@ryuenn3123/agentic-senior-core 4.1.0 → 4.2.1

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

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

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

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

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

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

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

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

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

@@ -143,3 +143,13 @@ keywords:
 1. Import through a module's public API instead of reaching into internal files.
 2. Keep contracts explicit at boundaries between modules.
 3. If a new developer cannot find the full flow of a feature in one clear area, the structure is too diffuse.
+
+## ARCH-013: Natural Implementation Pass
+
+1. Treat "human-readable" code as code that a maintainer can trace, test, and change safely. Do not optimize for looking hand-written at the expense of behavior.
+2. Write new code and refactors as a clear sequence of intent: validate the input, name the domain state, perform the operation, then return or report the outcome.
+3. Prefer early returns for invalid, empty, or unauthorized paths when they reduce nesting and make the happy path easier to follow.
+4. Keep functions focused on one responsibility, but do not create tiny helper chains unless the helper names a real domain condition, removes repeated logic, or makes the main flow easier to read.
+5. Avoid dense one-liners, nested ternaries, speculative classes, factories, interfaces, design patterns, and extra layers when direct code preserves the same guarantees.
+6. Match the local project style before introducing a new pattern. Do not make code generic enough to fit any product.
+7. Run a final naturalness pass before completion: domain names are specific, booleans expose state or permission, comments explain why only, edge cases are explicit, and simplification did not remove validation, error handling, fallbacks, accessibility, tests, security boundaries, or observability.

package/.agent-context/rules/naming-conv.md

@@ -27,6 +27,9 @@ Use the target language and framework conventions. Do not invent a naming style
 3. Reject names that require reading the implementation to understand the value.
 4. Keep file and directory naming styles consistent inside the same feature unless a framework reason requires mixed styles.
 5. Reject booleans, units, and side-effect functions whose names hide what they represent or change.
-6. Inline comments must explain why, not what.
-7. Put a one-line rationale near non-obvious choices that deserve explanation, such as retry strategy, index column order, denormalized field, intentional swallow with named recovery, or magic constant tied to an external system.
-8. Treat comments that paraphrase the code as noise.
+6. Name collections as collections when the language convention supports it.
+7. Name side-effect functions with an action plus the domain outcome they change.
+8. Avoid broad function names that describe activity without domain intent.
+9. Inline comments must explain why, not what.
+10. Put a one-line rationale near non-obvious choices that deserve explanation, such as retry strategy, index column order, denormalized field, intentional swallow with named recovery, or magic constant tied to an external system.
+11. Treat comments that paraphrase the code as noise.

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

@@ -17,8 +17,9 @@ Tracked operational artifact:
 
 Local-only/generated artifacts:
 - `active-memory.json`
-- `v3-purge-audit.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/AGENTS.md

@@ -18,17 +18,17 @@ Write instructions as imperative gates:
 - 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:
+For non-trivial coding, review, planning, or governance work, run `agentic-senior-core context` first if available, or `npx @ryuenn3123/agentic-senior-core context` when only the package is available, then 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.
+Keep it short. Do not load every rule just to fill it out. Skip this receipt and do not run the context command for trivial tasks (e.g., simple version bumps, minor typo fixes, or simple commits).
 
-## 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.
+## Default Activation And Command Economy
+At session start, enforce default-on surfaces: run `agentic-senior-core context` for non-trivial work, prefer `ascx git status` / `ascx git diff` / `ascx npm test` when available, and apply `compact-natural-mode.md` for final replies. Avoid repeated command output; use raw commands for pipes, redirects, or unsupported commands.
 
 ## Layer Index
 ### Layer 1: Rules (21 Files) [SCOPE-RESOLVED]
@@ -67,9 +67,8 @@ Execution Contracts are dynamic execution contracts from prompts, review checkli
 
 ### Layer 5: Prompts
 
-Location: `.agent-context/prompts/`.
-
-Load the matching prompt only:
+Location: `.agent-context/prompts/`. Load the matching prompt only, plus `compact-natural-mode.md` as the default final-response contract:
+- `compact-natural-mode.md` -> final response shape, evidence preservation, and compact natural prose
 - `init-project.md` -> create, build, new project, scaffold
 - `refactor.md` -> refactor, improve, clean up, fix
 - `review-code.md` -> review, audit, check, analyze
@@ -159,7 +158,6 @@ Action: one-line bounded next step
 Use valid rule IDs only; do not quote full rule prose, expose hidden chain-of-thought, or require the block for trivial replies.
 
 ## Definition of Done
-
 Never claim done without:
 1. Relevant rules applied.
 2. PR and architecture checklists considered.

package/README.md

@@ -7,93 +7,89 @@
 [![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)
 
-**Production-grade Rules Engine (Governance Engine) for AI coding agents.**
+**Production-grade Rules Engine for AI coding agents.**
 Works with Cursor, Windsurf, GitHub Copilot, Claude Code, Gemini, and other LLM-powered IDE workflows.
 
-Current package version: 4.1.0. Last published version before this release: 4.0.3.
-
-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>
 
 ---
 
-## Why this exists
+## Install
 
-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.
-
----
+```bash
+npx @ryuenn3123/agentic-senior-core init
+```
 
-## What's New in v4.1
+Initializes `AGENTS.md`, native import bridges, checklists, policies, state files, and the lazy `.agent-context/` rule library. Token optimization and Compact Natural Mode are enabled by default.
 
-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.
+Options:
+- Add `--mcp-template` to generate VS Code MCP workspace config.
+- Default init keeps MCP files opt-in.
+- Add `--no-token-optimize` only when you do not want ASCX command guidance enabled.
+- Local backup snapshots are written under `.agentic-backup/` and excluded from version control.
 
-- `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.
+## Upgrade
 
-Plus targeted refinements to four existing rules:
+```bash
+npx @ryuenn3123/agentic-senior-core upgrade --dry-run
+npx @ryuenn3123/agentic-senior-core upgrade --yes
+```
 
-- `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).
+Preview changes with `--dry-run`, then apply with `--yes`. Upgrade prunes obsolete managed files by default; use `--no-prune` to keep them. User-owned files without Agentic markers are never overwritten.
 
-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)
+## Core Commands
 
-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:
+| Command | Purpose |
+|---------|---------|
+| `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 context "<request>" --json --file src/app/page.tsx` | Resolve request labels, rules, prompts, docs, file signals, budget status, and fallback status |
+| `ascx git status` | Run `git status` through the local evidence-preserving output wrapper |
+| `ascx git diff` | Run `git diff` through the local evidence-preserving diff summary wrapper |
+| `ascx npm test` | Run `npm test` through the local evidence-preserving output wrapper |
+| `asc optimize status` | Check ASCX runtime token saver readiness |
+| `asc optimize doctor` | Diagnose ASCX availability, tee write safety, and compression conflicts |
+| `agentic-senior-core optimize --show` | Show token optimization state |
+| `agentic-senior-core mcp` | Start local MCP stdio runtime |
+| `npm run clean:local` | Remove ignored local reports, backups, benchmarks, and active-memory state |
 
-- Rules are now citable by ID, which the new bounded reflection block in `AGENTS.md` and the validation MCP tools (`lookup_rule`, `validate_against_rules`, `audit_compliance`) rely on.
-- A three-layer prompt caching contract (D4 in `docs/architecture/decisions-foundation.md`) is now enforced by `npm run audit:cache-layer-contract`.
-- A provider-free anti-halu benchmark is included (`benchmarks/anti-halu/`); pass rate and citation validity are reproducible locally.
-- Caching numbers are scoped per integration. The 89.31% Anthropic warm-cache effective reduction reported in `benchmarks/results/cache-phase-2-2026-05-16.json` applies to direct provider API and Claude Code SDK programmatic mode only. IDE wrapper integrations (Cursor, Windsurf, Codex CLI, Kiro) receive prefix stability without a measurable per-pack saving. See `docs/integration-playbook.md` for the per-tool matrix and `docs/benchmark-reference.md` for the required reporting JSON shape.
+`ascx` currently compresses only `git status`, `git diff`, and `npm test`. Other commands, pipes, redirects, and unsupported shell shapes pass through without compression. Compressed output includes a structured footer with command, exit code, filter name, estimated token reduction, and a raw tee path when safety requires it.
 
+`asc` is a short alias for the main `agentic-senior-core` CLI. The doctor does not probe localhost services in this phase; `9router` status remains `not-checked`.
 
-## 60-Second Start
+---
 
+## What It Does
 
-```bash
-npx @ryuenn3123/agentic-senior-core init
-```
+A coding agent that has read every framework tutorial 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. The rules are written as invariants and bad habits to reject, not as opinions about which framework is fashionable. You install it with one command, revert with a backup, and it does not depend on any IDE or LLM provider.
 
-One command to initialize `AGENTS.md`, native import bridges, checklists, policies, state files, and the lazy `.agent-context/` rule library for your project.
+### How It Works
 
-> **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.**
+1. Agent reads `AGENTS.md` at the start of each session.
+2. `AGENTS.md` activates the default triad: Adaptive Context for scoped rule selection, ASCX wrappers for supported noisy commands, and Compact Natural Mode for final replies.
+3. For shell commands, the agent uses `ascx` wrappers that compress noisy output while preserving debugging evidence (exit codes, file paths, line numbers, root errors, truncation markers, and raw tee paths).
+4. For final replies, the agent applies `.agent-context/prompts/compact-natural-mode.md` so answers stay concise without losing commands, paths, errors, assumptions, validation status, risks, or next actions.
+5. Detailed rules live under `.agent-context/rules/` and load by scope: 21 rule files covering architecture, security, performance, testing, database, API, frontend, Docker, observability, resilience, migrations, background jobs, configuration, and versioning.
 
-- 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`.
+### Instruction Entrypoints
 
----
+The canonical installed source is `AGENTS.md`.
 
-## Design Direction
+Default init and upgrade keep the project root compact:
+- `AGENTS.md`
+- `CLAUDE.md`
+- `GEMINI.md`
+- `.agent-context/`
 
-For UI, UX, layout, screen, Tailwind, frontend, or redesign work, the pack routes agents through the design bootstrap and frontend architecture rules before code changes.
+`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.
 
-The intended behavior is agent-led, not offline-template-led:
+Deprecated legacy files (`.instructions.md`, `.agent-instructions.md`, `.cursorrules`, `.windsurfrules`, tool-specific rule directories) are no longer generated. Upgrade prunes Agentic-managed copies while preserving user-owned files.
 
-- Existing projects: read the real repository, docs, UI surface, and current user brief before changing design.
-- Fresh projects: ask the LLM agent to recommend the stack and design approach from current evidence instead of silently choosing a hardcoded framework.
-- No visual reference provided: synthesize one modern conceptual anchor first, then derive typography, spacing, morphology, motion, and responsive behavior from that anchor.
-- Modern UI claims: research current-year libraries and patterns when relevant; 2026 work should use 2026 evidence, and future years should update automatically through agent research.
-- Anti-generic rule: avoid safe dashboard shells, admin panels, card grids, scale-only mobile layouts, and static no-motion interfaces unless the product context explicitly justifies them.
+### Long-Term Stability
 
-UI design work runs a research dossier prompt (`.agent-context/prompts/research-design.md`) before the bootstrap prompt. The dossier captures product reading, reference intake, category cliches, a morphological matrix, and five anchor candidates with a strengthened rename test. The contract carries a 90-day `researchVerifiedAt` freshness gate and an anti-repeat ledger seeded from prior anchor, palette, motion, and typography choices on existing projects, so additive UI work within the freshness window skips the research stage while redesigns and stale dossiers re-run it.
+Rules are written as invariants, outcomes, and freshness criteria, not as named patterns, library prescriptions, or magic-number thresholds. Where a rule cites a specific tool or threshold, the citation block carries a freshness anchor so the next maintainer knows when the technology references were last validated.
 
 ---
 
@@ -115,64 +111,40 @@ If you see `Property $schema is not allowed`, keep `.vscode/mcp.json` without `$
 
 ---
 
-## Core Commands
+## Design Direction
 
-| Command | Purpose |
-|---------|---------|
-| `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 clean:local` | Remove ignored local reports, backups, benchmarks, and active-memory state |
-| `agentic-senior-core mcp` | Start local MCP stdio runtime |
+For UI, UX, layout, screen, Tailwind, frontend, or redesign work, the pack routes agents through a research dossier prompt and design bootstrap before code changes. The flow synthesizes a conceptual anchor, derives typography, spacing, morphology, motion, and responsive behavior, and carries a 90-day freshness gate with an anti-repeat ledger to avoid recycling the same visual direction. Existing projects read the real repository and docs first; fresh projects ask the agent to recommend the stack from current evidence instead of hardcoding a framework.
+
+See [docs/doc-index.md](docs/doc-index.md) for the full doc routing map.
 
 ---
 
-## Upgrade Existing Governance Pack
+## What's New
 
-```bash
-npx @ryuenn3123/agentic-senior-core upgrade --dry-run
-npx @ryuenn3123/agentic-senior-core upgrade --yes
-```
+### v4.2
 
-Use `--dry-run` first to preview changes safely, then apply with `--yes`.
+Adds `ascx` command wrapper to optimize token usage via high-signal adapters for `git status`, `git diff`, and `npm test` alongside the `Compact Natural Mode` response compression contract to reduce token overhead while retaining high-fidelity reasoning.
 
-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.
+### v4.1
 
-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.
+Adds six backend rule files (`OBS-*`, `RES-*`, `MIG-*`, `JOB-*`, `CFG-*`, `VER-*`) and targeted refinements to `frontend-architecture.md`, `security.md`, `database-design.md`, and `api-docs.md`. See [CHANGELOG.md](CHANGELOG.md) for the full list.
 
-## Instruction Entrypoints
+### v4.0
 
-The canonical installed source is `AGENTS.md`.
+Numbered Markdown rules with stable section IDs, bounded reflection, provider-free anti-halu benchmark, three-layer prompt caching contract, and per-integration caching scope enforcement. Caching numbers are scoped per integration; IDE wrapper integrations receive prefix stability without a measurable per-pack saving. See [docs/benchmark-reference.md](docs/benchmark-reference.md) for the reporting format and [CHANGELOG.md](CHANGELOG.md) for details.
 
-Default init and upgrade now keep the project root compact:
-- `AGENTS.md`
-- `CLAUDE.md`
-- `GEMINI.md`
-- `.agent-context/`
-
-`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.
+Current package version: 4.2.0. Last published version: 4.0.3.
 
 ---
 
-## Terminology Mapping (Final)
-
-| Canonical Term | Developer-Facing Alias | Usage Rule |
-|----------------|------------------------|------------|
-| Federated Governance | Federated Rules Operations | Use canonical term in formal policy artifacts. |
-| Governance Engine | Rules Engine | Use alias in onboarding and day-to-day developer docs. |
-| Guardrails | Quality Checks | Use alias in implementation guidance and quickstart docs. |
-
-Rule: on first mention in developer-facing docs, include canonical term in parentheses.
-
-Examples:
-- `Federated Rules Operations (Federated Governance)`
-- `Rules Engine (Governance Engine)`
-- `quality checks (guardrails)`
+## Validation
 
-Compliance boundary: formal policy and audit artifacts must keep canonical terminology for operational traceability.
+```bash
+npm run validate
+npm test
+npm run gate:release
+npm run benchmark:ascx
+```
 
 ---
 
@@ -180,26 +152,16 @@ Compliance boundary: formal policy and audit artifacts must keep canonical termi
 
 - FAQ: docs/faq.md
 - Deep dive internals: docs/deep-dive.md
-- Project history (phase outcomes, archived playbooks, retired roadmap): docs/archive/HISTORY.md
+- Deep analysis and roadmap: docs/deep-analysis-and-roadmap-backlog.md
 - Integration playbook: docs/integration-playbook.md
 - Benchmark and stack reference: docs/benchmark-reference.md
-- Active roadmap and backlog: docs/deep-analysis-and-roadmap-backlog.md
-
----
-
-## Validation
-
-```bash
-npm run validate
-npm test
-npm run gate:release
-```
+- Project history: docs/archive/HISTORY.md
 
 ---
 
 ## Release and npm Publish Flow
 
-This repository publishes to npm automatically through GitHub Actions on every push to `main`.
+This repository publishes to npm through GitHub Actions on push to `main`.
 
 Release checklist:
 
@@ -209,10 +171,26 @@ Release checklist:
 4. Commit with a Conventional Commit message.
 5. Push to `origin/main`.
 
-Important notes:
+Package scope: `@ryuenn3123`. GitHub owner: `fatidaprilian`.
+
+---
+
+## Terminology Mapping (Final)
+
+| Canonical Term | Developer-Facing Alias | Usage Rule |
+|----------------|------------------------|------------|
+| Federated Governance | Federated Rules Operations | Use canonical term in formal policy artifacts. |
+| Governance Engine | Rules Engine | Use alias in onboarding and day-to-day developer docs. |
+| Guardrails | Quality Checks | Use alias in implementation guidance and quickstart docs. |
+
+Rule: on first mention in developer-facing docs, include canonical term in parentheses.
 
-- If the npm version already exists, publish fails.
-- Publish requires valid `NPM_TOKEN` in repository secrets.
+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.
 
 ---
 

package/benchmarks/README.md

@@ -0,0 +1,60 @@
+# Benchmarks
+
+Reproducible measurement suites for this repository. Release-facing claims must point to tracked JSON evidence under `benchmarks/results/` or to deterministic benchmark commands that print machine-readable output.
+
+## Folder Structure
+
+```text
+benchmarks/
+|-- anti-halu/              Provider-free anti-hallucination fixtures and scorer
+|-- compact-natural-mode/   Response compression fixtures and scorer
+|-- runtime-token-saver/    ASCX command-output compression fixtures
+|-- token-usage/            Provider token-counting and cache simulation benchmark
+|-- results/                Tracked release evidence JSON
+`-- README.md
+```
+
+## Active Benchmarks
+
+| Suite | Folder | Status | Output |
+| --- | --- | --- | --- |
+| Token usage baseline | `token-usage/` | Historical release evidence | `results/baseline-{YYYY-MM-DD}.json` |
+| Cache simulation | `token-usage/` | Historical release evidence | `results/cache-phase-2-{YYYY-MM-DD}.json` |
+| Anti-halu benchmark | `anti-halu/` | Active deterministic gate | `results/anti-halu-phase-3-{YYYY-MM-DD}.json` |
+| ASCX runtime token saver | `runtime-token-saver/` | Active deterministic gate | stdout via `npm run benchmark:ascx` |
+| Compact Natural Mode | `compact-natural-mode/` | Active deterministic gate | stdout via `npm run benchmark:compact-natural` |
+| Release benchmark bundle | `results/` | Active integrity gate | `results/release-bundle-{semver}.json` |
+
+## Running Benchmarks
+
+Use the package scripts for active gates:
+
+```bash
+npm run benchmark:adaptive-context
+npm run benchmark:ascx
+npm run benchmark:compact-natural
+npm run benchmark:anti-halu
+npm run build:release-bundle
+npm run audit:release-bundle
+```
+
+See `benchmarks/token-usage/README.md` for the provider token-counting benchmark details.
+
+## Reproducibility Requirements
+
+1. Use Node 22 or the runtime version documented by the current package metadata.
+2. Do not add runtime dependencies to the core package for benchmark-only work. Benchmark tooling belongs in `devDependencies`.
+3. Keep JSON output deterministic where possible. If timestamps or host facts vary, isolate them in metadata fields.
+4. Include schema version, timestamp, and tooling version when a result file is tracked so older evidence remains interpretable.
+
+## Result Files Convention
+
+- Track release evidence under `benchmarks/results/*.json`.
+- Use `{suite-name}-{YYYY-MM-DD}.json` or `{suite-name}-{semver}.json`.
+- Do not store raw API responses, secrets, tokens, or user data.
+- Historical phase outcomes are consolidated in `docs/archive/HISTORY.md`.
+- Live benchmark reporting rules are in `docs/benchmark-reference.md`.
+
+## Why This Exists
+
+Claims such as "40% token saving" or "rule adherence improved" need reproducible evidence. These suites are the comparator surface for README, changelog, release, and planning claims.