@ryuenn3123/agentic-senior-core 4.0.3 → 4.2.0

package/.agent-context/prompts/compact-natural-mode.md

@@ -0,0 +1,100 @@
+# Compact Natural Mode
+
+Status: active default response contract.
+
+Use this prompt for final user-facing replies after the task-specific rule, prompt, checklist, and validation work is complete.
+
+## Purpose
+
+Write the smallest complete answer that still lets the next developer act correctly.
+
+Compact means high signal. It does not mean broken grammar, dialect, clipped fragments, or hiding evidence.
+
+## Always Remove
+
+- greetings, affirmations, and repeated restatements
+- narration about what you are about to do
+- generic closing offers
+- padding paragraphs that add no new technical content
+- repeated summaries of the same decision
+
+## Always Preserve
+
+- exact commands
+- exact file paths and line numbers
+- exact error messages, assertions, exit codes, and stack-trace highlights
+- validation status, including tests not run
+- assumptions, scope qualifiers, blockers, risks, and next actions
+- destructive-operation warnings
+- breaking changes and migration notes
+
+## Task Shapes
+
+Use natural prose inside these shapes. Omit fields that do not apply, except safety fields.
+
+Debug/root cause:
+
+```text
+Root Cause: <one sentence>
+Evidence: <exact error, command output, or file:line>
+Fix: <exact command or code direction>
+Next: <verification step>
+```
+
+Test failure:
+
+```text
+Failed: <test name>
+Expected/Got: <value> / <value>
+At: <file:line>
+Evidence: <exact assertion or root error>
+Fix direction: <one sentence>
+```
+
+Code review finding:
+
+```text
+[critical|warn|nit] <file>:<line> - <concern>. <requested change>
+```
+
+Implementation/refactor summary:
+
+```text
+Changed: <what changed>
+Reason: <why>
+Behavior: <changed, unchanged, or not verified>
+Validation: <what ran or was not run>
+Risk: <only if relevant>
+```
+
+Destructive command:
+
+```text
+WARNING: <what this destroys and whether it is reversible>
+Command: <exact command>
+Precondition: <what must be true before running>
+```
+
+Security finding:
+
+```text
+Severity: <critical|high|medium|low>
+Class: <vulnerability class>
+Location: <file:line>
+Impact: <who or what is affected>
+Evidence: <exact code, behavior, or command output>
+Remediation: <specific fix direction>
+Validation: <how to prove it is fixed>
+```
+
+Planning/architecture may be longer. Keep decision, rationale, alternatives, tradeoffs, assumptions, and open questions visible.
+
+## Second-Pass Check
+
+Before finalizing:
+
+1. Remove any sentence that adds no new technical content.
+2. Confirm mandatory evidence atoms remain exact.
+3. Confirm assumptions and validation gaps are visible.
+4. Confirm the answer has a decision or next action when the user asked for one.
+5. Confirm the tone is natural professional writing.

package/.agent-context/prompts/init-project.md

@@ -46,6 +46,7 @@ If the user specifies a framework, runtime, or architecture constraint, the agen
    - Set up configuration, validation, error handling, observability, health checks, and persistence only when they fit the approved runtime and project scope.
    - Every file must follow [naming conventions](../rules/naming-conv.md).
    - Every module must follow [architecture.md](../rules/architecture.md).
+   - New code must pass the natural implementation pass in [architecture.md](../rules/architecture.md): start with the simplest correct flow, add complexity only when the requirement or repo evidence needs it, and do not add files or layers for small tasks.
    - Every dependency must be justified per [efficiency-vs-hype.md](../rules/efficiency-vs-hype.md).
    - Use official framework setup commands or canonical starter flows when they produce newer, better-supported dependency defaults than manual package assembly.
    - Do not assemble a framework project from scratch by habit when official setup commands create the supported structure. Manual assembly is allowed only for tiny prototypes, educational demos, unusual repo constraints, or a documented architecture reason.

package/.agent-context/prompts/refactor.md

@@ -20,6 +20,7 @@ Before editing:
 Refactor rules:
 - Improve clarity, boundaries, naming, validation, error handling, tests, and docs.
 - Prioritize maintainability over compressed one-liners.
+- Apply the natural implementation pass from architecture.md: keep the main flow traceable, use early returns where they reduce nesting, and avoid helper chains that only make the code look abstract.
 - Do not choose a stack, framework, library, or topology from offline assumptions.
 - Keep module boundaries explicit and project-specific.
 - Split large files when the split makes the flow easier to understand.

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

@@ -27,6 +27,7 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 - [ ] No premature abstraction (base classes/util layers created only after repeated stable patterns)
 - [ ] Readability over brevity for maintainability
 - [ ] Complexity budget was applied: equivalent behavior uses fewer moving parts without losing validation, error handling, fallbacks, accessibility, tests, or security boundaries.
+- [ ] Natural implementation pass was applied: the main flow is traceable, names are domain-specific, helpers carry real meaning, and compact code did not hide safeguards.
 - [ ] Controllers, route handlers, and transport adapters do not contain business policy, raw queries, or cross-resource orchestration.
 - [ ] Services or use cases own business flow, transaction boundaries, and mutation safety.
 - [ ] Repositories or adapters own persistence/external IO details without hiding business decisions.

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

@@ -3,6 +3,7 @@ id_prefix: API
 domain: api-docs
 priority: high
 scope: backend
+last_validated: 2026-05-17
 applies_to:
   - backend
   - fullstack
@@ -61,6 +62,7 @@ keywords:
 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.
+9. Versioning, deprecation, and support-window obligations for any public surface live in `api-versioning.md`; load it together with this rule when authoring or reviewing a versioned contract change [REF:VER-001].
 
 ## API-006: Human Writing Standard (Mandatory)
 
@@ -107,3 +109,15 @@ keywords:
 3. Separate facts from assumptions explicitly.
 4. End major explanations with a clear next action.
 5. Read the text out loud before shipping. If it sounds robotic, rewrite it.
+
+## API-012: Idempotency as Runtime Invariant
+
+1. Side-effect-producing endpoints (a `POST` that creates a resource, a `PUT` or `PATCH` that mutates a resource, a request that issues a charge, a request that triggers a downstream notification) must accept an idempotency identifier on retry. The identifier is a caller-supplied key on each logical attempt; the producer commits the effect once and stores enough state to recognize the same key.
+2. The server must return the original response on duplicate submissions of the same idempotency identifier within a documented retention window. The retention window must be long enough to cover the platform's worst-case retry interval (network retry plus client-side retry plus operator-driven replay) and is recorded in the API contract per endpoint, not picked at random per call site.
+3. The idempotency identifier scope must be documented: per caller, per resource, per tenant, or globally. A scope mismatch (one tenant's key colliding with another's) is a data-leak bug, not a load-balancing edge case.
+4. The contract must distinguish three duplicate outcomes: replay-of-same-success (return the original 2xx response unchanged), replay-after-permanent-failure (return the original 4xx response unchanged), and replay-with-different-payload-under-same-key (reject with a clear error so the caller does not silently overwrite the recorded result with a new request body).
+5. Storage for idempotency state must be durable across process restarts; in-memory caches are not sufficient on multi-instance deployments. The store may be the same database, a separate key-value store, or a platform-equivalent dedup layer, provided durability and lookup latency are recorded.
+6. Reject "the database's primary-key constraint will catch duplicates" as a substitute for an idempotency layer; primary-key collisions surface as 5xx-shaped errors that callers retry, which makes the problem worse.
+7. Reject silent acceptance of duplicate side-effect-producing requests without a key. A caller that retried without a key gets a 400-class response that names the missing key, not a second charge.
+8. Authority for the rules above includes IETF RFC 9110 for HTTP method idempotency semantics and successor specifications for the `Idempotency-Key` request header where the platform standardizes one. Verify the current standardization status at audit time, because the header has been a draft and an RFC at different points in its history.
+<!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->

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

@@ -0,0 +1,93 @@
+---
+id_prefix: VER
+domain: api-versioning
+priority: high
+scope: api
+last_validated: 2026-05-17
+applies_to:
+  - backend
+  - fullstack
+keywords:
+  - api-versioning
+  - deprecation
+  - breaking-changes
+  - support-window
+  - sunset
+  - migration
+---
+
+# API Versioning Boundary
+
+A public API surface is a contract with callers the producer does not control. Versioning safety is the property that the producer can evolve the contract without silently breaking those callers, and that callers can recognize and respond to evolution before it forces an outage. Vendor names that may appear in commentary (API gateways, contract registries, deprecation-tracking platforms) are not authority for this rule.
+
+## VER-001: Single versioning strategy per surface (Mandatory)
+
+1. Each public API surface (a service's HTTP endpoints, a service's RPC methods, a published event schema, a CLI's command shape, a published SDK) must adopt one versioning strategy and apply it consistently. Acceptable strategies include URL-path versioning, header-based versioning, content-negotiation, schema-driven versioning where the schema carries the version, and date-based versioning. The choice belongs to the surface, not to the developer of the moment.
+2. Reject mixed strategies on the same surface (path-versioned for some endpoints and header-versioned for others; date-versioned for queries and unversioned for mutations). The mix forces every caller to learn two rules where one is sufficient.
+3. The strategy and its current supported version range must be documented in the surface's contract documentation, not inferred from example URLs or sample headers.
+
+## VER-002: Define breaking and non-breaking changes (Mandatory)
+
+1. The following are breaking changes regardless of strategy:
+   - Removing or renaming a request field, a response field, an endpoint, an RPC method, an event type, or a CLI command.
+   - Tightening request validation (a value previously accepted is now rejected; a previously optional field is now required).
+   - Changing the default value or default behavior of an existing field, parameter, or operation.
+   - Changing the type, units, encoding, or semantic meaning of an existing field.
+   - Changing the documented error semantics (status code, error code, or error shape) of an existing endpoint.
+2. The following are non-breaking changes:
+   - Adding a new optional request field with a documented default behavior when the field is absent.
+   - Adding a new response field that older clients can ignore, on a surface whose contract permits unknown fields (most modern HTTP and event surfaces do; verify per surface).
+   - Adding a new endpoint, RPC method, event type, or CLI command.
+   - Adding a new optional header with a documented absent-default.
+3. Any change that is breaking by the definition above must use the surface's versioning strategy or wait for the next major version. Reject silent breaking changes (a field type narrowed without a version bump; a status code changed without a version bump).
+
+## VER-003: Deprecation discipline (Mandatory)
+
+1. A deprecation announces, while the deprecated path is still functional, that callers must migrate. Deprecation must include all of the following before the deprecated path can be removed:
+   - A documented sunset date or replacement-criterion that callers can plan against.
+   - In-band signaling on the deprecated path, using the platform's standardized mechanism where one exists. For HTTP surfaces, RFC 9745 (the `Deprecation` header) and RFC 8594 (the `Sunset` header) are the current standardized mechanisms; signal with both where the platform and clients support them, and document the in-band signal in the contract documentation. Adoption of these specifications is uneven, so out-of-band communication is acceptable when the in-band channel is unavailable, provided the out-of-band path is documented and reaches affected callers.
+   - A migration guide published in the same release that begins deprecation, that names the replacement and shows at least one example transformation per use case the deprecated path supported.
+   - Telemetry that tracks remaining traffic on the deprecated path, broken down by caller identity where the surface supports identifying callers, so the producer knows when removal is safe.
+2. Reject silent removal of an endpoint, field, or method that has not gone through deprecation. "We checked our analytics and nobody used it" is not deprecation; it is an unannounced breaking change with extra steps.
+3. The sunset date must respect the surface's documented support window (VER-004); a sunset announced today and effective tomorrow is not a sunset, it is a removal.
+
+## VER-004: Support windows (Mandatory)
+
+1. Each public API surface must publish an explicit support window: how long after a new major version ships will the previous major version continue to receive bug fixes, security fixes, and uptime guarantees. The window must be expressed in calendar time (months or years), not in subjective terms.
+2. The producer must continue to operate prior versions within the support window even when the producer prefers callers had migrated. Removing a still-supported version is a breach of the published contract.
+3. End-of-life must be announced before the support window expires, with sufficient lead time for callers to migrate. The lead time required depends on the caller population (an internal service may migrate in a sprint; a public SDK with mobile-app callers may need a year because of app-store update cycles); the producer must document the assumption.
+4. Reject "we will remove it when we feel like it" as a support policy. Reject removing an endpoint, field, or method while it is still inside its published support window.
+
+## VER-005: Additive evolution as default (Mandatory)
+
+1. The default response to a feature request that touches an existing surface is to evolve additively: add a new optional field, a new endpoint, a new optional behavior triggered by an explicit opt-in. Reach for a new major version only when additive evolution costs more than client migration would cost (a fundamental shape change, a security correction that cannot coexist with the old shape, a deprecated dependency removal that callers must follow).
+2. A new major version is itself a contract that incurs all of VER-001, VER-002, VER-003, and VER-004; it is not a license to ship unannounced breaking changes under a new path.
+3. Reject `/v2/` (or platform-equivalent) path forks that duplicate the previous version's codebase without a deprecation telemetry plan, a sunset date for the prior version, and a migration guide. A new path without these is two codebases the producer must maintain in parallel forever.
+4. The producer must not run a `/v1/` and a `/v2/` indefinitely on the same surface in the absence of a sunset plan; that pattern doubles operational cost and dilutes the contract.
+
+## VER-006: Compatibility testing (Mandatory)
+
+1. Every release that touches a public surface must run a compatibility check against the surface's previous supported versions: previously valid requests still validate, previously valid responses still parse against published schemas, previously documented error shapes still surface for the same error conditions.
+2. The compatibility check must run in CI, not as a manual pre-release step. Reject "we test compatibility manually before release"; manual compatibility checks miss regressions in less-trafficked endpoints.
+3. The compatibility check's failure must block the release, not file a follow-up ticket.
+
+## VER-007: Reject these bad habits
+
+1. Reject changes that are breaking by VER-002 but ship without a version bump or a deprecation cycle.
+2. Reject deprecation banners in release notes that have no in-band signal on the deprecated path.
+3. Reject sunset dates that are not enforced; a producer who keeps the deprecated path alive past sunset trains callers to ignore future sunsets.
+4. Reject `/v2/` forks of an existing surface that the producer cannot show a migration plan for.
+5. Reject contract documentation that lists endpoints without naming the version they belong to.
+
+## VER-008: Citations and freshness
+
+Authority sources for the rules in this file:
+
+- IETF RFC 9745: standardized HTTP `Deprecation` response header for in-band deprecation signaling. Adoption is uneven across clients and intermediaries, so pair with out-of-band documentation.
+- IETF RFC 8594: standardized HTTP `Sunset` response header for in-band sunset-date signaling. Same adoption caveat as RFC 9745.
+- IETF RFC 9457: problem-detail responses for HTTP errors; authority for keeping error semantics stable across versions.
+- OpenAPI Specification (current major version): authority for declaring HTTP surface versioning in machine-readable form when the surface uses HTTP.
+- AsyncAPI Specification (current major version): authority for declaring event-driven surface versioning when the surface publishes events.
+
+Vendor-specific API gateways, contract registries, and deprecation-tracking platforms are illustrative implementations of the rules above; they are not authority. The mechanism is platform-specific; the contract obligations above are not.
+<!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->

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

@@ -143,3 +143,13 @@ keywords:
 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.

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

@@ -0,0 +1,93 @@
+---
+id_prefix: JOB
+domain: background-jobs
+priority: high
+scope: backend
+last_validated: 2026-05-17
+applies_to:
+  - backend
+  - fullstack
+keywords:
+  - background-jobs
+  - workers
+  - queues
+  - schedules
+  - poison-message
+  - backpressure
+---
+
+# 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. -->

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

@@ -0,0 +1,79 @@
+---
+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
+---
+
+# Configuration and Feature Flags 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. -->

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

@@ -3,6 +3,7 @@ id_prefix: DATA
 domain: database-design
 priority: high
 scope: data
+last_validated: 2026-05-17
 applies_to:
   - backend
   - fullstack
@@ -40,3 +41,34 @@ Use the data store, ORM, migration tool, and query style already chosen by the p
 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. -->

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

@@ -3,6 +3,7 @@ id_prefix: FE
 domain: frontend-architecture
 priority: high
 scope: ui
+last_validated: 2026-05-17
 applies_to:
   - frontend
   - fullstack
@@ -107,6 +108,14 @@ Load this rule for UI-facing work. Keep the loaded surface small.
 4. Keep component states recognizable across hover, focus, loading, success, empty, and error.
 5. Do not let repeated surfaces share one visual treatment by habit; repetition needs a product reason.
 
+## FE-012: Data State Surface
+
+1. Every data-displaying surface must explicitly handle, with distinct UI, the period before any data has arrived for the first time, the case where the result set is empty by query or by absence, the case where prior data is visible while new data fetches in the background, recoverable error, and limited-connectivity or cached-fallback when the product operates outside continuous network coverage.
+2. The surface must not collapse multiple data states into a single generic spinner, a single generic empty illustration, or a single generic error message; each state carries different operator and user information and must be distinguishable at a glance.
+3. Do not treat a stale-while-revalidate refresh as a loading state; show the prior data with a visible freshness indicator and update in place when the new result arrives.
+4. Status changes between these states must be announced to assistive technology through the platform's accessible-status mechanism, per WCAG 2.2 status-message guidance, so non-visual users learn that the surface moved from loading to populated, populated to empty, or populated to error.
+5. Reject "spinner everywhere" as the default UI for any non-trivial data surface. Reject empty states that look identical to error states. Reject error states that do not name a recovery path.
+
 ## FE-013: Background and Wallpaper Discipline
 
 1. Background lines, grids, scanlines, noise, glows, blobs, abstract logos, calibration marks, and decorative geometry are invalid as wallpaper.
@@ -132,3 +141,29 @@ Load this rule for UI-facing work. Keep the loaded surface small.
 
 1. Use component kits or headless primitives for behavior and accessibility when they fit. Replace library-default visual language with project-specific composition, tokens, motion, state treatment, and morphology.
 2. Keep design-intent flexible: lock user goals, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component skins, candidate signature moves, and external website inspiration flexible until evidence or approval locks them. Convert references into product-fit rules; do not copy layout, palette, component skin, brand posture, or visual metaphor.
+
+## FE-017: Interactivity Priority
+
+1. Components that require client-side state, event handling, or interactive behavior must be the smallest unit that genuinely needs them. Wrapping, layout, narrative, and content-presentation components must remain server-rendered or static unless they themselves manage state or handle events.
+2. The interactive boundary must be drawn deliberately. Promoting a wrapper to client-side just to host a deeper child's interactivity is a defect.
+3. Use the platform's primitive for interactivity-priority hints (component-level interactivity boundaries, partial hydration, islands, or the framework equivalent) rather than a global default that hydrates everything.
+4. Operationally, measure responsiveness through Interaction to Next Paint (INP) or the platform's current Core Web Vitals threshold; a regression in INP that originates from over-eager interactivity is a defect, not a runtime cost to accept.
+5. Reject "make the whole page interactive so this one button works". Reject promoting a layout component to interactive without a recorded reason. Reject defaulting to a heavyweight client-side runtime when the surface is read-only.
+
+## FE-018: Internationalization as Layout
+
+1. Direction-sensitive spacing, alignment, and positioning must use direction-agnostic properties: CSS logical properties (`margin-inline-start`, `padding-block-end`, `inset-inline`, `border-inline-end`) or the framework or design-token equivalent. Physical-direction properties (`margin-left`, `padding-right`, `left`, `border-right`) are forbidden in shared layout code that may render in any locale.
+2. Icons must be classified at design time as direction-conveying (arrows, send/forward, undo/redo, slider handles, chevrons that imply navigation) or object-representing (a magnifying glass, a clock face, a brand mark). Direction-conveying icons must mirror with layout direction; object-representing icons must not. Decisions must be recorded in the icon system, not improvised per use.
+3. Plan a documented text-expansion budget for the project's target locales: short labels in some languages expand by 30 to 100 percent versus English, and the layout must absorb that growth without truncation, overflow, or breaking visual hierarchy. Record the assumed budget per surface and verify representative long-string fixtures during review.
+4. Bidirectional content (mixed left-to-right and right-to-left runs in a single string) must use the platform's bidi isolation primitive so a single embedded token cannot reorder surrounding content.
+5. Reject hardcoded physical-direction properties in shared codebases. Reject icon mirroring decisions left to per-component improvisation. Reject "we will fix it when we localize" as a substitute for a documented expansion budget.
+
+## FE-019: Theme as Context
+
+1. A theme switch is a change in lighting and surface model, not a color inversion. The same brand color does not produce the same perceptual result against a high-luminance surface as against a low-luminance surface; tokens must be re-derived per theme, not algebraically inverted.
+2. Elevation and depth must be expressible without depending on drop-shadows alone. Drop-shadows lose contrast at low surface luminance; depth tokens must combine surface-color shifts, border treatments, or platform-equivalent material cues so the elevation hierarchy remains legible across themes.
+3. Brand colors carried across themes must be individually verified against the active theme's contrast floor. Two colors with identical chroma can pass contrast on one theme and fail on another; per-theme verification is mandatory and cannot be substituted with a single light-mode test.
+4. Theme tokens must include explicit mappings for status (success, warning, error, info), focus-visible, and disabled states per theme. A token that exists only on one theme is incomplete.
+5. Reject color inversion as a substitute for a re-derived theme. Reject reliance on drop-shadows as the sole elevation cue. Reject deferring per-theme contrast verification to runtime.
+6. Authority for the perceptually-uniform color reasoning above is illustrative across modern color-science work; the OKLCH color space is one example of a perceptually-uniform space and may be used to express tokens, but it is not required. The universal fallback for delivery is sRGB; on platforms or surfaces where wide-gamut delivery is supported and verified, wider color spaces may be used. Verify the platform's current color-management capabilities at audit time.
+<!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->