@ryuenn3123/agentic-senior-core 3.0.47 → 3.0.49

package/.agent-context/prompts/bootstrap-design.md

@@ -56,9 +56,7 @@ If the expressive path needs a new motion, 3D, canvas, scroll, or interaction li
 
 Only downshift ambition after naming the concrete blocker: product fit, content density, measured performance budget, accessibility, device support, package conflict, security risk, or missing runtime capability. A new dependency, package count, or vague performance concern is not a blocker by itself. Pair every downshift with a replacement interaction quality that still changes composition, hierarchy, feedback, or memorability.
 ## Design Flexibility Layer
-`docs/design-intent.json` must separate locked outcomes from flexible expression. The machine contract keeps review invariants stable; it must not freeze exact aesthetic implementation unless repo evidence, accessibility validation, implementation constraints, or explicit user approval locks it.
-
-Record `designFlexibilityPolicy`: lock user goals, runtime constraints, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component-kit theme mapping, signature move implementation, literal anchor artifacts, and spatial metaphors flexible until validated or approved. Semantic roles are required; exact primitives are not automatically locked. Required experience outcomes are separate from candidate implementation moves. Libraries supply behavior, accessibility, primitives, and delivery speed; the project supplies final composition, theme, morphology, and visual language.
+`docs/design-intent.json` must separate locked outcomes from flexible expression. The machine contract keeps review invariants stable; it must not freeze exact aesthetic implementation unless repo evidence, accessibility validation, implementation constraints, or explicit user approval locks it. Record `designFlexibilityPolicy`: lock user goals, runtime constraints, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component-kit theme mapping, signature move implementation, literal anchor artifacts, and spatial metaphors flexible until validated or approved. Semantic roles are required; exact primitives are not automatically locked.
 ## External Inspiration Boundary
 Using outside websites, benchmark apps, galleries, or component examples is useful for constraint discovery, interaction mechanics, and implementation options, but never as a style source to imitate. Extract why a pattern works, then translate it into a current-project rule. Do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture from a reference unless the user explicitly approves that continuity and it passes product fit.
 
@@ -83,16 +81,16 @@ If rich motion or spatial UI is omitted, record the product, content-density, pe
 If 3D or canvas is used, record product role, interaction model, fallback path, runtime/library choice, loading state, keyboard path, and reduced-motion behavior.
 
 ## Token Derivation Audit
-Before implementation, `docs/design-intent.json` must include top-level `derivedTokenLogic`:
-- `anchorReference`
-- `colorDerivationSource`
-- `spacingDerivationSource`
-- `typographyDerivationSource`
-- `motionDerivationSource`
-- `validationRule`
+Before implementation, `docs/design-intent.json` must include top-level `derivedTokenLogic`: `anchorReference`, `colorDerivationSource`, `spacingDerivationSource`, `typographyDerivationSource`, `motionDerivationSource`, `colorSpace`, `spatialBaseUnit`, `typeScaleMethod`, `motionBudget`, and `validationRule`.
 
 Every semantic token role must trace to `anchorReference`. Exact primitive values stay flexible until repo evidence, accessibility validation, implementation constraints, or explicit user approval locks them. If the rationale is "looks good", "common practice", "modern default", or "framework default", derive the token again before UI code.
 
+## Implementation Craft Layer
+Before accepting the design contract, record explicit CSS craft decisions:
+- Color/typography: prefer OKLCH tokens and tinted neutrals for new CSS when supported, preserve existing token formats, name color commitment level, and prefer fluid `clamp()` scales with explicit role contrast, `text-wrap: balance`, and numeric typography decisions.
+- Spatial/motion: name `spatialBaseUnit`, major multiples, optical exceptions, and `motionBudget`; prefer transform/opacity choreography, explicit easing, bounded stagger, and reduced-motion behavior.
+- Implementation anti-attractor: list three default CSS reflexes this task might trigger, reject the most likely one, and choose one distinctive implementation move tied to the product.
+
 ## Library Research Protocol
 If web search is available:
 - Verify each new UI-related library against current official docs.

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

@@ -40,7 +40,7 @@ The agent must:
 If the user specifies a framework, runtime, or architecture constraint, the agent must:
 1. Read [AGENTS.md](../../AGENTS.md) for role context.
 2. Resolve only the rules required by the explicit constraint and scope. Do not read unrelated backend, frontend, or DevOps rules by habit.
-3. Reference [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [.cursorrules](../../.cursorrules), and [.windsurfrules](../../.windsurfrules) for runtime evidence and any explicit constraints already applied to this project.
+3. Reference [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [AGENTS.md](../../AGENTS.md), and the relevant `.agent-context/` files for runtime evidence and any explicit constraints already applied to this project.
 4. Scaffold the initial project structure only after runtime and architecture decisions are explicit:
    - Create only the directories and files justified by the approved structure.
    - Set up configuration, validation, error handling, observability, health checks, and persistence only when they fit the approved runtime and project scope.
@@ -53,7 +53,7 @@ If the user specifies a framework, runtime, or architecture constraint, the agen
 
 ## Runtime and Architecture Reference
 
-See [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [.cursorrules](../../.cursorrules), and [.windsurfrules](../../.windsurfrules) for the latest shipped runtime evidence, explicit constraints, and agent-decision status.
+See [.agent-context/state/onboarding-report.json](../state/onboarding-report.json), [AGENTS.md](../../AGENTS.md), and the relevant `.agent-context/` files for the latest shipped runtime evidence, explicit constraints, and agent-decision status.
 
 ## UI/UX Bootstrap
 

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

@@ -78,8 +78,8 @@ Use `README.md` for human orientation, then use `docs/doc-index.md` to choose th
 
 ## Single Source of Truth and Lazy Rule Loading
 
-- Canonical rule source is .instructions.md.
-- Adapter entry files stay thin and must point to the canonical source.
+- Canonical rule source is AGENTS.md.
+- Native adapter entry files stay thin and must import the canonical source.
 - Load global domain rules lazily based on touched scope.
 - Do not create or load stack-specific governance adapters as the baseline.
 - Runtime or framework evidence can clarify implementation details, but it must not replace the global architecture, security, data, API, error, event, and testing boundaries.

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

@@ -19,19 +19,7 @@ Use this rule for UI, UX, page, screen, component, layout, landing, dashboard, f
 
 ## Required Design Contract
 
-Before UI code, create or refine `docs/DESIGN.md` and `docs/design-intent.json`.
-
-The contract must record:
-- `motionPaletteDecision`
-- `designFlexibilityPolicy`
-- `conceptualAnchor`
-- `derivedTokenLogic`
-- `aiSafeUiAudit`
-- `designExecutionPolicy`
-- `designExecutionHandoff`
-- `reviewRubric`
-- `contextHygiene`
-- `libraryResearchStatus` and `libraryDecisions[]`
+Before UI code, create or refine `docs/DESIGN.md` and `docs/design-intent.json`. The contract must record `motionPaletteDecision`, `designFlexibilityPolicy`, `conceptualAnchor`, `derivedTokenLogic`, `aiSafeUiAudit`, `designExecutionPolicy`, `designExecutionHandoff`, `reviewRubric`, `contextHygiene`, `libraryResearchStatus`, and `libraryDecisions[]`.
 
 ## Anti-Generic UI Gate
 
@@ -71,6 +59,7 @@ If the user gives no current-task visual research or reference:
 - Treat motion, 3D, WebGL, canvas, scroll choreography, and animation libraries as first-class options.
 - Omit rich motion or spatial UI only after naming the product-fit reason and the replacement interaction quality.
 - For new screens or broad redesigns, research the expressive implementation path instead of defaulting to static native CSS. Use native or already-installed tools only when they can still deliver the chosen ambition, or when a concrete blocker is documented. Do not downshift because adding a package feels inconvenient; downshift only for a concrete product-fit, accessibility, security, compatibility, device, maintenance, or measured performance reason.
+- Prefer micro-interactions in 150-300ms, layout transitions in 300-500ms, transform/opacity for high-frequency motion, explicit easing, bounded stagger, and reduced-motion alternatives unless evidence changes the budget.
 - Keep reduced-motion, keyboard, loading, performance, mobile, and non-3D fallbacks explicit.
 - 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.
 - 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.
@@ -92,6 +81,7 @@ Responsive quality is not scale-only.
 - Tablet must regroup surfaces instead of shrinking desktop.
 - Desktop may expose more context but must not become interchangeable admin chrome.
 - At least one major surface must change position, grouping, priority, or disclosure strategy between mobile and desktop.
+- Prefer container queries, dynamic viewport units, support-checked selectors, subgrid, popover, or disclosure primitives when they simplify recomposition and fallbacks are clear.
 
 ## Accessibility
 
@@ -100,6 +90,12 @@ Responsive quality is not scale-only.
 - Hard checks include focus visibility, focus appearance, target size, keyboard access, accessible authentication, color-only meaning, and dynamic status/state access.
 - Fix accessibility issues without flattening the UI into generic safe chrome unless no expressive safe option remains.
 
+## CSS Production Hardening
+
+- Plan overflow, wrapping, truncation, empty, loading, error, and extreme-content behavior before declaring a layout complete.
+- Prefer `min()`, `max()`, `clamp()`, stable aspect ratios, container-relative sizing, OKLCH, and tinted neutrals for new tokens when supported; preserve existing design-system tokens.
+- Treat recursive card nesting, uniform radius everywhere, shadow on every surface, arbitrary spacing, gray text on saturated color, and library-default skins as drift signals requiring product rationale.
+
 ## Implementation Boundaries
 
 - Follow the shipped project stack and current repo patterns.

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

@@ -6,10 +6,10 @@ Use this file as repo-local agent context. It records the current governance arc
 
 | Surface | Criticality | Change Policy | Required Checks |
 | --- | --- | --- | --- |
-| `.instructions.md`, `AGENTS.md`, generated adapters | critical | Keep `.instructions.md` canonical and adapters thin/hash-synced | `npm run sync:adapters`, `npm run check:adapters`, `npm run validate` |
+| `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 |
-| `lib/cli/compiler.mjs`, `scripts/sync-thin-adapters.mjs` | critical | Preserve generated surface compatibility across Codex, Cursor, Windsurf, Copilot, Claude, and Gemini | adapter tests, smoke tests, validation |
+| `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 |
@@ -35,6 +35,6 @@ Use this file as repo-local agent context. It records the current governance arc
 
 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 generated adapter sync before release.
+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/dependency-map.md

@@ -21,7 +21,7 @@ Use this map to keep Agentic-Senior-Core's CLI, governance, and validation layer
 | `lib/cli/commands/upgrade.mjs` | detector, compiler, scaffolder seeds, backup/rollback, shared setup helpers | duplicated setup-policy helpers, silent stack migration |
 | `lib/cli/project-scaffolder.mjs` | stable public scaffolder exports | private validation helpers that do not need public API exposure |
 | `lib/cli/project-scaffolder/design-contract.mjs` | validation submodule, constants, utilities | hardcoded final palettes, fixed layouts, external design memory |
-| `scripts/sync-thin-adapters.mjs` | canonical instructions and adapter targets | hand-maintained duplicate policy blocks |
+| `scripts/sync-thin-adapters.mjs` | `AGENTS.md` and native import bridge targets | hand-maintained duplicate policy blocks |
 | `scripts/validate*.mjs` | config, coverage checks, file evidence | stale V2 skill-marketplace artifacts |
 | `.agent-context/prompts/bootstrap-design.md` | current repo evidence and frontend rule | prior-chat visuals, unrelated screenshots, template style presets |
 
@@ -30,7 +30,7 @@ Use this map to keep Agentic-Senior-Core's CLI, governance, and validation layer
 - Reject `commands -> project-scaffolder -> commands`.
 - Reject `compiler -> commands`.
 - Reject `scripts/validate -> tests`.
-- Reject generated adapters becoming inputs for `.instructions.md` or `.agent-context/`.
+- Reject generated adapters becoming inputs for `AGENTS.md` or `.agent-context/`.
 - Move repeated command setup policy into shared helper modules instead of copying local functions.
 
 ## Package Hygiene

package/AGENTS.md

@@ -1,44 +1,179 @@
-# AGENTS.md - Thin Adapter
+# Agentic-Senior-Core: Unified AI Agent Instructions
 
-Adapter Mode: thin
-Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
+Canonical project instructions. Resolve the smallest relevant layer set for the current request.
 
+## Role
+Act as a Principal Engineer. Ship maintainable, validated, production-ready work. Use clear plain language in formal artifacts. Do not use emoji.
+
+## Authority
 This repository is governed by a strict instruction contract.
-Use [.instructions.md](.instructions.md) as the canonical policy source.
-Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
-
-## Critical Bootstrap Floor
-
-- If your host stops at this file, continue the chain manually before coding.
-- Read `.agent-instructions.md` next when it exists.
-- Memory continuity does not replace bootstrap loading.
-- For UI, UX, layout, screen, tailwind, frontend, or redesign requests, load [bootstrap-design.md](.agent-context/prompts/bootstrap-design.md) and [frontend-architecture.md](.agent-context/rules/frontend-architecture.md) before code edits.
-- For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
-- For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
-- For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
-- Create or refine root README.md as the public and developer entrypoint before implementation.
-- For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](.agent-context/rules)).
-- For ecosystem, framework, dependency, or Docker claims, perform live web research.
-- Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.
-
-## Mandatory Bootstrap Chain
-
-1. Load [.instructions.md](.instructions.md).
-2. Load `.agent-instructions.md` when present.
-3. Load only relevant files from .agent-context/rules/ ([link](.agent-context/rules)).
-4. Apply matching prompts from .agent-context/prompts/ ([link](.agent-context/prompts)).
-5. Enforce .agent-context/review-checklists/ ([link](.agent-context/review-checklists/pr-checklist.md)).
-6. Use .agent-context/state/ ([link](.agent-context/state)) and .agent-context/policies/ ([link](.agent-context/policies)) only when relevant.
-7. Use project docs and live evidence for runtime, dependency, and architecture claims.
+
+Use `AGENTS.md` as the canonical baseline. Use `.agent-context/` as technical authority for rules, prompts, checklists, state, and policies. Use `README.md` only for public and developer overview, setup, usage, and user-facing context when stricter governance files conflict.
+
+Write instructions as imperative gates:
+- Use direct commands.
+- Prefer short mechanical checks over descriptive prose.
+- Keep root adapters thin.
+- Move detailed policy into `.agent-context/`.
+- Add validation when a rule can drift.
 
 ## Bootstrap Receipt
+For non-trivial coding, review, planning, or governance work, emit a concise Bootstrap Receipt before implementation output or file edits:
+- `loaded_files`: files actually read
+- `selected_rules`: files selected for this scope and why
+- `skipped_rules`: out-of-scope categories left unloaded
+- `unreachable_files`: required files that could not be read
+- `validation_plan`: expected checks before completion
+
+Keep it short. Do not load every rule just to fill it out.
+
+## Command Economy
+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]
+Location: `.agent-context/rules/`.
+
+Load only relevant rule files. Do not read the entire rule directory by default.
+
+Available rules: `naming-conv.md`, `architecture.md`, `security.md`, `performance.md`, `error-handling.md`, `testing.md`, `git-workflow.md`, `efficiency-vs-hype.md`, `api-docs.md`, `microservices.md`, `event-driven.md`, `database-design.md`, `realtime.md`, `frontend-architecture.md`, `docker-runtime.md`.
+
+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.
+
+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`.
+
+Use the union once when scopes overlap. Do not create framework-specific governance adapters.
+
+### Layer 2: Runtime Decision Signals
+
+Runtime Decision Signals come from project context, repo evidence, and live research. Runtime signals are evidence gates, not style cues or popularity rankings.
+
+For fresh projects, recommend runtime/framework from the brief, constraints, and live official docs before coding. For existing projects, treat detected markers as evidence only. Ignore pattern frequency, external rankings, and remembered defaults. Do not default web projects to Next.js, Tailwind-only styling, shadcn/ui, Vite, or any familiar web stack by habit, and do not avoid them because of this guard when they are the strongest project fit.
+
+### Layer 3: Structural Planning Signals
+
+Structural Planning Signals use dynamic structural planning from repo context, docs, runtime constraints, and live research. Structural planning signals are not a hard whitelist.
+
+For new projects or modules, extract constraints, boundaries, and required docs first. Do not silently choose frameworks or architecture from offline heuristics. If runtime or architecture is unresolved, produce a short recommendation from evidence and live official documentation before coding. Compare at least one plausible alternative when the strongest-looking option is a familiar web default and the user did not explicitly choose it.
+
+### Layer 4: Execution Contracts
+
+Execution Contracts are dynamic execution contracts from prompts, review checklists, and policy thresholds. Resolve the active contract, then enforce mandatory checks before declaring completion.
+
+### Layer 5: Prompts
+
+Location: `.agent-context/prompts/`.
+
+Load the matching prompt only:
+- `init-project.md` -> create, build, new project, scaffold
+- `refactor.md` -> refactor, improve, clean up, fix
+- `review-code.md` -> review, audit, check, analyze
+- `bootstrap-design.md` -> ui, ux, layout, screen, tailwind, frontend, redesign
+
+For UI-only work, load `bootstrap-design.md` and `frontend-architecture.md` first; do not eagerly load unrelated backend-only rules unless the request crosses that boundary. The valid style context is current repo evidence, current brief, and current project docs. External references, prior-chat memory, unrelated-project visuals, and remembered screenshots are tainted unless the user makes them current-task constraints. Treat WCAG 2.2 AA as the hard compliance floor and APCA as advisory perceptual tuning only. Do not require screenshot capture as a baseline dependency.
+
+### Layer 6: Governance Modes
+
+Governance Modes use dynamic governance context from state files, policies, and repo norms. Apply matching defaults only when relevant.
+
+### Layer 7: State and Benchmarks
+
+Use `.agent-context/state/` only when the task needs risk zones, dependency boundaries, benchmarks, or continuity metadata. For initialized projects, `.agent-context/state/onboarding-report.json` records selected profile, runtime evidence, architecture decision status, token optimization, and memory continuity.
+
+### Layer 8: Policies and Thresholds
+
+Use `.agent-context/policies/` for quality gates, release thresholds, and audit posture.
+
+### Layer 9: Project Context
+
+Use root `README.md` as the public and developer entrypoint for every fresh or existing project. Use `docs/doc-index.md` as the compact routing map when `docs/` exists. Use `docs/` when present: `project-brief.md`, `architecture-decision-record.md`, `database-schema.md`, `api-contract.md`, `flow-overview.md`, `DESIGN.md`, `design-intent.json`.
+
+## Mandatory Triggers
+
+### 1. Documentation-First Mode
+
+Trigger: docs, documentation, dokumen, `docs/*`, architecture docs, flow docs, API docs, or "lengkapkan docs".
+
+1. Load `architecture.md`, `api-docs.md`, and only additional rules required by scope.
+2. Create or refine required docs first: root `README.md` for every fresh or existing project; `docs/doc-index.md` whenever `docs/` exists; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md` for APIs, firmware endpoints, CLI commands, or web application flows; `docs/database-schema.md` for persistent data; and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
+3. Use `docs/doc-index.md` as the compact read-routing map. Add PRD, SRS, technical-design, or separate ERD only when project evidence justifies them.
+4. Write formal project docs in English by default unless the user asks otherwise.
+5. Stop after documentation when the user only asked for docs. Do not write application, firmware, or UI code until the user asks or approves implementation; do not write application, firmware, or UI code before approval.
+
+### 2. New Project Planning
+
+Trigger: create, build, new project, scaffold.
+
+1. Resolve relevant rules.
+2. Read `init-project.md`.
+3. Infer constraints, required docs, and boundaries from requirements, repo evidence, docs, and live research.
+4. Recommend runtime/architecture when unresolved.
+5. WAIT for user approval before generating code.
+
+### 3. Refactor Mode
+
+Trigger: refactor, improve, fix, clean up.
+
+1. Resolve relevant rules.
+2. Read `refactor.md`.
+3. Apply active prompt/checklist contracts.
+4. Propose a plan before edits.
+5. WAIT for approval.
+
+### 4. Code Review Mode
+
+Trigger: review, audit, check, analyze.
+
+Load `pr-checklist.md` and `architecture-review.md`, then report defects, risks, regressions, and missing tests first.
+
+### 5. UI Design Mode
+
+Trigger: ui, ux, layout, screen, tailwind, frontend, redesign.
+
+1. Read `bootstrap-design.md` and `frontend-architecture.md`.
+2. Read UI-relevant repo evidence from state, current UI code, and `docs/*`.
+3. Include a one-line Motion/Palette Decision before UI code; product categories are heuristics, not style presets.
+4. Before UI code, record one real-world anchor, one signature motion behavior, and one typographic role contrast.
+5. Ensure `docs/design-intent.json` includes `conceptualAnchor.anchorReference`, top-level `derivedTokenLogic`, `libraryResearchStatus`, `libraryDecisions[]`, and motion/palette decisions.
+6. Generate or refine `docs/DESIGN.md` plus `docs/design-intent.json` before UI implementation.
+7. Keep context isolated; do not eagerly load unrelated backend-only rules.
+8. In UI Design Mode, choose the ambition level proactively. For broad screens or redesigns, treat expressive motion, spatial hierarchy, distinctive composition, and product-specific interaction as the baseline even when the user did not say "rich"; quiet or static surfaces require a concrete product, performance, accessibility, device, or dependency reason.
+9. Do not let conceptual anchors collapse into room, darkroom, counting room, control room, war room, studio, lab, cockpit, or command center by habit. Prefer artifacts, workflows, custody chains, instruments, data behaviors, material systems, editorial systems, service rituals, or interaction mechanisms unless a physical place model is core to the product.
+10. External websites and benchmark examples are candidate evidence for constraints, mechanics, and quality bars only. Do not copy their layout rhythm, palette, component skin, visual metaphor, or brand posture without explicit user approval and product-fit rationale.
+
+## Reasoning Chain
+
+When rejecting an approach or enforcing a rule, use:
+
+```text
+REASONING CHAIN
+Problem: [risk]
+Required Action: [boundary]
+Why Required: [project protection]
+```
+
+## Definition of Done
+
+Never claim done without:
+1. Relevant rules applied.
+2. PR and architecture checklists considered.
+3. Universal SOP gates satisfied: public and developer root `README.md`; `docs/architecture-decision-record.md`; plus `docs/DESIGN.md` and `docs/design-intent.json` for UI scope.
+4. If `.agent-context/state/active-memory.json` exists and material project progress happened, refresh it while preserving privacy rules and user-owned entries.
+5. MCP validation passed through `npm run validate`.
 
-For non-trivial coding, review, planning, or governance work, produce a short Bootstrap Receipt before implementation output: `loaded_files`, `selected_rules`, `skipped_rules`, `unreachable_files`, and `validation_plan`.
+## Knowledge Inventory Checklist
 
-## Completion Gate
+Verify reachability when relevant: Layer 1 Rules, Layer 2 Runtime Decision Signals, Layer 3 Structural Planning Signals, Layer 4 Execution Contracts, Layer 5 Prompts, Layer 6 Governance Modes, Layer 7 State, Layer 8 Policies, Layer 9 Project Context.
 
-Run [pr-checklist.md](.agent-context/review-checklists/pr-checklist.md) before declaring work complete.
+## Operating Gates
 
-If this adapter drifts from canonical behavior, refresh from [.instructions.md](.instructions.md) and update the hash metadata.
+- Before code: resolve active rules and contract.
+- Before PR: run review checklists.
+- Before deploy: check policy thresholds.
+- Before major refactor: read `architecture-map.md`.
+- Before UI implementation: confirm valid style context, design contract, and required docs.

package/CLAUDE.md

@@ -1,44 +1 @@
-# CLAUDE.md - Thin Adapter
-
-Adapter Mode: thin
-Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
-
-This repository is governed by a strict instruction contract.
-Use [.instructions.md](.instructions.md) as the canonical policy source.
-Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
-
-## Critical Bootstrap Floor
-
-- If your host stops at this file, continue the chain manually before coding.
-- Read `.agent-instructions.md` next when it exists.
-- Memory continuity does not replace bootstrap loading.
-- For UI, UX, layout, screen, tailwind, frontend, or redesign requests, load [bootstrap-design.md](.agent-context/prompts/bootstrap-design.md) and [frontend-architecture.md](.agent-context/rules/frontend-architecture.md) before code edits.
-- For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
-- For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
-- For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
-- Create or refine root README.md as the public and developer entrypoint before implementation.
-- For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](.agent-context/rules)).
-- For ecosystem, framework, dependency, or Docker claims, perform live web research.
-- Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.
-
-## Mandatory Bootstrap Chain
-
-1. Load [.instructions.md](.instructions.md).
-2. Load `.agent-instructions.md` when present.
-3. Load only relevant files from .agent-context/rules/ ([link](.agent-context/rules)).
-4. Apply matching prompts from .agent-context/prompts/ ([link](.agent-context/prompts)).
-5. Enforce .agent-context/review-checklists/ ([link](.agent-context/review-checklists/pr-checklist.md)).
-6. Use .agent-context/state/ ([link](.agent-context/state)) and .agent-context/policies/ ([link](.agent-context/policies)) only when relevant.
-7. Use project docs and live evidence for runtime, dependency, and architecture claims.
-
-## Bootstrap Receipt
-
-For non-trivial coding, review, planning, or governance work, produce a short Bootstrap Receipt before implementation output: `loaded_files`, `selected_rules`, `skipped_rules`, `unreachable_files`, and `validation_plan`.
-
-## Completion Gate
-
-Run [pr-checklist.md](.agent-context/review-checklists/pr-checklist.md) before declaring work complete.
-
-If this adapter drifts from canonical behavior, refresh from [.instructions.md](.instructions.md) and update the hash metadata.
+@AGENTS.md

package/CONTRIBUTING.md

@@ -13,7 +13,6 @@ Thanks for wanting to make AI agents write better code. Here's how to contribute
 | Structural planning guidance update | `.agent-context/prompts/`, `lib/cli/compiler.mjs` | Scope planning, docs bootstrap, and project-context guidance |
 | New checklist | `.agent-context/review-checklists/` | Self-audit guide |
 | State intelligence update | `.agent-context/state/` | Architecture boundaries and dependency map |
-| Override policy update | `.agent-override.md` | Scoped rule exceptions |
 | MCP workflow update | `mcp.json` | Self-healing automation flow |
 | Bug fix | Any file | Typos, broken links, incorrect rules |
 | Improvement | Any file | Sharper wording, stricter boundaries |
@@ -63,7 +62,7 @@ If all three are "yes", it belongs here.
    - Core principle (1-2 sentences)
    - BANNED / REQUIRED sections with enforceable boundaries
    - Decision tree or quick ruleset when it reduces ambiguity
-3. Update `.instructions.md` or `.agent-context/` as the source, then regenerate thin adapters with `npm run sync:adapters`
+3. Update `AGENTS.md` or `.agent-context/` as the source, then verify thin adapters with `npm run check:adapters`
 4. Update `review-checklists/pr-checklist.md` when the rule is part of review scope
 5. Validate and PR
 
@@ -88,7 +87,7 @@ If all three are "yes", it belongs here.
 - Generic content that reads like it was auto-generated without thought
 - Rules without concrete enforcement boundaries
 - Stack profiles for languages the author doesn't actually use in production
-- PRs that don't update the relevant source files, generated adapters, and checklists
+- PRs that don't update the relevant source files, docs, validators, and checklists
 
 ---
 

package/GEMINI.md

@@ -1,44 +1 @@
-# GEMINI.md - Thin Adapter
-
-Adapter Mode: thin
-Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 728c7ecaa49ea69a3e9b03c1c88d25f310a1827f2cebb72de102b5ae5005ff0e
-
-This repository is governed by a strict instruction contract.
-Use [.instructions.md](.instructions.md) as the canonical policy source.
-Use .agent-context/ for technical rules, prompts, checklists, policies, and state.
-Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.
-
-## Critical Bootstrap Floor
-
-- If your host stops at this file, continue the chain manually before coding.
-- Read `.agent-instructions.md` next when it exists.
-- Memory continuity does not replace bootstrap loading.
-- For UI, UX, layout, screen, tailwind, frontend, or redesign requests, load [bootstrap-design.md](.agent-context/prompts/bootstrap-design.md) and [frontend-architecture.md](.agent-context/rules/frontend-architecture.md) before code edits.
-- For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.
-- For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.
-- For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.
-- Create or refine root README.md as the public and developer entrypoint before implementation.
-- For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](.agent-context/rules)).
-- For ecosystem, framework, dependency, or Docker claims, perform live web research.
-- Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.
-
-## Mandatory Bootstrap Chain
-
-1. Load [.instructions.md](.instructions.md).
-2. Load `.agent-instructions.md` when present.
-3. Load only relevant files from .agent-context/rules/ ([link](.agent-context/rules)).
-4. Apply matching prompts from .agent-context/prompts/ ([link](.agent-context/prompts)).
-5. Enforce .agent-context/review-checklists/ ([link](.agent-context/review-checklists/pr-checklist.md)).
-6. Use .agent-context/state/ ([link](.agent-context/state)) and .agent-context/policies/ ([link](.agent-context/policies)) only when relevant.
-7. Use project docs and live evidence for runtime, dependency, and architecture claims.
-
-## Bootstrap Receipt
-
-For non-trivial coding, review, planning, or governance work, produce a short Bootstrap Receipt before implementation output: `loaded_files`, `selected_rules`, `skipped_rules`, `unreachable_files`, and `validation_plan`.
-
-## Completion Gate
-
-Run [pr-checklist.md](.agent-context/review-checklists/pr-checklist.md) before declaring work complete.
-
-If this adapter drifts from canonical behavior, refresh from [.instructions.md](.instructions.md) and update the hash metadata.
+@AGENTS.md

package/README.md

@@ -10,12 +10,13 @@
 **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.
 
-Latest release: 3.0.40 (2026-04-30).
+Current package version: 3.0.48.
 
-Highlights in 3.0.40:
-- Adds a mandatory complexity budget so agents choose fewer moving parts only when quality stays intact.
-- Refactor guidance now requires a final simplification pass before completion.
-- Release tooling keeps legacy root adapter version metadata aligned with package bumps.
+Highlights:
+- Uses `AGENTS.md` as the canonical instruction entrypoint.
+- Keeps Claude Code and Gemini bridges as native `@AGENTS.md` imports.
+- Loads detailed rules lazily from `.agent-context/` by task scope.
+- Keeps MCP workspace files opt-in through `--mcp-template`.
 
 </div>
 
@@ -29,11 +30,12 @@ Highlights in 3.0.40:
 npx @ryuenn3123/agentic-senior-core init
 ```
 
-One command to initialize rules, checklists, thin discovery adapters, and a compiled AI rulebook for your project.
+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/deep-dive.md](docs/deep-dive.md) and [docs/roadmap.md](docs/roadmap.md) for advanced configuration, planning mode, snapshot, and realtime options.**
+> **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.**
 
-- This command writes `.agent-context/state/v3-purge-audit.json` and reports whether static directory deletion is safe.
+- 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.
 - When project docs are scaffolded, `docs/doc-index.md` is used as the compact map for deeper docs so agents can read the right files without scanning every Markdown file.
 - Local backup snapshots are written under `.agentic-backup/`; init and upgrade ensure that folder is ignored by the target repository.
 - Package scope is `@ryuenn3123`; the GitHub repository owner is `fatidaprilian`.
@@ -76,8 +78,8 @@ If you see `Property $schema is not allowed`, keep `.vscode/mcp.json` without `$
 
 | Command | Purpose |
 |---------|---------|
-| `agentic-senior-core init` | Initialize the project guidance pack, thin adapters, and compiled AI rulebook |
-| `agentic-senior-core upgrade --dry-run` | Preview safe upgrades |
+| `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 |
@@ -94,26 +96,24 @@ npx @ryuenn3123/agentic-senior-core upgrade --yes
 
 Use `--dry-run` first to preview changes safely, then apply with `--yes`.
 
-Upgrade now performs managed-surface synchronization by default: obsolete governance files under managed paths are pruned so the pack stays aligned with the latest release.
+Upgrade now performs managed-surface synchronization by default: obsolete Agentic-managed instruction files are pruned so the pack stays aligned with the latest release.
 Use `--no-prune` if you want to keep legacy managed files.
 
 When upgrade creates `.agentic-backup/`, it also keeps the target root `.gitignore` aligned with that local-only backup folder. The backup is for rollback safety, not a source of truth and not a file to commit.
 
 ## Instruction Entrypoints
 
-The canonical source is `.instructions.md`.
+The canonical installed source is `AGENTS.md`.
 
-Generated bridge files stay small:
+Default init and upgrade now keep the project root compact:
 - `AGENTS.md`
 - `CLAUDE.md`
 - `GEMINI.md`
-- `.cursor/rules/agentic-senior-core.mdc`
-- `.windsurf/rules/agentic-senior-core.md`
-- `.github/copilot-instructions.md`
-- `.github/instructions/agentic-senior-core.instructions.md`
-- `.gemini/instructions.md`
+- `.agent-context/`
 
-Legacy root files `.cursorrules`, `.windsurfrules`, and `.clauderc` are thin compatibility adapters. They point to `.agent-instructions.md` when the compiled rulebook exists, with `.instructions.md` as the fallback source.
+`CLAUDE.md` and `GEMINI.md` are native import bridges that load `AGENTS.md`. Detailed rules, prompts, checklists, policies, and state stay under `.agent-context/` and load by task scope.
+
+Deprecated legacy files such as `.instructions.md`, `.agent-instructions.md`, `.cursorrules`, `.windsurfrules`, `.agent-override.md`, tool-specific rule directories, and copied Copilot/Gemini instruction folders are no longer generated by default. Upgrade prunes Agentic-managed copies while preserving user-owned files without Agentic markers.
 
 ---
 
@@ -159,9 +159,11 @@ This repository publishes to npm automatically through GitHub Actions on every p
 
 Release checklist:
 
-1. Bump `package.json` version.
-2. Add matching release notes in `CHANGELOG.md`.
-3. Push to `main`.
+1. Run `node scripts/bump-version.mjs <version>`.
+2. Fill the matching release notes in `CHANGELOG.md`.
+3. Run `npm run check:adapters`, `npm run validate`, `npm test`, `npm run gate:release`, and `git diff --check`.
+4. Commit with a Conventional Commit message.
+5. Push to `origin/main`.
 
 Important notes: