@ryuenn3123/agentic-senior-core 4.3.2 → 4.3.4

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

@@ -3,153 +3,35 @@ id_prefix: ARCH
 domain: architecture
 priority: critical
 scope: all-tasks
-applies_to:
-  - backend
-  - frontend
-  - fullstack
-keywords:
-  - architecture
-  - arch
-  - separation
-  - concerns
-  - structure
-  - universal
+applies_to: [backend, frontend, fullstack]
+keywords: [architecture, arch, boundary, system]
 ---
 
-# Architecture - Separation of Concerns and Structure
+# Architecture Boundary
 
-> If a service imports transport concerns or raw persistence concerns directly, the architecture is already drifting.
-
-## 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.
-  - `docs/architecture-decision-record.md` (alias: `docs/Architecture-Decision-Record.md`) must exist.
-  - `docs/flow-overview.md` must exist.
-  - 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.
-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-001: Execution Rules
+1. Rely on ESLint/Linters for structural enforcement.
+2. Require README.md and docs/doc-index.md.
+3. Run `npm run validate` to enforce architecture invariants.
+4. Do not invent custom crypto, custom state management, or custom routing. Use standard libraries.
 
 ## 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.
+2. Detect drift before changing runtime choices, topology, public contracts, or core patterns.
+3. Direction changes require explicit user confirmation before applying changes.
 
 ## 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.
-
-## ARCH-013: Natural Implementation Pass
-
-1. Treat "human-readable" code as code that a maintainer can trace, test, and change safely. Do not optimize for looking hand-written at the expense of behavior.
-2. Write new code and refactors as a clear sequence of intent: validate the input, name the domain state, perform the operation, then return or report the outcome.
-3. Prefer early returns for invalid, empty, or unauthorized paths when they reduce nesting and make the happy path easier to follow.
-4. Keep functions focused on one responsibility, but do not create tiny helper chains unless the helper names a real domain condition, removes repeated logic, or makes the main flow easier to read.
-5. Avoid dense one-liners, nested ternaries, speculative classes, factories, interfaces, design patterns, and extra layers when direct code preserves the same guarantees.
-6. Match the local project style before introducing a new pattern. Do not make code generic enough to fit any product.
-7. Run a final naturalness pass before completion: domain names are specific, booleans expose state or permission, comments explain why only, edge cases are explicit, and simplification did not remove validation, error handling, fallbacks, accessibility, tests, security boundaries, or observability.
+2. Load global domain rules lazily based on touched scope.
+3. Do not create or load stack-specific governance adapters as the baseline.
+
+## ARCH-008: Backend Universal Principles
+1. No clever hacks.
+2. No premature abstraction.
+3. Readability over brevity.
+4. Keep backend and shared core modules clean.

package/.agent-context/rules/background-jobs.md

@@ -1,93 +1,17 @@
 ---
 id_prefix: JOB
 domain: background-jobs
-priority: high
+priority: medium
 scope: backend
-last_validated: 2026-05-17
-applies_to:
-  - backend
-  - fullstack
-keywords:
-  - background-jobs
-  - workers
-  - queues
-  - schedules
-  - poison-message
-  - backpressure
+applies_to: [backend, fullstack]
+keywords: [background-jobs, worker, cron, queue]
 ---
 
 # Background Jobs Boundary
 
-A background job is any code path that runs outside a synchronous user request: scheduled tasks, queued asynchronous work, long-lived consumers of a recurring stream, and one-shot operational tasks. The rules below treat these shapes as different. Vendor names that may appear in commentary (queue platforms, scheduler services, stream-processing runtimes) are not authority for this rule.
-
-## JOB-001: Pick the right job shape (Mandatory)
-
-1. Before adding a job, classify it: scheduled (time-driven, fires at intervals or on a calendar), queued (request-driven asynchronous follow-up to user action), recurring stream (continuous consumer of an event stream), or one-shot operational task (manually triggered or run-to-completion). Use the simplest shape that fits.
-2. Reject using one shape for everything. A scheduled task that polls a queue is not a queue worker. A queue worker is not a stream consumer. A one-shot operational task is not a permanent scheduled job.
-3. Reject "fire-and-forget" jobs without observability into success rate, retry rate, and lag. A job that the system cannot detect failing is not a job; it is a hope.
-
-## JOB-002: Job ownership and runbook (Mandatory)
-
-Every job, regardless of shape, must record the following before it ships:
-
-1. An owner (team or role) accountable for the job's success.
-2. An expected runtime budget under normal load.
-3. A documented failure outcome: what happens if the job fails partially, fails completely, runs late, or runs twice.
-4. A runbook entry, or platform-equivalent operational note, that names the alert thresholds, the recovery steps, and the data the operator needs to investigate a failure.
-
-A job that lacks any of the above is a defect waiting for an incident.
-
-## JOB-003: Idempotency (Mandatory)
-
-1. Every job must be idempotent at the job level: a job that ran partially and was retried, or that was scheduled twice for the same input, must converge to the same final state. The system must not double-charge, double-write, double-notify, or double-grant.
-2. Idempotency must be enforced on the side of the job that holds the durable record (the database row, the external API's idempotency key acceptance, the event-store dedup key), not only on the side that emits the trigger.
-3. The job must distinguish "I already did this" (success, no further work) from "the input changed" (treat as a new request) using a stable input identifier; a re-emission of the same logical work must collapse to a single committed effect.
-4. Reject jobs whose only protection against double-execution is "the queue is configured exactly-once". Treat queue delivery guarantees as best-effort and enforce idempotency in the application.
-
-## JOB-004: Long-running and durable execution (Mandatory)
-
-1. A long-running job must extend its lease, visibility timeout, or platform-equivalent ownership token while it is still doing useful work, so its mid-flight progress does not get re-dispatched to a second worker.
-2. A long-running job must checkpoint progress to durable storage at intervals that bound replay cost: a process crash must not require redoing more work than the platform's documented loss tolerance allows.
-3. A long-running job must handle graceful shutdown: when the runtime signals termination (deploy, scaling event, host eviction), the job must stop at the next checkpoint, mark its lease as relinquishable, and exit within the platform's drain window.
-4. Reject long-running jobs that hold an in-memory buffer with no checkpoint, that ignore graceful-shutdown signals, or that allow a duplicate worker to start when their lease expires without serializing on a durable lock.
-
-## JOB-005: Poison messages and dead letters (Mandatory)
-
-1. Every queue or stream consumer must define a maximum attempt count. After that count, the message must be moved to a dead-letter destination, not retried indefinitely.
-2. The dead-letter destination must be observable: an alert threshold on its size, an inspectable record per entry, and a documented human recovery path that takes the operator from "alert" to "decided to replay, edit, or discard".
-3. Replays out of the dead-letter destination must respect job-level idempotency: the original handler must not double-apply effects when a dead-letter message is replayed alongside an already-succeeded retry.
-4. Reject infinite retries on a poison input. Reject silent message drops with no dead-letter or audit trail. Reject dead-letter destinations that no human is alerted on.
-
-## JOB-006: Time, schedules, and fan-out (Mandatory)
-
-1. Schedule definitions and time-of-event fields must be stored in a timezone-unambiguous form (UTC for storage, with the original timezone retained as metadata when the schedule is meaningful in a local calendar). Naive local-time storage of a moment that crosses a daylight-saving transition is forbidden.
-2. Where a schedule applies to many entities (per-customer billing run, per-tenant report generation, per-device sync), the implementation must stagger fan-out with jitter so the entities do not all execute on the same instant; the platform's queue and downstream APIs see a smoothed load curve, not a thundering herd.
-3. Schedules that depend on a calendar (month-end, billing-cycle) must specify the resolution rule for ambiguous calendar dates (the 31st of a 30-day month, the leap day) at design time, not at the first failure.
-4. Reject schedules whose timezone is implicit. Reject coordinated fan-out that treats every entity as urgent at the same wall-clock instant.
-
-## JOB-007: Backpressure (Mandatory)
-
-1. A queue or stream consumer that cannot keep up must shed load, throttle producers, or expose its lag, not silently grow until memory or storage is exhausted.
-2. The consumer must expose its current lag, its rejection or shed rate, and its in-flight count as telemetry; the operator must be able to answer "is the consumer slow, the producer fast, or is the queue full?" without reading the queue directly.
-3. Where the producer is a user request, backpressure must be communicated synchronously to the user (a throttle, a delayed acknowledgement, a queued-for-later response with a tracking identifier), not silently absorbed and lost.
-4. Reject implementations where the only response to overload is "scale the worker pool"; scaling is a remediation, not a substitute for explicit backpressure.
-
-## JOB-008: Reject these bad habits
-
-1. Reject scheduled jobs that polling-loop through a database table that should have been a queue.
-2. Reject queue workers that bake business state into the queue payload because no durable record exists.
-3. Reject stream consumers that hold long-lived in-memory aggregates without a checkpoint and replay strategy.
-4. Reject "one-shot" operational tasks that have shipped to production three times; if a task is re-run regularly, it is a recurring job and needs the JOB-002 fields.
-5. Reject "the queue handles retries for us" as the entire retry strategy; pair it with idempotency and a dead-letter destination.
-
-## JOB-009: Citations and freshness
-
-Authority and background reading for the rules in this file:
-
-- IETF RFC 3339: authority for the wire shape of timezone-aware timestamps used in job payloads.
-- Cron expression specifications and the platform scheduler's documentation: authority for the schedule grammar in use; verify behavior on daylight-saving transitions and leap days against the platform's current major version, because behavior on these edge cases varies between schedulers and between versions of the same scheduler.
-- AWS Well-Architected Reliability Pillar (REL05) and Google SRE Workbook chapters on overload and addressing cascading failures: background reading on backpressure, dead-letter queues, and graceful degradation as deployment-architecture concerns.
-- Job-platform documentation for the runtime in use: authority for visibility-timeout semantics, lease extension, retry-with-backoff defaults, and dead-letter-queue conventions.
-
-Vendor-specific job platforms (queue services, stream processors, scheduler services) are illustrative implementations of the outcomes above; they are not authority. Use the platform-appropriate mechanism that exists in the deployed runtime.
-<!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->
+## JOB-001: Execution Rules
+1. All jobs must be idempotent.
+2. Offload heavy processing (>500ms) to background queues.
+3. Use dead-letter queues (DLQ) for failed jobs.
+4. Emit telemetry on job failure/success.
+5. Jobs must have timeouts and retry limits.

package/.agent-context/rules/config-and-flags.md

@@ -3,77 +3,14 @@ id_prefix: CFG
 domain: config-and-flags
 priority: high
 scope: backend
-last_validated: 2026-05-17
-applies_to:
-  - backend
-  - frontend
-  - fullstack
-keywords:
-  - configuration
-  - feature-flags
-  - kill-switch
-  - environment
-  - secrets
-  - rollout
+applies_to: [backend, frontend, fullstack]
+keywords: [configuration, feature-flags, environment, secrets]
 ---
 
-# Configuration and Feature Flags Boundary
+# Configuration Boundary
 
-Configuration is data that the application reads to decide how to run. Feature flags are configuration whose value is a decision about behavior, evaluated per request, per user, or per tenant. The two rules sets below treat them as different, because their lifetimes, audiences, and failure modes are different. Vendor names that may appear in commentary (configuration providers, feature-flag platforms, secret managers) are not authority for this rule.
-
-## CFG-001: Configuration sources (Mandatory)
-
-1. The application must read all configuration values from one of: process environment, runtime configuration injected by the deploy platform, a documented configuration file outside the source tree, or a secret manager. Constants embedded in source code are forbidden when the value is environment-specific (URLs, hostnames, credentials, region identifiers, tenant identifiers, model identifiers).
-2. The application must validate every configuration value at startup. A missing required value, a malformed value, or a value outside the documented range must abort startup with a readable error that names the field and the source. Lazy validation that surfaces in a request handler an hour later is forbidden.
-3. The application must distinguish "no configuration" from "configuration loaded with empty value"; the two cannot be the same code path. A missing key must abort startup; an explicit empty value is a configured choice.
-4. Configuration that influences security or correctness (allowed origins, signing keys, allow-lists, billing thresholds) must come from a controlled source the operator can audit. The application must record at startup which configuration source supplied the value, without printing the value itself when it is sensitive.
-5. Reject environment-specific constants in code (`if env === "prod"`, hard-coded production hostnames, production-only API endpoints behind a comment). Branch on capability flags or configuration values instead. Reject treating a build-time constant as a substitute for runtime configuration when the same artifact is shipped to multiple environments.
-
-## CFG-002: Secret handling (Mandatory)
-
-1. Secrets must be retrieved through the platform's secret manager, runtime injection, or environment variables sourced from a controlled secret store. Static secrets in source, in repository configuration, in container images, or in plaintext configuration files are forbidden.
-2. Secrets must not be logged, included in error responses, included in telemetry payloads, or embedded in any structured event. Identifiers that name the secret (key id, version, source) are acceptable; the secret value is not.
-3. Secret rotation must be a runtime event the application handles without redeploy on platforms that support it; on platforms that do not, the redeploy procedure must explicitly re-read secrets, not cache them across deploys.
-4. Reject treating a secret as a feature flag and a feature flag as a secret. Secrets and behavioral flags have different audit, rotation, and exposure rules; collapsing them violates both.
-
-## CFG-003: Feature flag taxonomy (Mandatory)
-
-1. Every feature flag must declare its type before it is used:
-   - Release flags: short-lived, gate the rollout of new code; removed after the rollout completes.
-   - Operational kill switches: long-lived, allow an operator to disable a code path during an incident; removed only when the gated code path is removed.
-   - Experiment flags: assign users into variants and feed the assignment into analytics; removed when the experiment concludes.
-   - Entitlement flags: gate a capability behind a permission, plan, license, or tenant attribute; live for the lifetime of the capability.
-2. The mechanism that evaluates each flag type may differ. Reject one mechanism that mixes release flags, kill switches, experiment flags, and entitlement flags without distinguishing them, because the right rollout, audit, and removal disciplines differ.
-3. Every flag must record: the flag's type, its owner, its removal criterion (concrete, measurable), and an expiry date. A flag past its expiry without a documented extension is technical debt, not a feature; the audit must surface it.
-
-## CFG-004: Flag evaluation safety (Mandatory)
-
-1. Every flag evaluation must define a safe default that the system uses when the flag service is unreachable, the value cannot be parsed, or the evaluation context is missing. The safe default must not enable destructive, billable, or irrecoverable behavior.
-2. Flag evaluation must not block a request on a remote call by default; the application must read from a locally cached value with bounded staleness, or the flag platform must run a sidecar with a documented refresh interval, so a flag-service outage cannot turn into a request-handler outage.
-3. The application must record the flag value used for a given request decision (in a structured event, not a free-text log) so the operator can answer, after the fact, "which variant did this user see?". The recorded value must not include any secret payload that the flag carries.
-4. Reject flag evaluations that have no safe default, that block synchronously on a remote call from a hot request path, or that cannot be reproduced in telemetry.
-
-## CFG-005: Environment branching (Mandatory)
-
-1. The application must not branch business logic on the name of the environment. `if env === "prod"` and its variants are forbidden; the correct branch is on a configuration value or a capability flag whose name describes the capability, not the environment that happens to enable it.
-2. Configuration profiles per environment are acceptable when they are explicit data (a `production.yaml` file the deploy platform selects, a parameter store path scoped per environment) rather than embedded conditionals in code.
-3. Reject conditionals that quietly disable safety checks in non-production environments and re-enable them in production. The check belongs in code; configuration controls thresholds, allow-lists, or capability flags, not whether the check exists.
-
-## CFG-006: Reject these bad habits
-
-1. Reject configuration values that exist only as comments in source ("set this to your production URL").
-2. Reject feature flags older than their declared expiry that nobody owns.
-3. Reject "stub the flag for tests" patterns that bypass the flag mechanism in non-test code paths.
-4. Reject configuration validators that only run in development.
-5. Reject deploy procedures that ship a new mandatory configuration field without a deploy-ordering note that pairs the new field with the code that requires it.
-
-## CFG-007: Citations and freshness
-
-Authority sources for the rules in this file:
-
-- The Twelve-Factor App, Section III "Config": authority for the principle that environment-specific configuration is data, not source.
-- OWASP ASVS sections on secret management and credential storage: authority for what counts as a secret, how it must be stored, and how it must not be logged or transmitted.
-- Continuous-delivery and feature-flag literature on flag taxonomy and lifecycle (release flags vs operational kill switches vs experiment flags vs entitlement flags): authority for the multi-type discipline above.
-
-Vendor-specific configuration providers, secret managers, and feature-flag platforms are illustrative implementations of the outcomes above; they are not authority. Use the platform-appropriate mechanism that exists in the deployed runtime.
-<!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->
+## CFG-001: Execution Rules
+1. Inject secrets via environment variables.
+2. Never store secrets in code. Use .env.example for templates.
+3. Use feature flags for incremental rollouts.
+4. Validate config shapes at startup. Fail fast if invalid.

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

@@ -3,72 +3,16 @@ id_prefix: DATA
 domain: database-design
 priority: high
 scope: data
-last_validated: 2026-05-17
-applies_to:
-  - backend
-  - fullstack
-keywords:
-  - database-design
-  - data
-  - design
-  - boundary
-  - reject
-  - these
+applies_to: [backend, fullstack]
+keywords: [database-design, data, schema]
 ---
 
 # 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.
-
-## 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
-
-## DATA-002: Backend data access rules
-
-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.
-
-## DATA-003: Money and time
-
-1. Monetary amounts must be stored as a fixed-precision integer in the smallest unit of the currency (for example, the smallest indivisible unit defined by the currency's standard subdivision), or as a decimal type with explicit precision and scale matched to the currency's accounting requirements. The chosen representation must be recorded in the data model docs alongside the column it applies to.
-2. Floating-point types (`float`, `double`, `real`, or platform equivalent) are forbidden for monetary columns. Floating-point arithmetic introduces rounding artifacts that compound across aggregation, settlement, and reconciliation; the cost of correcting them after the fact is higher than the cost of using the right type up front.
-3. Currency-bearing columns must record the currency code on the same row, not implicitly through the column or the table; an amount without a stored currency is not a quantity, it is a defect waiting for a multi-currency feature.
-4. Timestamps that represent a real-world moment must be stored in UTC. Timezone information that the user or the source system supplied may be retained as separate metadata when the local calendar is meaningful, but the canonical instant is UTC.
-5. Naive timestamp storage (a timestamp type with no timezone offset, or a string without an explicit timezone designator) is forbidden for any field that represents a real-world moment. Timestamps that record a wall-clock value (a recurring event in a local calendar, a scheduled time-of-day) are not real-world moments and may use a date or local-time type, but the choice must be explicit, not the default that fell out of the migration tool.
-6. Conversion to local time must occur only at presentation boundaries (formatted output, user-facing UI, exported reports). Application logic, queries, and inter-service messages must operate on the UTC value.
-7. Reject floating-point types for monetary columns. Reject naive timestamps for fields that represent a real-world moment. Reject ambiguous "string of digits" amount columns when the database offers a precise numeric type.
-
-## DATA-004: Concurrency and write conflicts
-
-1. Resources that can be edited by independent owners (the same row reachable by multiple users, the same aggregate reachable by multiple sessions, the same record reachable by overlapping batch jobs) must carry an optimistic-concurrency token: a monotonic version column, an `ETag`-style content hash, an updated-at timestamp combined with a precondition, or platform-equivalent compare-and-set primitive.
-2. The token must travel with the read response so the next write can submit it as a precondition. A write that lacks the token must be rejected, not silently treated as the latest version.
-3. The conflict response must be explicit and machine-actionable. For HTTP surfaces, an HTTP 409 response is the canonical signal; the response body must include the current state of the resource (or a stable reference the caller can fetch to retrieve it) and a conflict reason the caller can render to the user. The response shape must be documented in the API contract.
-4. The conflict-resolution strategy must be recorded per resource: prompt the user to merge, retry on a fresh read, drop the change, or escalate to a server-side merge function. "Retry forever" is not a strategy; it must have a bounded attempt count and a documented fallback.
-5. For workflows where overlapping edits are expected (collaborative documents, multi-step forms with parallel reviewers), use a change-tracking model that captures intent (operations, deltas, change requests) rather than only final-state writes; final-state writes against shared resources without a token are the failure mode this rule prevents.
-6. Reject implicit last-write-wins on shared mutable resources. Reject "we will solve it when conflicts happen" as a substitute for an explicit token. Reject conflict responses that do not include the current state and a reason the caller can act on.
-
-## DATA-005: Citations and freshness
-
-Authority sources for the additions in [REF:DATA-003] and [REF:DATA-004]:
-
-- ISO 4217: authority for currency codes and the standardized minor-unit count per currency. Verify the current edition for currency additions and minor-unit changes; the standard is updated periodically.
-- ISO 8601 (and IETF RFC 3339 as the wire-shape profile): authority for timezone-aware timestamp representations.
-- IETF RFC 9110 sections on conditional requests and the `412 Precondition Failed` and `409 Conflict` semantics: authority for the HTTP-side conflict-response shape referenced in [REF:DATA-004].
-- IETF RFC 7232: authority for `ETag` and `If-Match` precondition mechanics on HTTP surfaces.
-
-Vendor-specific decimal types, time-handling libraries, and conflict-detection frameworks are illustrative implementations of the rules above; they are not authority. Use the platform-appropriate mechanism that exists in the deployed runtime.
-<!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->
+## DATA-001: Execution Rules
+1. Avoid N+1 queries. Use eager loading or batching.
+2. Paginate growable datasets.
+3. Multi-table mutations must run inside transactions.
+4. Monetary amounts must be integer (minor units) or exact decimal. NO floats.
+5. Store real-world timestamps in UTC. NO naive timestamps.
+6. Use optimistic concurrency tokens (ETag/version) for shared mutable resources.

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

@@ -3,68 +3,15 @@ id_prefix: DOCK
 domain: docker-runtime
 priority: high
 scope: infra
-applies_to:
-  - backend
-  - frontend
-  - fullstack
-keywords:
-  - docker-runtime
-  - dock
-  - docker
-  - runtime
+applies_to: [backend, frontend, fullstack]
+keywords: [docker-runtime, docker, runtime]
 ---
 
-# Docker Runtime Strategy (Dynamic Generation Required)
+# Docker Runtime Boundary
 
-Use this rule when Docker is enabled in project context.
-
-## 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.
+## DOCK-001: Execution Rules
+1. ALWAYS perform Live Research / Web Search for latest official Docker documentation before writing configuration.
+2. Keep Dev and Prod stages separate.
+3. Use minimal trusted base images. Avoid running as root in Prod.
+4. Never bake secrets into image layers.
+5. Define explicit healthchecks in production compose files.

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

@@ -3,43 +3,13 @@ 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
+applies_to: [backend, frontend, fullstack]
+keywords: [efficiency, dependency]
 ---
 
-# Dependency and Tooling Boundary
+# Dependency Boundary
 
-## DEP-001: Latest-Compatible-First Rule
-
-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.
-
-## DEP-002: Before adding or recommending a dependency
-
-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
-
-## DEP-003: Framework and offline decision boundaries
-
-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.
+## DEP-001: Execution Rules
+1. ALWAYS perform Live Research / Web Search for official library docs before installation.
+2. Choose the latest stable compatible version.
+3. Do not blindly avoid dependencies if they solve complex domains securely (e.g., Auth, Crypto, Accessibility).