@ryuenn3123/agentic-senior-core 4.4.0 → 5.2.0

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

@@ -1,38 +0,0 @@
----
-id_prefix: ARCH
-domain: architecture
-priority: critical
-scope: all-tasks
-applies_to: [backend, frontend, fullstack]
-keywords: [architecture, arch, boundary, system]
----
-
-# Architecture Boundary
-
-## 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. 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.
-
-## ARCH-007: Single Source of Truth and Lazy Rule Loading
-1. Canonical rule source is AGENTS.md.
-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: AI-Optimized Code Style (Simplicity, Modularity, Elegance)
-1. No Clever Hacks: Do not use code golfing, deeply nested ternaries, or tricky functional chains that destroy readability.
-2. No Premature Abstraction: Avoid over-engineering (excessive helper functions, layers, or abstraction classes) when a direct procedural flow is easier for an LLM to comprehend.
-3. Explicit Variable Naming: Use descriptive and functional variable names. Avoid cryptic abbreviations.
-4. Natural Implementation Pass: Keep the main flow traceable, use early returns to reduce nesting, and avoid abstraction chains unless a real duplication pattern exists.
-

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

@@ -1,17 +0,0 @@
----
-id_prefix: JOB
-domain: background-jobs
-priority: medium
-scope: backend
-applies_to: [backend, fullstack]
-keywords: [background-jobs, worker, cron, queue]
----
-
-# Background Jobs Boundary
-
-## 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

@@ -1,16 +0,0 @@
----
-id_prefix: CFG
-domain: config-and-flags
-priority: high
-scope: backend
-applies_to: [backend, frontend, fullstack]
-keywords: [configuration, feature-flags, environment, secrets]
----
-
-# Configuration Boundary
-
-## 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

@@ -1,18 +0,0 @@
----
-id_prefix: DATA
-domain: database-design
-priority: high
-scope: data
-applies_to: [backend, fullstack]
-keywords: [database-design, data, schema]
----
-
-# Data Design Boundary
-
-## 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

@@ -1,17 +0,0 @@
----
-id_prefix: DOCK
-domain: docker-runtime
-priority: high
-scope: infra
-applies_to: [backend, frontend, fullstack]
-keywords: [docker-runtime, docker, runtime]
----
-
-# Docker Runtime Boundary
-
-## 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/error-handling.md

@@ -1,16 +0,0 @@
----
-id_prefix: ERR
-domain: error-handling
-priority: high
-scope: backend
-applies_to: [backend, frontend, fullstack]
-keywords: [error-handling, errors, exception]
----
-
-# Error Handling Boundary
-
-## ERR-001: Execution Rules
-1. Fail fast on invalid input.
-2. Do not leak stack traces to clients. Log them securely.
-3. Use standardized machine-readable error codes (RFC 9457).
-4. Distinguish client errors (4xx) from server errors (5xx).

package/.agent-context/rules/event-driven.md

@@ -1,16 +0,0 @@
----
-id_prefix: EVT
-domain: event-driven
-priority: medium
-scope: backend
-applies_to: [backend, fullstack]
-keywords: [event-driven, events, kafka, rabbitmq]
----
-
-# Event Driven Boundary
-
-## EVT-001: Execution Rules
-1. Events must be immutable.
-2. Consumers must be idempotent.
-3. Handle out-of-order events securely.
-4. Always implement Dead Letter Queues (DLQ) for poison messages.

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

@@ -1,54 +0,0 @@
----
-id_prefix: FE
-domain: frontend-architecture
-priority: high
-scope: ui
-last_validated: 2026-05-17
-applies_to: [frontend, fullstack]
-keywords: [frontend-architecture, fe, ui, engineering]
----
-
-# Frontend Engineering Invariants (Tier 2)
-
-Load this rule for UI-facing engineering work. This file contains strict engineering constraints.
-
-## FE-009: Accessibility
-1. WCAG 2.2 AA is the hard floor. APCA is advisory perceptual tuning only.
-2. Hard checks: focus visibility, target size, keyboard access, color-only meaning.
-
-## FE-010: CSS Production Hardening
-1. Plan overflow, wrapping, truncation, empty, loading, and error behavior.
-2. Prefer logical composition primitives (container queries, subgrid).
-
-## FE-011: Implementation Boundaries
-1. Follow the shipped project stack and current repo patterns.
-2. Do not hardcode framework-specific state management or data fetching libraries, or rigid component doctrines.
-
-## FE-012: Data State Surface
-1. Explicitly handle empty, loading, error, and offline states.
-2. Reject "spinner everywhere".
-
-## FE-013: Background and Wallpaper Discipline
-1. Decorative geometry are invalid as wallpaper.
-2. Use grids/lines only for specific functional roles (alignment, map, crop).
-
-## FE-014: Production Content Policy
-1. No visible testing, demo, sample, placeholder, lorem, or TODO labels in production UI.
-
-## FE-015: Motion Implementation Budget
-1. Keep reduced-motion, keyboard, loading, performance, and mobile fallbacks explicit.
-
-## FE-016: Library and Design-Intent Discipline
-1. Use component kits or headless primitives for behavior and accessibility when they fit.
-
-## FE-017: Interactivity Priority
-1. The interactive boundary must be drawn deliberately. Keep client-side state boundaries small.
-2. Measure responsiveness through Interaction to Next Paint (INP).
-
-## FE-018: Internationalization as Layout
-1. Direction-sensitive spacing, alignment, and positioning must use CSS logical properties (e.g., `margin-inline-start`).
-2. Plan a documented text-expansion budget for target locales.
-
-## FE-019: Theme as Context
-1. A theme switch is a change in lighting and surface model, not a color inversion. Re-derive tokens per theme.
-2. Brand colors carried across themes must be individually verified against the active theme's contrast floor.

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

@@ -1,16 +0,0 @@
----
-id_prefix: SVC
-domain: microservices
-priority: medium
-scope: backend
-applies_to: [backend, fullstack]
-keywords: [microservices, monolith]
----
-
-# Microservices Boundary
-
-## SVC-001: Execution Rules
-1. Default to modular monoliths unless scale explicitly dictates microservices.
-2. Independent services must own their data. NO shared databases.
-3. Cross-service calls must have timeouts and retries.
-4. Prefer async choreographies over distributed two-phase commits.

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

@@ -1,16 +0,0 @@
----
-id_prefix: MIG
-domain: migrations
-priority: high
-scope: data
-applies_to: [backend, fullstack]
-keywords: [migrations, schema, database]
----
-
-# Migrations Boundary
-
-## MIG-001: Execution Rules
-1. Schema changes MUST have a versioned migration.
-2. Migrations must be reversible (down-migrations) or have a recovery plan.
-3. Never modify past migrations once merged. Create a new one.
-4. Use concurrent index builds in production.

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

@@ -1,16 +0,0 @@
----
-id_prefix: OBS
-domain: observability
-priority: high
-scope: backend
-applies_to: [backend, fullstack]
-keywords: [observability, telemetry, logs, metrics]
----
-
-# Observability Boundary
-
-## OBS-001: Execution Rules
-1. Emit telemetry for failures, degraded states, and security events.
-2. Inject correlation IDs on inbound requests and propagate them downstream.
-3. Do not log PII, secrets, or credentials.
-4. Measure latency, traffic, errors, and saturation.

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

@@ -1,16 +0,0 @@
----
-id_prefix: PERF
-domain: performance
-priority: medium
-scope: backend
-applies_to: [backend, frontend, fullstack]
-keywords: [performance, perf, optimization]
----
-
-# Performance Boundary
-
-## PERF-001: Execution Rules
-1. Optimize DB queries before adding caches.
-2. Compress network payloads.
-3. Bound memory usage (paginate, stream). No unbounded arrays.
-4. Cache aggressively but define explicit cache invalidation.

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

@@ -1,16 +0,0 @@
----
-id_prefix: RT
-domain: realtime
-priority: medium
-scope: backend
-applies_to: [backend, fullstack]
-keywords: [realtime, websockets, sse]
----
-
-# Realtime Boundary
-
-## RT-001: Execution Rules
-1. Use SSE for one-way server-to-client streams. Use WebSockets only for true bi-directional.
-2. Realtime connections must gracefully degrade to polling if blocked.
-3. Implement ping/pong heartbeats to drop dead connections.
-4. Scale pub/sub via Redis or dedicated brokers.

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

@@ -1,18 +0,0 @@
----
-id_prefix: RES
-domain: resilience
-priority: critical
-scope: backend
-applies_to: [backend, fullstack]
-keywords: [resilience, timeout, retry]
----
-
-# Resilience Boundary
-
-## RES-001: Execution Rules
-1. Every outbound network call MUST have a strict timeout.
-2. Retries MUST use exponential backoff with jitter and max attempt limits.
-3. Only retry idempotent operations.
-4. Fail fast using Circuit Breakers / Load Shedding on unhealthy dependencies.
-5. Provide graceful degradation on non-critical dependency failures.
-6. Enforce backpressure on bounded consumers.

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

@@ -1,18 +0,0 @@
----
-id_prefix: SEC
-domain: security
-priority: critical
-scope: all-tasks
-applies_to: [backend, frontend, fullstack]
-keywords: [security, boundary, zero-trust]
----
-
-# Security Boundary
-
-## SEC-001: Execution Rules
-1. Validate and normalize ALL inputs.
-2. Parameterize all SQL queries. Never interpolate input into DB or Shell.
-3. Hash passwords with Argon2/Bcrypt. NEVER store plain text or use MD5/SHA.
-4. NEVER commit secrets, tokens, or credentials.
-5. Implement resource-aware authorization (Row-Level), not just Authentication.
-6. Verify service-to-service cryptographic identity.

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

@@ -1,16 +0,0 @@
----
-id_prefix: TEST
-domain: testing
-priority: medium
-scope: all-tasks
-applies_to: [backend, frontend, fullstack]
-keywords: [testing, tests, coverage]
----
-
-# Testing Boundary
-
-## TEST-001: Execution Rules
-1. Write tests for business logic and boundary failures.
-2. Test error states, not just the happy path.
-3. Use deterministic mocks for external services.
-4. Ensure CI pipelines block on test failures.

package/.agent-context/state/README.md

@@ -1,25 +0,0 @@
-# State Artifacts
-
-Use this directory as a typed governance state surface, not as a dump folder.
-
-Tracked seed/config artifacts:
-- `architecture-map.md`
-- `dependency-map.md`
-- `benchmark-comparison-schema.json`
-- `benchmark-reproducibility.json`
-- `benchmark-thresholds.json`
-- `benchmark-writer-judge-config.json`
-- `memory-adapter-contract.json`
-- `memory-schema-v1.json`
-
-Tracked operational artifact:
-- `onboarding-report.json` stays tracked in this repository because internal audits read it as the current repository onboarding state. In installed projects, `init` and `upgrade` regenerate this file.
-
-Local-only/generated artifacts:
-- `active-memory.json`
-- `llm-judge-report.json`
-- `token-saver/`
-- `token-optimization-report.json`
-- benchmark, trend, weekly governance, and quality report outputs
-
-Do not treat generated reports or archived research as current project truth. Rerun the matching `npm run benchmark:*`, `npm run report:*`, or `npm run audit:*` command when fresh evidence is needed.

package/.agent-context/state/architecture-map.md

@@ -1,40 +0,0 @@
-# Architecture Map
-
-Use this file as repo-local agent context. It records the current governance architecture and the boundaries agents must protect.
-
-## Boundary Classification
-
-| Surface | Criticality | Change Policy | Required Checks |
-| --- | --- | --- | --- |
-| `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` | critical | Keep `AGENTS.md` canonical and native bridges minimal | `npm run sync:adapters`, `npm run check:adapters`, `npm run validate` |
-| `.agent-context/rules/**`, `.agent-context/prompts/**`, `.agent-context/review-checklists/**` | critical | Keep rules imperative, compact, scope-resolved, and non-duplicative | adapter sync, validation, targeted smoke tests |
-| `.agent-context/state/**` | high | Track only seed/config and current operational state; keep generated reports local-only | `npm pack --dry-run`, state README review |
-| `scripts/sync-thin-adapters.mjs` | critical | Preserve minimal import bridge compatibility for Claude and Gemini | adapter tests, smoke tests, validation |
-| `lib/cli/commands/init.mjs`, `lib/cli/commands/upgrade.mjs` | high | Preserve fresh-project and existing-project behavior without silent stack/style decisions | CLI smoke tests, onboarding report checks |
-| `lib/cli/project-scaffolder/**` | high | Preserve docs-first and design-contract behavior without hardcoded house style | design/detection smoke tests, validation |
-| `scripts/validate*.mjs`, `scripts/validate/**` | high | Keep validation mechanical and aligned with current shipped surfaces | `node ./scripts/validate.mjs`, targeted script checks |
-| `tests/**` | high | Test behavior and contracts, not private implementation trivia | `npm test` |
-| `package.json`, `package-lock.json`, package allowlist | high | Keep release metadata and tarball contents synchronized | `npm pack --dry-run`, release gate |
-
-## Frontend Governance Context
-
-- Frontend guidance is efficient enough for the current architecture because it is scope-resolved: UI tasks load `bootstrap-design.md` and `frontend-architecture.md`; backend-only tasks do not.
-- Keep the current design contract. It does not prescribe a palette or layout; it requires product evidence, anchor-derived tokens, motion/spatial fit decisions, and accessibility.
-- Do not reduce motion, 3D, canvas, WebGL, or animation guidance. These are capability unlocks, not mandatory decoration.
-- Treat product categories as heuristics only. They must not become style presets.
-- Treat grid, line, glow, blob, and abstract-logo backgrounds as review findings unless they serve a named product function.
-
-## Backend Governance Context
-
-- Backend guidance is efficient enough for the current architecture because backend/API rules are lazy-loaded by scope.
-- Keep global backend principles stack-agnostic: architecture boundaries, validation, safe errors, security, testing, event boundaries, and data design.
-- Do not add framework-specific governance adapters unless real repo evidence proves a repeated project need.
-- New dependencies are allowed when they improve efficiency, delivery time, correctness, or maintainability, and current official docs support the choice.
-
-## Agent Behavior
-
-1. Load the smallest relevant rule set.
-2. Use README only for public and developer overview, setup, usage, and user-facing context when governance files conflict.
-3. Preserve native import bridge sync before release.
-4. Treat stale generated state, dual lockfiles, and obsolete V2/V3 transition files as cleanup findings.
-5. Before claiming done, run the relevant validation gate and report any skipped checks.

package/.agent-context/state/benchmark-comparison-schema.json

@@ -1,181 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "Benchmark Before-vs-After Comparison",
-  "description": "Schema for comparing benchmark results across releases or configuration changes. Each entry captures quality, bug signal, runtime, and token metrics for a before and after snapshot.",
-  "type": "object",
-  "required": ["schemaVersion", "comparisonId", "generatedAt", "before", "after", "delta"],
-  "properties": {
-    "schemaVersion": {
-      "type": "string",
-      "const": "1.0.0"
-    },
-    "comparisonId": {
-      "type": "string",
-      "description": "Unique identifier for this comparison run."
-    },
-    "generatedAt": {
-      "type": "string",
-      "format": "date-time"
-    },
-    "baselineVersion": {
-      "type": "string",
-      "description": "Package version of the before snapshot."
-    },
-    "candidateVersion": {
-      "type": "string",
-      "description": "Package version of the after snapshot."
-    },
-    "comparisonType": {
-      "type": "string",
-      "enum": ["release-to-release", "config-change", "model-swap", "manual"],
-      "description": "What triggered this comparison."
-    },
-    "before": { "$ref": "#/$defs/snapshot" },
-    "after": { "$ref": "#/$defs/snapshot" },
-    "delta": { "$ref": "#/$defs/deltaReport" },
-    "verdict": {
-      "type": "string",
-      "enum": ["pass", "warn", "fail"],
-      "description": "Overall comparison verdict based on threshold policy."
-    },
-    "verdictReason": {
-      "type": "string",
-      "description": "Human-readable explanation of the verdict."
-    }
-  },
-  "$defs": {
-    "snapshot": {
-      "type": "object",
-      "required": ["capturedAt", "quality", "runtime"],
-      "properties": {
-        "capturedAt": {
-          "type": "string",
-          "format": "date-time"
-        },
-        "packageVersion": {
-          "type": "string"
-        },
-        "quality": {
-          "type": "object",
-          "properties": {
-            "top1Accuracy": {
-              "type": "number",
-              "minimum": 0,
-              "maximum": 1,
-              "description": "Fraction of scenarios where the top-ranked output was correct."
-            },
-            "manualCorrectionRate": {
-              "type": "number",
-              "minimum": 0,
-              "maximum": 1,
-              "description": "Fraction of outputs requiring human correction."
-            },
-            "averageJudgeScore": {
-              "type": "number",
-              "minimum": 0,
-              "maximum": 10,
-              "description": "Mean score across all judge dimensions."
-            },
-            "scenarioCount": {
-              "type": "integer",
-              "minimum": 1
-            }
-          }
-        },
-        "bugSignal": {
-          "type": "object",
-          "properties": {
-            "validationFailures": {
-              "type": "integer",
-              "minimum": 0,
-              "description": "Number of validation check failures."
-            },
-            "securityWarnings": {
-              "type": "integer",
-              "minimum": 0
-            },
-            "deprecationWarnings": {
-              "type": "integer",
-              "minimum": 0
-            }
-          }
-        },
-        "runtime": {
-          "type": "object",
-          "properties": {
-            "totalDurationMs": {
-              "type": "number",
-              "description": "Total benchmark suite execution time in milliseconds."
-            },
-            "averageScenarioDurationMs": {
-              "type": "number"
-            },
-            "peakMemoryMb": {
-              "type": "number"
-            }
-          }
-        },
-        "token": {
-          "type": "object",
-          "properties": {
-            "nativeSavingsPercent": {
-              "type": "number",
-              "description": "Token savings from native optimization."
-            },
-            "proxySavingsPercent": {
-              "type": "number",
-              "description": "Token savings from external proxy optimization."
-            },
-            "totalInputTokens": {
-              "type": "integer"
-            },
-            "totalOutputTokens": {
-              "type": "integer"
-            }
-          }
-        }
-      }
-    },
-    "deltaReport": {
-      "type": "object",
-      "properties": {
-        "top1AccuracyChange": {
-          "type": "number",
-          "description": "After minus before. Positive means improvement."
-        },
-        "manualCorrectionRateChange": {
-          "type": "number",
-          "description": "After minus before. Negative means improvement."
-        },
-        "averageJudgeScoreChange": {
-          "type": "number"
-        },
-        "validationFailureChange": {
-          "type": "integer"
-        },
-        "totalDurationMsChange": {
-          "type": "number"
-        },
-        "nativeSavingsChange": {
-          "type": "number"
-        },
-        "regressionDetected": {
-          "type": "boolean",
-          "description": "True if any metric crossed a threshold in the wrong direction."
-        },
-        "regressionDetails": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "properties": {
-              "metric": { "type": "string" },
-              "threshold": { "type": "number" },
-              "actual": { "type": "number" },
-              "direction": { "type": "string", "enum": ["increase", "decrease"] }
-            }
-          }
-        }
-      }
-    }
-  }
-}