@ryuenn3123/agentic-senior-core 4.0.2 → 4.1.0

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

@@ -0,0 +1,78 @@
+---
+id_prefix: RES
+domain: resilience
+priority: critical
+scope: backend
+last_validated: 2026-05-17
+applies_to:
+  - backend
+  - fullstack
+keywords:
+  - resilience
+  - timeout
+  - retry
+  - deadline
+  - degradation
+  - backpressure
+---
+
+# Resilience Boundary
+
+The system must remain useful when a dependency is slow, partial, or unavailable. Resilience is the property that the user-facing operation either completes within an agreed budget, fails fast with a clear outcome, or runs in a documented degraded mode; it is not the absence of failure. Vendor names and library names that may appear in commentary (timeout libraries, service meshes, adaptive-concurrency runtimes) are not authority for this rule.
+
+## RES-001: Timeouts and deadlines (Mandatory)
+
+1. Every outbound network or inter-process call must carry an explicit timeout derived from the user-facing operation's worst-acceptable latency. Library defaults and "no timeout" are not acceptable.
+2. The timeout must be smaller than the upstream caller's remaining latency budget. A request handler that has 800 ms of remaining budget must not issue a downstream call configured to wait 5 seconds.
+3. The system must propagate the caller's remaining deadline downstream so a downstream operation cannot continue past the upstream's expiration. If the platform exposes a deadline header or a context cancellation primitive, use it; otherwise, transmit the remaining budget as an explicit field on the call.
+4. Connect, read, and idle timeouts must be set independently. A combined "request timeout" that hides which phase exceeded the budget makes failure analysis ambiguous.
+5. Reject reliance on default timeouts. Reject "infinite" or platform-maximum timeouts on user-facing call paths. Reject configuring a downstream timeout larger than the upstream caller's remaining budget.
+
+## RES-002: Retries (Mandatory)
+
+1. Retries are allowed only on operations that are idempotent on the target, or on operations that carry an idempotency identifier the target honors within a documented retention window.
+2. Retries must use exponential backoff with jitter and a documented attempt cap. Fixed-interval retries are forbidden because they synchronize callers during incidents.
+3. Each retry must inherit the caller's remaining deadline; the sum of attempts plus backoff must not exceed the original budget.
+4. Retries must distinguish retriable failures (transient network, explicit retry-after, documented `5xx` semantics) from non-retriable failures (validation, authorization, business-rule rejection); non-retriable failures must surface immediately without consuming retry budget.
+5. Reject retries on non-idempotent writes that lack an idempotency identifier on the target. Reject retry storms: any pattern where many callers retry on the same schedule, without jitter, and without a global cap, is a defect even if each caller is locally well-behaved.
+
+## RES-003: Failing fast on unhealthy dependencies (Mandatory)
+
+1. When a dependency's failure rate, latency, or queue depth indicates it cannot serve traffic within the user-facing latency budget, the calling component must shed load on that dependency rather than continue to issue calls that will time out.
+2. Load shedding is an outcome, not a named pattern. The system may achieve it through any mechanism appropriate to the platform: a service mesh fault-tolerance policy, an adaptive-concurrency limiter, an in-process state machine that rejects calls during a recovery window, or a rate limiter informed by health probes. Choose what the platform supports; do not write a custom mechanism when the platform provides one.
+3. The shedding component must emit a telemetry event when it transitions between healthy, degraded, and shedding states, so an operator can correlate user impact with the decision to shed.
+4. The shedding component must have a documented recovery path: how it re-admits traffic to the dependency, how it confirms the dependency is healthy, and how it bounds the rate of recovery to avoid a thundering herd.
+5. Reject open-loop retry behavior against an upstream that has been unhealthy for longer than its documented recovery window. Reject "fail open" defaults on security-relevant calls (authorization, license enforcement); those must fail closed and the user-facing impact must be a documented degraded mode, not silent permission.
+
+## RES-004: Dependency isolation (Mandatory)
+
+1. Independent dependencies must use independent resource pools (connection pools, thread pools, semaphore quotas, or platform-equivalent admission control) so the saturation of one upstream cannot exhaust the pools used by another.
+2. The size of each pool must be derived from the dependency's documented capacity and the caller's latency budget, not from a default.
+3. The system must expose the in-flight count, the queue depth, and the rejection count for each pool as telemetry, so an operator can distinguish "dependency slow" from "caller's pool exhausted".
+4. Reject sharing one global pool across unrelated downstream calls when the platform supports separation. Reject silent unbounded queueing in front of a saturated pool; bounded queues with explicit rejection are mandatory.
+
+## RES-005: Graceful degradation (Mandatory)
+
+1. For each dependency, the implementation must answer one question explicitly in code or in a runbook: "what does the caller still do for the user when this dependency is unavailable?" A generic catch-all error response is not an answer.
+2. Acceptable degraded behaviors include: serving a cached or older version of the data with a freshness indicator, returning a partial result with the unavailable section labelled as such, queueing the request for later processing with a documented user-visible acknowledgement, or refusing the operation with a clear error that names the unavailable subsystem.
+3. The user-facing error path must distinguish "we cannot do this right now, retry later" from "we will not do this, do not retry"; clients reading these responses act differently on the two.
+4. Degraded behavior must be observable: a request served from a fallback path must emit telemetry that records which fallback fired, why, and how stale or partial the result was.
+5. Reject silent degradation. A response that hides a fallback from the caller, or that omits a stale-data marker when the data is stale, is a defect.
+
+## RES-006: Backpressure across producers and consumers (Mandatory)
+
+1. Any boundary between an unbounded producer (user requests, upstream events, ingestion stream) and a bounded consumer must apply backpressure: shed load, throttle the producer, or expose lag back to the producer. Silent unbounded growth of an in-memory or on-disk queue is forbidden.
+2. The boundary must expose its current lag, drop rate, and rejection reason as telemetry, so an operator can choose between scaling the consumer, slowing the producer, or shedding low-value traffic.
+3. Reject "queue grows until OOM" as an acceptable failure mode. Reject "we will scale later" as a substitute for explicit backpressure on a path that already takes user traffic.
+
+## RES-007: Citations and freshness
+
+Authority and background reading for the rules in this file:
+
+- AWS Well-Architected Framework, Reliability Pillar (REL05 and surrounding controls): authority on dependency isolation, timeouts, retries with backoff, and graceful degradation as deployment-architecture concerns. Verify against the Reliability Pillar version current at audit time.
+- Google SRE Workbook chapters on overload and addressing cascading failures: background reading on load shedding, graceful degradation, and the difference between transient and persistent failure modes.
+- IETF RFC 7231 and successor specifications for HTTP semantics: authority for which response statuses are safe to retry by default.
+- IETF RFC 7234 and `Retry-After` semantics: authority for cooperating with explicit retry-control signals from upstreams.
+
+Vendor-specific resilience libraries (circuit-breaker libraries, service-mesh fault-tolerance modules, language-runtime cancellation primitives) are illustrative implementations of the outcomes above; they are not authority. Choose the implementation appropriate to the platform.
+<!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->

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

@@ -3,6 +3,7 @@ id_prefix: SEC
 domain: security
 priority: critical
 scope: all-tasks
+last_validated: 2026-05-17
 applies_to:
   - backend
   - frontend
@@ -43,3 +44,30 @@ Use the security model and libraries already present in the project. If security
 4. Sanitization must match the sink: SQL, shell, file path, log, HTML, template, and URL contexts need different protections.
 5. Authorization must be resource-aware when data ownership matters. Prefer row, tenant, account, organization, or resource-level checks over role-only checks for sensitive records.
 6. For high-risk changes, check current framework security docs and record the relevant source or assumption in the implementation notes.
+
+## SEC-003: Authentication versus authorization
+
+1. Authentication proves identity (this caller is who they claim to be); authorization grants capability (this identity may perform this action on this resource). The two are different concerns and must be implemented as distinct layers.
+2. Request-handling code must not conflate them. A handler that checks "is this caller logged in?" and treats the answer as permission to mutate the resource is a defect, regardless of how strong the authentication check is.
+3. The authorization decision layer must be independently testable from the request-handling layer. The system must support tests that pass an authenticated principal plus a target resource and a requested action and assert the decision, without standing up the full HTTP transport.
+4. Authorization decisions must be recorded as audit events [REF:OBS-004]: who acted, what was acted upon, the requested action, and the decision. A "permitted" decision and a "denied" decision both belong on the audit stream.
+5. Reject controllers that mix authentication checks, business policy, and persistence in one block. Reject role-only authorization on resources that have owners; ownership-, tenant-, or relationship-aware authorization is required when records have owners.
+
+## SEC-004: Credential storage
+
+1. Passwords and other reversible-equivalent credentials must be hashed with a memory-hard, computationally-tunable algorithm intended for password storage. Argon2id is the current widely accepted default; bcrypt remains acceptable on platforms where a memory-hard implementation is unavailable or on platforms where the operational surface has already standardized on it. The mechanism must be tunable: as hardware improves, the work factor must be raised without a code change.
+2. General-purpose hash functions (MD5, SHA-1, SHA-256, SHA-3 by themselves) are forbidden for password storage. They are designed to be fast; password storage requires a function designed to be slow under attacker hardware.
+3. Stored credentials must include a per-credential random salt at the size and shape the chosen algorithm specifies; global pepper, if used, must come from the secret manager [REF:CFG-002], not from source.
+4. Verification must be constant-time for the comparison step where the platform supports it, to limit timing-side-channel inference about partial matches.
+5. Credential rotation must be supported as a runtime operation: the system must be able to re-hash a credential at the next successful authentication when the work factor or algorithm changes, without forcing a coordinated reset.
+6. Reject storing credentials with a general-purpose hash. Reject storing credentials in plaintext for any reason, including "for support recovery". Reject pinning a work factor that the platform's hardware has outpaced; the work factor is a tuning parameter, not a constant.
+
+## SEC-005: Service-to-service authentication
+
+1. Service-to-service identity must be cryptographically verifiable at the receiving end. Acceptable mechanisms include mutual TLS with verified peer certificates, OIDC client-credentials flow with short-lived tokens, signed bearer tokens with a documented issuer and verifiable signature, or platform-equivalent verifiable identity (workload identity, signed JWT-over-mTLS).
+2. Tokens used between services must carry a short time-to-live (the value depends on the platform's revocation latency and the operation's blast radius; record the chosen TTL and the rationale, do not inherit a default).
+3. The receiving service must validate the token's issuer, signature, audience, expiration, and not-before fields on every request. A cached "yes this is valid" decision that bypasses signature validation is a defect.
+4. Reject shared static tokens (a single long-lived API key embedded in every caller) as the sole identity mechanism between services. Static tokens are acceptable only as one factor inside a stronger mechanism, or as a deliberate fallback for narrowly-scoped, audit-logged emergency access.
+5. Reject IP-allow-list as a substitute for cryptographic identity on networks the producer does not exclusively control. Reject "trusted network" as a substitute for verifying the caller; zero-trust is the default at the service boundary.
+6. Authority for the rules above includes OWASP ASVS sections on authentication and session management, IETF RFC 6749 (OAuth 2.0) and successors for token-based identity, and the platform's current workload-identity documentation. Verify the current versions at audit time.
+<!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->

package/AGENTS.md

@@ -31,21 +31,21 @@ Keep it short. Do not load every rule just to fill it out.
 Avoid repeated command output. Do not rerun broad inspections unless edits changed the result. Prefer targeted reads, targeted searches, concise diffs, and final validation gates.
 
 ## Layer Index
-### Layer 1: Rules (15 Files) [SCOPE-RESOLVED]
+### Layer 1: Rules (21 Files) [SCOPE-RESOLVED]
 Location: `.agent-context/rules/`.
 
 Load only relevant rule files. Do not read the entire rule directory by default.
 
-Available rules: `naming-conv.md` (`NAME-*`, v4), `architecture.md` (`ARCH-*`, v4), `security.md` (`SEC-*`, v4), `performance.md` (`PERF-*`, v4), `error-handling.md` (`ERR-*`, v4), `testing.md` (`TEST-*`, v4), `git-workflow.md` (`GIT-*`, v4), `efficiency-vs-hype.md` (`DEP-*`, v4), `api-docs.md` (`API-*`, v4), `microservices.md` (`SVC-*`, v4), `event-driven.md` (`EVT-*`, v4), `database-design.md` (`DATA-*`, v4), `realtime.md` (`RT-*`, v4), `frontend-architecture.md` (`FE-*`, v4), `docker-runtime.md` (`DOCK-*`, v4).
+Available rules: `naming-conv.md` (`NAME-*`, v4), `architecture.md` (`ARCH-*`, v4), `security.md` (`SEC-*`, v4), `performance.md` (`PERF-*`, v4), `error-handling.md` (`ERR-*`, v4), `testing.md` (`TEST-*`, v4), `git-workflow.md` (`GIT-*`, v4), `efficiency-vs-hype.md` (`DEP-*`, v4), `api-docs.md` (`API-*`, v4), `microservices.md` (`SVC-*`, v4), `event-driven.md` (`EVT-*`, v4), `database-design.md` (`DATA-*`, v4), `realtime.md` (`RT-*`, v4), `frontend-architecture.md` (`FE-*`, v4), `docker-runtime.md` (`DOCK-*`, v4), `observability.md` (`OBS-*`, v4), `resilience.md` (`RES-*`, v4), `migrations.md` (`MIG-*`, v4), `background-jobs.md` (`JOB-*`, v4), `config-and-flags.md` (`CFG-*`, v4), `api-versioning.md` (`VER-*`, v4).
 
-For Docker or Compose work, load `docker-runtime.md` and verify the latest official Docker docs before authoring container assets. Also perform live web research for Docker and framework/package setup claims. For framework or package setup work, use the latest stable compatible dependency set and official setup flow unless a documented compatibility constraint blocks it. Prefer official framework scaffolders when they create the supported project shape; manual file assembly needs a repo, prototype, learning, or architecture reason. New dependencies are allowed when they improve efficiency, delivery time, correctness, accessibility, UX, or maintainability. Do not treat dependency avoidance or vague performance fear as a default reason to skip a modern maintained library.
+For Docker or Compose work, load `docker-runtime.md` and verify the latest official Docker docs before authoring container assets. Also perform live web research for Docker and framework/package setup claims. For framework or package setup work, use the latest stable compatible dependency set and official setup flow unless a documented compatibility constraint blocks it; prefer official framework scaffolders when they create the supported project shape. New dependencies are allowed when they improve efficiency, delivery time, correctness, accessibility, UX, or maintainability. Do not treat dependency avoidance or vague performance fear as a default reason to skip a modern maintained library.
 
 Backend/API routing:
-- Data/schema/persistence: `architecture.md`, `database-design.md`, `performance.md`, `testing.md`.
-- Endpoint/API/error contracts: `architecture.md`, `api-docs.md`, `error-handling.md`, `security.md`, `testing.md`.
-- Auth/secrets/uploads/permissions: `security.md`, `error-handling.md`, `testing.md`.
-- Queue/worker/cron/events/retry: `event-driven.md`, `database-design.md`, `error-handling.md`, `performance.md`, `testing.md`.
-- Multi-service/distributed boundaries: `microservices.md`, `event-driven.md`, `database-design.md`, `api-docs.md`, `architecture.md`.
+- Data/schema/persistence: `architecture.md`, `database-design.md`, `migrations.md`, `performance.md`, `testing.md`.
+- Endpoint/API/error contracts: `architecture.md`, `api-docs.md`, `api-versioning.md`, `error-handling.md`, `observability.md`, `security.md`, `testing.md`.
+- Auth/secrets/uploads/permissions: `security.md`, `config-and-flags.md`, `error-handling.md`, `observability.md`, `testing.md`.
+- Queue/worker/cron/events/retry: `event-driven.md`, `background-jobs.md`, `resilience.md`, `database-design.md`, `error-handling.md`, `observability.md`, `performance.md`, `testing.md`.
+- Multi-service/distributed boundaries: `microservices.md`, `event-driven.md`, `database-design.md`, `api-docs.md`, `architecture.md`, `resilience.md`, `observability.md`, `performance.md`.
 
 Use the union once when scopes overlap. Do not create framework-specific governance adapters.
 

package/README.md

@@ -2,7 +2,7 @@
 
 # Agentic-Senior-Core
 
-### Force your AI Agent to code like a Staff Engineer, not a Junior.
+### Change your AI Agent to code like a Staff Engineer, not a Junior.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
@@ -10,7 +10,7 @@
 **Production-grade Rules Engine (Governance Engine) for AI coding agents.**
 Works with Cursor, Windsurf, GitHub Copilot, Claude Code, Gemini, and other LLM-powered IDE workflows.
 
-Current package version: 4.0.0. Last published version before this release: 3.0.50.
+Current package version: 4.1.0. Last published version before this release: 4.0.3.
 
 Highlights:
 - Uses `AGENTS.md` as the canonical instruction entrypoint.
@@ -22,7 +22,37 @@ Highlights:
 
 ---
 
-## What's New in v4
+## Why this exists
+
+A coding agent that has read every framework tutorial on the internet still ships junior-grade work because nothing in its training tells it which trade-off matters in your codebase. This pack is a small set of plain-language rules an agent loads only when the work scope calls for them: data, endpoints, observability, resilience, migrations, jobs, configuration, versioning, security, design, and a few more. The rules are written as invariants and as bad habits to reject, not as opinions about which framework is fashionable. An agent that reads them treats your repo with the discipline of a senior engineer the first time, instead of after three rounds of review. You install it with one command, you can revert it with a backup, and it does not depend on any particular IDE or LLM provider.
+
+### Long-Term Stability
+
+The rules in this pack are written as invariants, outcomes, and freshness criteria, not as named patterns, library prescriptions, or magic-number thresholds. A migration rule says "DDL expected to hold a lock longer than the service's acceptable request-latency threshold must use an online migration mechanism", not "use pgroll for tables larger than ten million rows". A resilience rule says "fail fast when a dependency is unhealthy and shed load before shared resources are exhausted", not "implement a circuit breaker using library X". The intent is that each rule continues to tell a future maintainer the right thing to do across at least three years of framework and tooling churn. Where a rule cites a specific tool name or numeric threshold, the citation block at the bottom of the rule carries a freshness anchor and (in the next release) a `last_validated` date so the next maintainer knows when the technology references were last cross-checked against current practice.
+
+---
+
+## What's New in v4.1
+
+This release adds six backend rule files that bring the backend pack to parity with the existing frontend rule. They are technology-neutral by construction and follow the same v4 numbered-Markdown format as the prior fifteen rules.
+
+- `observability.md` (`OBS-*`) — observability as structured per-request events; metrics, logs, and traces as derived views; SLO-backed alerting; cardinality, signal-substitution, and audit-stream rules.
+- `resilience.md` (`RES-*`) — explicit timeouts and deadline propagation, idempotency-required retries, dependency isolation, fail-fast as outcome (not named pattern), explicit graceful degradation, observable backpressure.
+- `migrations.md` (`MIG-*`) — expand-contract / parallel-change for live data, deploy-ordering invariant, lock-posture rule keyed to the service's own latency budget, idempotent resumable backfills, mandatory risk fields per migration ticket.
+- `background-jobs.md` (`JOB-*`) — job-shape selection (scheduled vs queued vs stream vs one-shot), per-job ownership and runbook, job-level idempotency, lease/checkpoint/graceful-shutdown for long jobs, poison-message and dead-letter discipline, UTC schedules, jittered fan-out, explicit backpressure.
+- `config-and-flags.md` (`CFG-*`) — configuration sources and startup validation, secret handling, four-way feature-flag taxonomy (release / kill switch / experiment / entitlement) with per-flag owner and expiry, safe defaults on flag-service outage, no-branch-on-environment rule.
+- `api-versioning.md` (`VER-*`) — single versioning strategy per surface, breaking-vs-non-breaking definitions, deprecation discipline (in-band signal via RFC 9745 / RFC 8594 where adopted, plus migration guide and telemetry), explicit support windows, additive evolution as default, CI-blocking compatibility checks.
+
+Plus targeted refinements to four existing rules:
+
+- `frontend-architecture.md` — FE-012 Data state surface, FE-017 Interactivity priority, FE-018 Internationalization as layout, FE-019 Theme as context.
+- `security.md` — SEC-003 authn vs authz, SEC-004 memory-hard credential storage, SEC-005 cryptographically verifiable service-to-service identity.
+- `database-design.md` — DATA-003 money and time (no floating-point money, UTC for real-world moments), DATA-004 concurrency and write conflicts.
+- `api-docs.md` — API-005 cross-reference to the new versioning rule, API-012 idempotency as a runtime invariant (not just a documentation field).
+
+Plus repository hygiene: archive consolidation into `docs/archive/HISTORY.md`, removal of the v3-purge and migrate-rule-format tooling (now under `docs/archive/migrations/`), and inlining of the terminology mapping into this README.
+
+## What's New in v4 (prior)
 
 The internal `.agent-context/rules/` pack is now numbered Markdown with YAML frontmatter and stable section IDs (e.g. `FE-004`, `ARCH-009`, `API-006`). This is a breaking change for downstream consumers that parse rule headings; the migration guide lives in `CHANGELOG.md` under `4.0.0`. Repository-wide impact:
 
@@ -41,7 +71,7 @@ npx @ryuenn3123/agentic-senior-core init
 
 One command to initialize `AGENTS.md`, native import bridges, checklists, policies, state files, and the lazy `.agent-context/` rule library for your project.
 
-> **See [docs/doc-index.md](docs/doc-index.md), [docs/deep-dive.md](docs/deep-dive.md), and [docs/roadmap.md](docs/roadmap.md) for deeper CLI, architecture, integration, and roadmap context.**
+> **See [docs/doc-index.md](docs/doc-index.md), [docs/deep-dive.md](docs/deep-dive.md), and [docs/deep-analysis-and-roadmap-backlog.md](docs/deep-analysis-and-roadmap-backlog.md) for deeper CLI, architecture, integration, and roadmap context.**
 
 - Default init copies the compact instruction surface and writes onboarding, selected policy, token optimization, and memory continuity state.
 - MCP workspace files are disabled by default. Add `--mcp-template` when you want starter IDE MCP configuration files.
@@ -92,7 +122,6 @@ If you see `Property $schema is not allowed`, keep `.vscode/mcp.json` without `$
 | `agentic-senior-core init` | Initialize the compact project guidance pack and native agent entrypoints |
 | `agentic-senior-core upgrade --dry-run` | Preview managed-surface upgrades |
 | `agentic-senior-core optimize --show` | Show token optimization state |
-| `npm run audit:v3-purge` | Run deep purge readiness audit (no deletion) |
 | `npm run clean:local` | Remove ignored local reports, backups, benchmarks, and active-memory state |
 | `agentic-senior-core mcp` | Start local MCP stdio runtime |
 
@@ -138,7 +167,12 @@ Deprecated legacy files such as `.instructions.md`, `.agent-instructions.md`, `.
 
 Rule: on first mention in developer-facing docs, include canonical term in parentheses.
 
-Full mapping reference: docs/terminology-mapping.md
+Examples:
+- `Federated Rules Operations (Federated Governance)`
+- `Rules Engine (Governance Engine)`
+- `quality checks (guardrails)`
+
+Compliance boundary: formal policy and audit artifacts must keep canonical terminology for operational traceability.
 
 ---
 
@@ -146,11 +180,10 @@ Full mapping reference: docs/terminology-mapping.md
 
 - FAQ: docs/faq.md
 - Deep dive internals: docs/deep-dive.md
-- Archived V2 upgrade playbook: docs/archive/v2-upgrade-playbook.md
+- Project history (phase outcomes, archived playbooks, retired roadmap): docs/archive/HISTORY.md
 - Integration playbook: docs/integration-playbook.md
 - Benchmark and stack reference: docs/benchmark-reference.md
-- Terminology mapping reference: docs/terminology-mapping.md
-- Product roadmap: docs/roadmap.md
+- Active roadmap and backlog: docs/deep-analysis-and-roadmap-backlog.md
 
 ---
 

package/bin/agentic-senior-core.js

@@ -15,6 +15,7 @@ import { runMcpServerCommand } from '../lib/cli/commands/mcp.mjs';
 import { runOptimizeCommand, parseOptimizeArguments } from '../lib/cli/commands/optimize.mjs';
 import { runInitCommand, parseInitArguments } from '../lib/cli/commands/init.mjs';
 import { runUpgradeCommand, parseUpgradeArguments } from '../lib/cli/commands/upgrade.mjs';
+import { runDesignAntiRepeatAuditCommand } from '../lib/cli/commands/audit-design-anti-repeat.mjs';
 
 async function main() {
   const commandArgument = process.argv[2];
@@ -63,6 +64,11 @@ async function main() {
     return;
   }
 
+  if (commandArgument === 'audit:design-anti-repeat') {
+    const auditExitCode = await runDesignAntiRepeatAuditCommand(commandArguments);
+    exit(auditExitCode);
+  }
+
   console.error(`Unknown command: ${commandArgument}`);
   printUsage();
   exit(1);

package/lib/cli/audits/typography-palette-anti-repeat/color-utils.mjs

@@ -0,0 +1,156 @@
+// @ts-check
+
+/**
+ * Color parsing and distance utilities for the typography/palette
+ * anti-repeat audit. OKLCH math is contained here so the main audit module
+ * stays focused on file scanning and ledger cross-check.
+ */
+
+export const HEX_COLOR_PATTERN = /#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g;
+export const OKLCH_PATTERN = /oklch\(\s*([^)]+)\s*\)/gi;
+
+export function expandShortHexColor(rawHexColor) {
+  if (rawHexColor.length !== 4) {
+    return rawHexColor;
+  }
+  const expandedChars = [];
+  for (let charIndex = 1; charIndex < rawHexColor.length; charIndex += 1) {
+    expandedChars.push(rawHexColor[charIndex], rawHexColor[charIndex]);
+  }
+  return `#${expandedChars.join('')}`.toLowerCase();
+}
+
+export function normalizeHexColor(rawHexColor) {
+  if (typeof rawHexColor !== 'string' || rawHexColor.length === 0) {
+    return null;
+  }
+  const trimmedHex = rawHexColor.trim().toLowerCase();
+  if (!trimmedHex.startsWith('#')) {
+    return null;
+  }
+  if (trimmedHex.length === 4) {
+    return expandShortHexColor(trimmedHex);
+  }
+  if (trimmedHex.length === 7 || trimmedHex.length === 9) {
+    return trimmedHex.slice(0, 7);
+  }
+  return null;
+}
+
+function parseOklchNumber(rawNumber, percentScale) {
+  const numberString = String(rawNumber || '').trim();
+  if (numberString.endsWith('%')) {
+    const percentValue = parseFloat(numberString.slice(0, -1));
+    if (!Number.isFinite(percentValue)) {
+      return Number.NaN;
+    }
+    return (percentValue / 100) * percentScale;
+  }
+  return parseFloat(numberString);
+}
+
+export function parseOklchTriple(oklchExpression) {
+  const componentTokens = String(oklchExpression || '')
+    .replace(/\//g, ' ')
+    .split(/[\s,]+/)
+    .filter((componentToken) => componentToken.length > 0);
+  if (componentTokens.length < 3) {
+    return null;
+  }
+  const lightness = parseOklchNumber(componentTokens[0], 1);
+  const chroma = parseFloat(componentTokens[1]);
+  const hueDegrees = parseOklchNumber(componentTokens[2], 360);
+  if (!Number.isFinite(lightness) || !Number.isFinite(chroma) || !Number.isFinite(hueDegrees)) {
+    return null;
+  }
+  return { lightness, chroma, hueDegrees };
+}
+
+/**
+ * L*C*H-style perceptual distance proxy. OKLCH is perceptually uniform,
+ * so a Cartesian-like delta over (L, C, C * Δhue_radians) tracks visible
+ * difference well enough for an anti-repeat heuristic.
+ */
+export function oklchPerceptualDistance(leftColor, rightColor) {
+  const lightnessDelta = leftColor.lightness - rightColor.lightness;
+  const chromaDelta = leftColor.chroma - rightColor.chroma;
+  const hueDelta = ((leftColor.hueDegrees - rightColor.hueDegrees + 540) % 360) - 180;
+  const hueArcRadians = (hueDelta * Math.PI) / 180;
+  const hueChromaDelta = leftColor.chroma * hueArcRadians;
+  return Math.sqrt(
+    lightnessDelta * lightnessDelta
+    + chromaDelta * chromaDelta
+    + hueChromaDelta * hueChromaDelta,
+  );
+}
+
+export function extractColorOccurrencesFromText(sourceText) {
+  /** @type {{ kind: 'hex' | 'oklch', raw: string, normalized: string | null, oklch: { lightness: number, chroma: number, hueDegrees: number } | null, index: number }[]} */
+  const colorOccurrences = [];
+
+  HEX_COLOR_PATTERN.lastIndex = 0;
+  let hexMatch;
+  // eslint-disable-next-line no-cond-assign
+  while ((hexMatch = HEX_COLOR_PATTERN.exec(sourceText)) !== null) {
+    colorOccurrences.push({
+      kind: 'hex',
+      raw: hexMatch[0],
+      normalized: normalizeHexColor(hexMatch[0]),
+      oklch: null,
+      index: hexMatch.index,
+    });
+  }
+
+  OKLCH_PATTERN.lastIndex = 0;
+  let oklchMatch;
+  // eslint-disable-next-line no-cond-assign
+  while ((oklchMatch = OKLCH_PATTERN.exec(sourceText)) !== null) {
+    colorOccurrences.push({
+      kind: 'oklch',
+      raw: oklchMatch[0],
+      normalized: oklchMatch[0].toLowerCase(),
+      oklch: parseOklchTriple(oklchMatch[1]),
+      index: oklchMatch.index,
+    });
+  }
+
+  return colorOccurrences;
+}
+
+export function extractLedgerColors(antiRepeatLedger) {
+  const previousPalettes = Array.isArray(antiRepeatLedger?.previousPalettes)
+    ? antiRepeatLedger.previousPalettes
+    : [];
+
+  /** @type {{ kind: 'hex' | 'oklch', normalized: string | null, oklch: { lightness: number, chroma: number, hueDegrees: number } | null, sourceEntry: any }[]} */
+  const ledgerColors = [];
+  for (const ledgerEntry of previousPalettes) {
+    const summaryString = String(ledgerEntry?.summary || '');
+    if (!summaryString) {
+      continue;
+    }
+    HEX_COLOR_PATTERN.lastIndex = 0;
+    let hexMatch;
+    // eslint-disable-next-line no-cond-assign
+    while ((hexMatch = HEX_COLOR_PATTERN.exec(summaryString)) !== null) {
+      ledgerColors.push({
+        kind: 'hex',
+        normalized: normalizeHexColor(hexMatch[0]),
+        oklch: null,
+        sourceEntry: ledgerEntry,
+      });
+    }
+    OKLCH_PATTERN.lastIndex = 0;
+    let oklchMatch;
+    // eslint-disable-next-line no-cond-assign
+    while ((oklchMatch = OKLCH_PATTERN.exec(summaryString)) !== null) {
+      ledgerColors.push({
+        kind: 'oklch',
+        normalized: oklchMatch[0].toLowerCase(),
+        oklch: parseOklchTriple(oklchMatch[1]),
+        sourceEntry: ledgerEntry,
+      });
+    }
+  }
+  return ledgerColors;
+}

package/lib/cli/audits/typography-palette-anti-repeat/file-scanner.mjs

@@ -0,0 +1,103 @@
+// @ts-check
+
+/**
+ * Filesystem scanning for the typography/palette anti-repeat audit. Walks
+ * the repository tree, skips noisy directories (node_modules, build outputs,
+ * etc.), and yields scannable CSS-like and token-config file paths.
+ */
+
+import { readdirSync, statSync, existsSync } from 'node:fs';
+import { extname, join, relative, sep } from 'node:path';
+
+export const DEFAULT_CSS_FILE_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
+export const TOKEN_CONFIG_FILE_NAMES = new Set([
+  'tailwind.config.js',
+  'tailwind.config.cjs',
+  'tailwind.config.mjs',
+  'tailwind.config.ts',
+  'theme.config.js',
+  'theme.config.ts',
+  'design-tokens.js',
+  'design-tokens.ts',
+]);
+export const SCAN_SKIP_DIRECTORY_NAMES = new Set([
+  'node_modules',
+  '.git',
+  '.agentic-backup',
+  '.benchmarks',
+  'dist',
+  'build',
+  '.next',
+  'out',
+  'coverage',
+  '.cache',
+]);
+
+function isInsideSkippedDirectory(absolutePath, repositoryRootPath) {
+  const relativePath = relative(repositoryRootPath, absolutePath);
+  if (!relativePath || relativePath.startsWith('..')) {
+    return true;
+  }
+  const pathSegments = relativePath.split(sep);
+  return pathSegments.some((segmentName) => SCAN_SKIP_DIRECTORY_NAMES.has(segmentName));
+}
+
+function* walkDirectoryEntries(currentDirectoryPath, repositoryRootPath) {
+  const directoryEntries = readdirSync(currentDirectoryPath, { withFileTypes: true });
+  for (const directoryEntry of directoryEntries) {
+    const childPath = join(currentDirectoryPath, directoryEntry.name);
+    if (directoryEntry.isDirectory()) {
+      if (SCAN_SKIP_DIRECTORY_NAMES.has(directoryEntry.name)) {
+        continue;
+      }
+      if (isInsideSkippedDirectory(childPath, repositoryRootPath)) {
+        continue;
+      }
+      yield* walkDirectoryEntries(childPath, repositoryRootPath);
+      continue;
+    }
+    if (directoryEntry.isFile()) {
+      yield childPath;
+    }
+  }
+}
+
+export function isScannableFile(absoluteFilePath) {
+  const fileExtension = extname(absoluteFilePath).toLowerCase();
+  if (DEFAULT_CSS_FILE_EXTENSIONS.has(fileExtension)) {
+    return true;
+  }
+  const baseName = absoluteFilePath.split(/[\\/]/).pop();
+  return TOKEN_CONFIG_FILE_NAMES.has(baseName);
+}
+
+export function collectScannableFilePaths(repositoryRootPath, scanRoots) {
+  const collectedFilePaths = [];
+  for (const scanRoot of scanRoots) {
+    const absoluteScanRoot = join(repositoryRootPath, scanRoot);
+    if (!existsSync(absoluteScanRoot)) {
+      continue;
+    }
+    const scanRootStat = statSync(absoluteScanRoot);
+    if (!scanRootStat.isDirectory()) {
+      continue;
+    }
+    for (const candidateFilePath of walkDirectoryEntries(absoluteScanRoot, repositoryRootPath)) {
+      if (!isScannableFile(candidateFilePath)) {
+        continue;
+      }
+      collectedFilePaths.push(candidateFilePath);
+    }
+  }
+  return collectedFilePaths.sort();
+}
+
+export function lineNumberFromIndex(sourceText, charIndex) {
+  let lineNumber = 1;
+  for (let scanIndex = 0; scanIndex < charIndex && scanIndex < sourceText.length; scanIndex += 1) {
+    if (sourceText[scanIndex] === '\n') {
+      lineNumber += 1;
+    }
+  }
+  return lineNumber;
+}

package/lib/cli/audits/typography-palette-anti-repeat/typography-utils.mjs

@@ -0,0 +1,70 @@
+// @ts-check
+
+/**
+ * Font-family parsing for the typography/palette anti-repeat audit. CSS
+ * `font-family:` declarations and `@font-face` blocks are the inputs;
+ * normalized lowercase family tokens are the outputs.
+ */
+
+export const FONT_FAMILY_DECLARATION_PATTERN = /font-family\s*:\s*([^;}]+)[;}]/gi;
+export const FONT_FACE_FAMILY_PATTERN = /@font-face\s*\{[^}]*font-family\s*:\s*([^;]+);/gi;
+
+export function normalizeFontFamilyToken(rawFamilyToken) {
+  return String(rawFamilyToken || '')
+    .replace(/^["']|["']$/g, '')
+    .trim()
+    .toLowerCase();
+}
+
+export function splitFontFamilyDeclaration(declarationValue) {
+  return String(declarationValue || '')
+    .split(',')
+    .map((familyEntry) => normalizeFontFamilyToken(familyEntry))
+    .filter((familyEntry) => familyEntry.length > 0 && !familyEntry.startsWith('var('));
+}
+
+export function extractFontFamiliesFromText(sourceText) {
+  /** @type {{ family: string, index: number }[]} */
+  const familyOccurrences = [];
+
+  for (const matchPattern of [FONT_FAMILY_DECLARATION_PATTERN, FONT_FACE_FAMILY_PATTERN]) {
+    matchPattern.lastIndex = 0;
+    let regexMatch;
+    // eslint-disable-next-line no-cond-assign
+    while ((regexMatch = matchPattern.exec(sourceText)) !== null) {
+      const declarationValue = regexMatch[1];
+      const declarationStartIndex = regexMatch.index;
+      for (const familyEntry of splitFontFamilyDeclaration(declarationValue)) {
+        familyOccurrences.push({ family: familyEntry, index: declarationStartIndex });
+      }
+    }
+  }
+
+  return familyOccurrences;
+}
+
+export function extractLedgerTypographyFamilies(antiRepeatLedger) {
+  const previousTypographyChoices = Array.isArray(antiRepeatLedger?.previousTypographyChoices)
+    ? antiRepeatLedger.previousTypographyChoices
+    : [];
+
+  const ledgerFamilies = new Map();
+  for (const ledgerEntry of previousTypographyChoices) {
+    const summaryString = String(ledgerEntry?.summary || '');
+    if (!summaryString) {
+      continue;
+    }
+    // Summaries are emitted as "role: value; role: value". Each value is a
+    // font family that the previous design shipped.
+    for (const summaryPart of summaryString.split(';')) {
+      const colonSplitIndex = summaryPart.indexOf(':');
+      const familyValue = colonSplitIndex >= 0 ? summaryPart.slice(colonSplitIndex + 1) : summaryPart;
+      const normalizedFamilyValue = normalizeFontFamilyToken(familyValue);
+      if (normalizedFamilyValue.length === 0) {
+        continue;
+      }
+      ledgerFamilies.set(normalizedFamilyValue, ledgerEntry);
+    }
+  }
+  return ledgerFamilies;
+}