@ryuenn3123/agentic-senior-core 4.0.3 → 4.2.0

package/README.md

@@ -2,68 +2,94 @@
 
 # Agentic-Senior-Core
 
-### Force your AI Agent to code like a Staff Engineer, not a Junior.
+### Change your AI Agent to code like a Staff Engineer, not a Junior.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
 
-**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.0.0. Last published version before this release: 3.0.50.
-
-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>
 
 ---
 
-## What's New in v4
-
-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:
+## Install
 
-- 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.
+```bash
+npx @ryuenn3123/agentic-senior-core init
+```
 
+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.
 
-## 60-Second Start
+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.
 
+## Upgrade
 
 ```bash
-npx @ryuenn3123/agentic-senior-core init
+npx @ryuenn3123/agentic-senior-core upgrade --dry-run
+npx @ryuenn3123/agentic-senior-core upgrade --yes
 ```
 
-One command to initialize `AGENTS.md`, native import bridges, checklists, policies, state files, and the lazy `.agent-context/` rule library for your project.
+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.
+
+---
+
+## Core Commands
+
+| 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 |
 
-> **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.**
+`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.
 
-- 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`.
+`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`.
 
 ---
 
-## Design Direction
+## What It Does
+
+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.
 
-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.
+### How It Works
 
-The intended behavior is agent-led, not offline-template-led:
+1. Agent reads `AGENTS.md` at the start of each session.
+2. `AGENTS.md` instructs the agent to run the Adaptive Context resolver, which selects only the rules, prompts, and docs relevant to the current task.
+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.
 
-- 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.
+### Instruction Entrypoints
 
-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.
+The canonical installed source is `AGENTS.md`.
+
+Default init and upgrade 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 (`.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.
+
+### Long-Term Stability
+
+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.
 
 ---
 
@@ -85,60 +111,40 @@ If you see `Property $schema is not allowed`, keep `.vscode/mcp.json` without `$
 
 ---
 
-## Core Commands
-
-| 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 audit:v3-purge` | Run deep purge readiness audit (no deletion) |
-| `npm run clean:local` | Remove ignored local reports, backups, benchmarks, and active-memory state |
-| `agentic-senior-core mcp` | Start local MCP stdio runtime |
+## Design Direction
 
----
+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.
 
-## Upgrade Existing Governance Pack
+See [docs/doc-index.md](docs/doc-index.md) for the full doc routing map.
 
-```bash
-npx @ryuenn3123/agentic-senior-core upgrade --dry-run
-npx @ryuenn3123/agentic-senior-core upgrade --yes
-```
+---
 
-Use `--dry-run` first to preview changes safely, then apply with `--yes`.
+## What's New
 
-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.2
 
-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 `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.
 
-## Instruction Entrypoints
+### v4.1
 
-The canonical installed source is `AGENTS.md`.
+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.
 
-Default init and upgrade now keep the project root compact:
-- `AGENTS.md`
-- `CLAUDE.md`
-- `GEMINI.md`
-- `.agent-context/`
+### v4.0
 
-`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.
+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.
 
-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.
+## Validation
 
-Full mapping reference: docs/terminology-mapping.md
+```bash
+npm run validate
+npm test
+npm run gate:release
+npm run benchmark:ascx
+```
 
 ---
 
@@ -146,27 +152,16 @@ Full mapping reference: docs/terminology-mapping.md
 
 - FAQ: docs/faq.md
 - Deep dive internals: docs/deep-dive.md
-- Archived V2 upgrade playbook: docs/archive/v2-upgrade-playbook.md
+- 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
-- Terminology mapping reference: docs/terminology-mapping.md
-- Product roadmap: docs/roadmap.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:
 
@@ -176,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.
+
+Examples:
+- `Federated Rules Operations (Federated Governance)`
+- `Rules Engine (Governance Engine)`
+- `quality checks (guardrails)`
 
-- If the npm version already exists, publish fails.
-- Publish requires valid `NPM_TOKEN` in repository secrets.
+Compliance boundary: formal policy and audit artifacts must keep canonical terminology for operational traceability.
 
 ---
 

package/benchmarks/README.md

@@ -0,0 +1,40 @@
+# Benchmarks
+
+Reproducible measurement suites untuk repo ini. Setiap release publish hasil benchmark di `benchmarks/results/{name}-{date}.json` supaya klaim bisa diverifikasi.
+
+## Folder Structure
+
+```
+benchmarks/
+├── token-usage/        Token measurement per provider untuk rules pack delivery
+├── results/            Output JSON yang dipublish per release (tracked di git)
+└── README.md
+```
+
+## Active Benchmarks
+
+| Suite | Folder | Status | Output |
+|-------|--------|--------|--------|
+| Token usage baseline | `token-usage/` | Phase 0 (in progress) | `results/baseline-{YYYY-MM-DD}.json` |
+
+## Running Benchmarks
+
+Setiap suite punya README sendiri di sub-folder. Lihat `token-usage/README.md` untuk instruksi spesifik.
+
+## Reproducibility Requirements
+
+1. Node version: lihat `package.json#engines` (jika ada) atau gunakan Node 22 LTS minimum.
+2. Tidak boleh tambah dependency runtime ke core (`package.json#dependencies`). Benchmark hanya boleh pakai `devDependencies`.
+3. Output JSON harus deterministic — jika ada nilai yang berubah antar run (timestamp, host info), pisahkan ke field metadata terpisah.
+4. Setiap result file harus include schema version + timestamp + tooling version supaya hasil lama tetap interpretable.
+
+## Result Files Convention
+
+- Tracked di git (`benchmarks/results/*.json` whitelisted di `.gitignore`).
+- Naming: `{suite-name}-{YYYY-MM-DD}.json` atau `{suite-name}-{semver}.json`.
+- Tidak boleh berisi raw API response yang bisa expose secrets atau data user.
+- Latest baseline per suite is referenced from `docs/archive/phase-2-outcome.md` and the live decision authority in `docs/architecture/decisions-foundation.md`.
+
+## Why This Exists
+
+Klaim seperti "hemat 40% token" atau "rule adherence +14pt" tanpa data reproducible = marketing. Suite di folder ini = comparator wajib untuk setiap claim di README atau release notes.