@ryuenn3123/agentic-senior-core 4.2.0 → 4.2.1

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

@@ -25,10 +25,10 @@ For non-trivial coding, review, planning, or governance work, run `agentic-senio
 - `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, concise diffs, and `ascx git status` / `ascx git diff` / `ascx npm test` when available; use raw commands for pipes, redirects, or unsupported commands.
+## 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]
@@ -175,4 +175,4 @@ Verify reachability when relevant: Layer 1 Rules, Layer 2 Runtime Decision Signa
 - 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.
+- Before UI implementation: confirm valid style context, design contract, and required docs.

package/README.md

@@ -68,7 +68,7 @@ A coding agent that has read every framework tutorial still ships junior-grade w
 ### How It Works
 
 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.
+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.

package/benchmarks/README.md

@@ -1,40 +1,60 @@
 # Benchmarks
 
-Reproducible measurement suites untuk repo ini. Setiap release publish hasil benchmark di `benchmarks/results/{name}-{date}.json` supaya klaim bisa diverifikasi.
+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/
-├── token-usage/        Token measurement per provider untuk rules pack delivery
-├── results/            Output JSON yang dipublish per release (tracked di git)
-└── README.md
+|-- 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/` | Phase 0 (in progress) | `results/baseline-{YYYY-MM-DD}.json` |
+| --- | --- | --- | --- |
+| 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
 
-Setiap suite punya README sendiri di sub-folder. Lihat `token-usage/README.md` untuk instruksi spesifik.
+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. 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.
+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
 
-- 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`.
+- 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
 
-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.
+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.

package/benchmarks/runtime-token-saver/fixtures.mjs

@@ -349,14 +349,14 @@ export const ASCX_RUNTIME_TOKEN_SAVER_FIXTURES = [
       stderr: '',
     },
     expectCompressed: true,
-    expectTee: true,
+    expectTee: false,
     requiredSubstrings: [
       'npm test summary:',
       '# tests 1',
       '# pass 1',
       '# fail 0',
       'exit: 0',
-      'raw_output:',
+      'raw_output: none',
     ],
     forbiddenSubstrings: [
       'passing fixture 01',
@@ -364,18 +364,18 @@ export const ASCX_RUNTIME_TOKEN_SAVER_FIXTURES = [
     continuationChecks: [
       {
         id: 'passing-tests-avoid-failure-hunt',
-        action: 'Decide that no failing-test triage is needed while raw output remains available for audit.',
+        action: 'Decide that no failing-test triage is needed and no raw tee was written.',
         requiredSubstrings: [
           '# tests 1',
           '# pass 1',
           '# fail 0',
           'exit: 0',
-          'raw_output:',
+          'raw_output: none',
         ],
         forbiddenSubstrings: [
           'passing fixture 01',
         ],
-        expectTee: true,
+        expectTee: false,
       },
     ],
   },
@@ -399,14 +399,14 @@ export const ASCX_RUNTIME_TOKEN_SAVER_FIXTURES = [
       stderr: '',
     },
     expectCompressed: true,
-    expectTee: true,
+    expectTee: false,
     requiredSubstrings: [
       'npm test summary:',
       '# tests 2',
       '# pass 2',
       '# fail 0',
       'exit: 0',
-      'raw_output:',
+      'raw_output: none',
     ],
     forbiddenSubstrings: [
       'failures:',
@@ -421,13 +421,13 @@ export const ASCX_RUNTIME_TOKEN_SAVER_FIXTURES = [
           '# tests 2',
           '# pass 2',
           '# fail 0',
-          'raw_output:',
+          'raw_output: none',
         ],
         forbiddenSubstrings: [
           'failures:',
           '[FATAL]',
         ],
-        expectTee: true,
+        expectTee: false,
       },
     ],
   },
@@ -610,4 +610,105 @@ export const ASCX_RUNTIME_TOKEN_SAVER_FIXTURES = [
       },
     ],
   },
+  {
+    id: 'npm-run-build-success',
+    commandArguments: ['npm', 'run', 'build'],
+    capture: {
+      exitCode: 0,
+      stdout: [
+        '> npm run build',
+        '> vite build',
+        'vite v4.0.0 building for production...',
+        'transforming...',
+        '✓ 124 modules transformed.',
+        'dist/index.html 1.2kB',
+        'dist/assets/index.js 24kB',
+        'built in 1.2s',
+      ].join('\n'),
+      stderr: '',
+    },
+    expectCompressed: true,
+    expectTee: false,
+    requiredSubstrings: [
+      'npm run build summary:',
+      'result: passed',
+      'exit: 0',
+    ],
+    continuationChecks: [
+      {
+        id: 'npm-run-build-success-compacts-noise',
+        action: 'Recognize the build passed and avoid reading raw noise.',
+        requiredSubstrings: [
+          'result: passed',
+          'exit: 0',
+        ],
+        expectTee: false,
+      },
+    ],
+  },
+  {
+    id: 'npm-run-build-failure',
+    commandArguments: ['npm', 'run', 'build'],
+    capture: {
+      exitCode: 1,
+      stdout: [
+        '> npm run build',
+        '> tsc --noEmit',
+        'src/components/Header.tsx:15:10 - error TS2322: Type \'string\' is not assignable to type \'number\'.',
+        '15   const age: number = "25";',
+      ].join('\n'),
+      stderr: '',
+    },
+    expectCompressed: true,
+    expectTee: true,
+    requiredSubstrings: [
+      'npm run build summary:',
+      'failures:',
+      'error TS2322',
+      'Header.tsx:15:10',
+      'exit: 1',
+    ],
+    continuationChecks: [
+      {
+        id: 'npm-run-build-failure-preserves-error',
+        action: 'Identify the build error and file path.',
+        requiredSubstrings: [
+          'failures:',
+          'error TS2322',
+          'Header.tsx:15:10',
+        ],
+        expectTee: true,
+      },
+    ],
+  },
+  {
+    id: 'rg-large-output',
+    commandArguments: ['rg', 'function'],
+    capture: {
+      exitCode: 0,
+      stdout: Array.from({ length: 120 }, (_, i) => `src/file-${i}.ts:10:function doSomething() {}`).join('\n'),
+      stderr: '',
+    },
+    expectCompressed: true,
+    expectTee: true, // We should write tee because it's truncated? Let's check formatter logic
+    requiredSubstrings: [
+      'ripgrep results:',
+      'src/file-0.ts',
+      '... truncated 40 more lines of matches',
+      'truncation: full search results available in the raw tee output',
+      'exit: 0',
+    ],
+    continuationChecks: [
+      {
+        id: 'rg-truncates-massive-results',
+        action: 'Identify that ripgrep found many matches and read the truncated summary.',
+        requiredSubstrings: [
+          'ripgrep results:',
+          '... truncated 40 more lines of matches',
+          'truncation: full search results available in the raw tee output',
+        ],
+        expectTee: true, // Should tee if truncated
+      },
+    ],
+  },
 ];

package/lib/cli/ascx/adapters/npm-run-build.mjs

@@ -0,0 +1,99 @@
+const FAILURE_LINE_PATTERN = /(?:^Error:|^TypeError:|^SyntaxError|^ReferenceError|^TS\d+:\s|^Failed to compile|Module not found|ERR!|error\b|ERROR\b|×|✖|failure|FAIL\b)/iu;
+const FILE_LINE_PATTERN = /(?:[A-Za-z]:)?[^:\s]+?\.(?:cjs|mjs|js|jsx|ts|tsx|vue|svelte|css|scss|html|json):\d+(?::\d+)?/u;
+
+function pushUniqueLine(lines, nextLine) {
+  const normalizedLine = String(nextLine || '').trimEnd();
+  if (normalizedLine && !lines.includes(normalizedLine)) {
+    lines.push(normalizedLine);
+  }
+}
+
+function extractFailureLines(lines) {
+  const keptLines = [];
+  let contextBuffer = [];
+
+  for (const line of lines) {
+    const trimmedLine = line.trim();
+
+    // Preserve empty lines in context buffer to maintain readability if we decide to flush it
+    if (!trimmedLine) {
+      if (contextBuffer.length > 0) {
+        contextBuffer.push(line);
+      }
+      continue;
+    }
+
+    const isFailureLine = FAILURE_LINE_PATTERN.test(trimmedLine) || FILE_LINE_PATTERN.test(trimmedLine);
+    
+    if (isFailureLine) {
+      // If we found a failure, flush the preceding short context (e.g., file paths that didn't match the regex but preceded an error)
+      for (const ctxLine of contextBuffer) {
+        pushUniqueLine(keptLines, ctxLine);
+      }
+      contextBuffer = [];
+      pushUniqueLine(keptLines, line);
+    } else {
+      // Keep a small rolling buffer of context lines (max 2) before an error
+      contextBuffer.push(line);
+      if (contextBuffer.length > 2) {
+        contextBuffer.shift();
+      }
+    }
+  }
+
+  return keptLines;
+}
+
+export function compressNpmRunBuildOutput({ stdout, stderr, exitCode }) {
+  const rawOutput = [stdout, stderr].filter(Boolean).join('\n');
+  const lines = rawOutput.split(/\r?\n/u);
+  
+  // If exit code is 0, build probably succeeded, just return a short success message.
+  if (exitCode === 0) {
+    return {
+      filterName: 'npm-run-build-summary',
+      confident: true,
+      truncated: false,
+      output: 'npm run build summary:\nresult: passed',
+      preservedFields: {
+        exitCode: true,
+      },
+    };
+  }
+
+  const failureLines = extractFailureLines(lines);
+  const outputLines = ['npm run build summary:'];
+
+  if (failureLines.length > 0) {
+    outputLines.push('failures:');
+    outputLines.push(...failureLines.slice(0, 100));
+  }
+
+  const truncated = failureLines.length > 100;
+  if (truncated) {
+    outputLines.push(`... truncated ${failureLines.length - 100} more failure evidence lines`);
+  }
+
+  if (failureLines.length === 0) {
+    // We couldn't parse the errors clearly, fallback to raw
+    return {
+      filterName: 'npm-run-build-raw-parse-uncertain',
+      confident: false,
+      truncated: false,
+      output: rawOutput,
+      preservedFields: {},
+    };
+  }
+
+  return {
+    filterName: 'npm-run-build-summary',
+    confident: true,
+    truncated,
+    output: outputLines.join('\n'),
+    preservedFields: {
+      rootError: failureLines.length > 0,
+      filePath: failureLines.some((line) => FILE_LINE_PATTERN.test(line)),
+      exitCode: true,
+    },
+  };
+}

package/lib/cli/ascx/adapters/rg.mjs

@@ -0,0 +1,39 @@
+export function compressRgOutput({ stdout, stderr, exitCode }) {
+  const rawOutput = [stdout, stderr].filter(Boolean).join('\n');
+  const lines = rawOutput.split(/\r?\n/u);
+  
+  // If exit code is non-zero and no output, rg found nothing or errored
+  if (lines.length === 0 || (lines.length === 1 && lines[0] === '')) {
+    return {
+      filterName: 'rg-summary',
+      confident: true,
+      truncated: false,
+      output: exitCode === 0 ? 'No matches found.' : `ripgrep exited with code ${exitCode}`,
+      preservedFields: {
+        exitCode: true,
+      },
+    };
+  }
+
+  const outputLines = ['ripgrep results:'];
+  const maxLines = 80;
+
+  if (lines.length > maxLines) {
+    outputLines.push(...lines.slice(0, maxLines));
+    outputLines.push(`... truncated ${lines.length - maxLines} more lines of matches`);
+    outputLines.push(`truncation: full search results available in the raw tee output`);
+  } else {
+    outputLines.push(...lines);
+  }
+
+  return {
+    filterName: 'rg-summary',
+    confident: true,
+    truncated: lines.length > maxLines,
+    output: outputLines.join('\n'),
+    preservedFields: {
+      exitCode: true,
+      filePath: true, // We assume rg output contains file paths
+    },
+  };
+}

package/lib/cli/ascx/formatter.mjs

@@ -39,8 +39,9 @@ export function buildAscxFooter({
 }
 
 export function shouldWriteSafetyTee({ adapterResult, exitCode, reductionPercent }) {
-  return exitCode !== 0
-    || adapterResult.truncated === true
-    || adapterResult.confident === false
-    || reductionPercent >= HIGH_RISK_REDUCTION_PERCENT;
+  if (exitCode !== 0) return true;
+  if (adapterResult.truncated === true) return true;
+  if (adapterResult.confident === false) return true;
+  if (adapterResult.confident !== true && reductionPercent >= HIGH_RISK_REDUCTION_PERCENT) return true;
+  return false;
 }

package/lib/cli/ascx/lexer.mjs

@@ -105,6 +105,22 @@ export function classifyAscxInvocation(parsedCommand) {
     };
   }
 
+  if (parsedCommand.executable === 'npm' && parsedCommand.args[0] === 'run' && parsedCommand.args[1] === 'build') {
+    return {
+      kind: 'compressible',
+      adapterName: 'npm-run-build',
+      reason: 'supported npm run build adapter',
+    };
+  }
+
+  if (parsedCommand.executable === 'rg') {
+    return {
+      kind: 'compressible',
+      adapterName: 'rg',
+      reason: 'supported rg (ripgrep) adapter',
+    };
+  }
+
   return {
     kind: 'passthrough',
     adapterName: null,

package/lib/cli/ascx/runtime.mjs

@@ -3,6 +3,8 @@ import { spawn } from 'node:child_process';
 import { compressGitDiffOutput } from './adapters/git-diff.mjs';
 import { compressGitStatusOutput } from './adapters/git-status.mjs';
 import { compressNpmTestOutput } from './adapters/npm-test.mjs';
+import { compressNpmRunBuildOutput } from './adapters/npm-run-build.mjs';
+import { compressRgOutput } from './adapters/rg.mjs';
 import { buildAscxFooter, shouldWriteSafetyTee } from './formatter.mjs';
 import { classifyAscxInvocation, parseAscxCommand } from './lexer.mjs';
 import { writeRawTeeFile } from './tee-writer.mjs';
@@ -11,6 +13,8 @@ const ADAPTERS = {
   'git-diff': compressGitDiffOutput,
   'git-status': compressGitStatusOutput,
   'npm-test': compressNpmTestOutput,
+  'npm-run-build': compressNpmRunBuildOutput,
+  'rg': compressRgOutput,
 };
 
 function buildCommandEnvironment(baseEnvironment, parsedCommand) {

package/lib/cli/ascx/tee-writer.mjs

@@ -1,6 +1,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+export const MAX_TEE_FILES = 20;
+
 function sanitizeFileNamePart(rawValue) {
   return String(rawValue || 'command')
     .toLowerCase()
@@ -13,6 +15,27 @@ export function getDefaultTeeDirectory(cwd = process.cwd()) {
   return path.resolve(cwd, '.agent-context', 'state', 'token-saver', 'tee');
 }
 
+async function sweepOldTeeFiles(directoryPath, maxFiles = MAX_TEE_FILES) {
+  let entries;
+
+  try {
+    entries = await fs.readdir(directoryPath);
+  } catch {
+    return;
+  }
+
+  const logFiles = entries.filter((name) => name.endsWith('.log')).sort();
+  const excess = logFiles.length - maxFiles;
+
+  for (let i = 0; i < excess; i++) {
+    try {
+      await fs.unlink(path.join(directoryPath, logFiles[i]));
+    } catch {
+      // Best-effort cleanup; do not fail the write path.
+    }
+  }
+}
+
 export async function writeRawTeeFile({
   commandText,
   cwd = process.cwd(),
@@ -33,6 +56,8 @@ export async function writeRawTeeFile({
 
   await fs.mkdir(path.dirname(teeFilePath), { recursive: true });
   await fs.writeFile(teeFilePath, fileContent, 'utf8');
+  await sweepOldTeeFiles(teeDirectoryPath);
 
   return teeFilePath;
 }
+

package/lib/cli/backup.mjs

@@ -6,6 +6,11 @@ import { entryPointFiles, BACKUP_DIR_NAME } from './constants.mjs';
 
 const BACKUP_GITIGNORE_ENTRY = `${BACKUP_DIR_NAME}/`;
 const BACKUP_GITIGNORE_COMMENT = '# agentic-senior-core: local backup artifacts';
+const RUNTIME_ARTIFACT_GITIGNORE_ENTRIES = [
+  '.agent-context/state/token-saver/',
+  '.agent-context/state/token-optimization-report.json',
+];
+const RUNTIME_ARTIFACT_GITIGNORE_COMMENT = '# agentic-senior-core: local runtime artifacts';
 
 /**
  * Calculates a SHA-256 hash of a file's contents.
@@ -127,18 +132,23 @@ export async function createBackup(targetDirectoryPath) {
   };
 }
 
-export async function ensureBackupGitignoreEntry(targetDirectoryPath) {
+async function ensureGitignoreEntries(targetDirectoryPath, { comment, entries, aliasesByEntry = {} }) {
   const gitignorePath = path.join(targetDirectoryPath, '.gitignore');
   const existingContent = await pathExists(gitignorePath)
     ? await fs.readFile(gitignorePath, 'utf8')
     : '';
   const existingLines = existingContent.split(/\r?\n/).map((line) => line.trim());
+  const missingEntries = entries.filter((entry) => {
+    const equivalentEntries = [entry, ...(aliasesByEntry[entry] || [])];
+    return !equivalentEntries.some((equivalentEntry) => existingLines.includes(equivalentEntry));
+  });
 
-  if (existingLines.includes(BACKUP_GITIGNORE_ENTRY) || existingLines.includes(BACKUP_DIR_NAME)) {
+  if (missingEntries.length === 0) {
     return {
       status: 'unchanged',
       gitignorePath,
-      entry: BACKUP_GITIGNORE_ENTRY,
+      entries,
+      addedEntries: [],
     };
   }
 
@@ -149,13 +159,36 @@ export async function ensureBackupGitignoreEntry(targetDirectoryPath) {
   if (nextContent.length > 0 && !nextContent.endsWith('\n\n')) {
     nextContent += '\n';
   }
-  nextContent += `${BACKUP_GITIGNORE_COMMENT}\n${BACKUP_GITIGNORE_ENTRY}\n`;
+  nextContent += `${comment}\n${missingEntries.join('\n')}\n`;
 
   await fs.writeFile(gitignorePath, nextContent, 'utf8');
 
   return {
     status: existingContent ? 'updated' : 'created',
     gitignorePath,
+    entries,
+    addedEntries: missingEntries,
+  };
+}
+
+export async function ensureBackupGitignoreEntry(targetDirectoryPath) {
+  const result = await ensureGitignoreEntries(targetDirectoryPath, {
+    comment: BACKUP_GITIGNORE_COMMENT,
+    entries: [BACKUP_GITIGNORE_ENTRY],
+    aliasesByEntry: {
+      [BACKUP_GITIGNORE_ENTRY]: [BACKUP_DIR_NAME],
+    },
+  });
+
+  return {
+    ...result,
     entry: BACKUP_GITIGNORE_ENTRY,
   };
 }
+
+export async function ensureRuntimeArtifactGitignoreEntries(targetDirectoryPath) {
+  return ensureGitignoreEntries(targetDirectoryPath, {
+    comment: RUNTIME_ARTIFACT_GITIGNORE_COMMENT,
+    entries: RUNTIME_ARTIFACT_GITIGNORE_ENTRIES,
+  });
+}

package/lib/cli/commands/init.mjs

@@ -45,7 +45,11 @@ import {
   resolveDetectedSetupDecision,
 } from '../init-detection-flow.mjs';
 import { runPreflightChecks } from '../preflight.mjs';
-import { createBackup, ensureBackupGitignoreEntry } from '../backup.mjs';
+import {
+  createBackup,
+  ensureBackupGitignoreEntry,
+  ensureRuntimeArtifactGitignoreEntries,
+} from '../backup.mjs';
 import {
   runProjectDiscovery,
   generateProjectDocumentation,
@@ -373,6 +377,12 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     if (backupGitignoreResult.status !== 'unchanged') {
       console.log(`Local backup artifacts ignored in .gitignore (${backupGitignoreResult.entry}).`);
     }
+    const runtimeArtifactGitignoreResult = await ensureRuntimeArtifactGitignoreEntries(resolvedTargetDirectoryPath);
+    if (runtimeArtifactGitignoreResult.status !== 'unchanged') {
+      console.log(
+        `Local runtime artifacts ignored in .gitignore (${runtimeArtifactGitignoreResult.addedEntries.join(', ')}).`
+      );
+    }
 
     await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {
       includeMcpTemplate: shouldIncludeMcpTemplate,
@@ -565,6 +575,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     console.log(`- Review thresholds: ${formatBlockingSeverities(selectedPolicyProfile.blockingSeverities)}`);
     console.log(`- Setup time: ${formatDuration(setupDurationMs)}`);
     console.log('- Generated files: AGENTS.md, CLAUDE.md, GEMINI.md, .agent-context/, and .agent-context/state/onboarding-report.json');
+    console.log('- Default activation cues: Adaptive Context bootstrap, ASCX command wrappers, Compact Natural final replies');
     console.log('- Default response mode: Compact Natural Mode enabled (.agent-context/prompts/compact-natural-mode.md)');
     if (scaffoldingResult?.bootstrapMode === 'ai-synthesis') {
       console.log(`- Bootstrap prompts: ${(scaffoldingResult.generatedPromptFileNames || []).length} files generated in .agent-context/prompts/`);

package/lib/cli/commands/upgrade/design-intent-seed.mjs

@@ -0,0 +1,46 @@
+import path from 'node:path';
+
+import { buildDesignIntentSeedFromSignals } from '../../project-scaffolder.mjs';
+
+export function buildUpgradeDesignIntentSeed({
+  targetDirectoryPath,
+  packageManifest,
+  selectedStackFileName,
+  selectedBlueprintFileName,
+  uiScopeSignals,
+}) {
+  const projectName = String(packageManifest?.name || path.basename(targetDirectoryPath)).trim()
+    || 'existing-ui-project';
+  const isMobileUiProject = String(selectedStackFileName || '').toLowerCase().includes('react-native')
+    || String(selectedStackFileName || '').toLowerCase().includes('flutter')
+    || uiScopeSignals.signalReasons.some((signalReason) => {
+      return signalReason.includes('android') || signalReason.includes('ios');
+    });
+  const resolvedDomain = isMobileUiProject ? 'Mobile app' : 'Web application';
+  const projectDescription = String(packageManifest?.description || '').trim()
+    || `Existing ${resolvedDomain.toLowerCase()} detected during upgrade. Create a project-specific dynamic design contract before shipping new UI work.`;
+
+  return buildDesignIntentSeedFromSignals({
+    projectName,
+    projectDescription,
+    primaryDomain: resolvedDomain,
+    features: [],
+    initContext: {
+      stackFileName: selectedStackFileName,
+      blueprintFileName: selectedBlueprintFileName,
+    },
+    status: 'seed-generated-during-upgrade',
+    supplementalFields: {
+      upgradeSignals: {
+        detectedFrom: uiScopeSignals.signalReasons,
+        generatedBy: 'upgrade-seed',
+      },
+      repoEvidence: {
+        uiSignalReasons: uiScopeSignals.signalReasons,
+        frontendMetrics: uiScopeSignals.frontendEvidenceMetrics || null,
+        designEvidenceSummary: uiScopeSignals.designEvidenceSummary || null,
+        workspaceUiEntries: uiScopeSignals.workspaceUiEntries || [],
+      },
+    },
+  });
+}

package/lib/cli/commands/upgrade/token-optimization-state.mjs

@@ -0,0 +1,51 @@
+import {
+  createTokenOptimizationState,
+  detectRtkBinary,
+  normalizeAgentName,
+  readTokenOptimizationState,
+  writeTokenOptimizationState,
+} from '../../token-optimization.mjs';
+
+export async function resolveUpgradeTokenOptimizationPlan(targetDirectoryPath, existingOnboardingReport) {
+  const existingState = await readTokenOptimizationState(targetDirectoryPath);
+  const optedOut = existingOnboardingReport?.tokenOptimization?.enabled === false;
+  const selectedAgentName = normalizeAgentName(
+    existingOnboardingReport?.tokenOptimization?.selectedAgent || 'copilot'
+  );
+
+  return {
+    existingState,
+    optedOut,
+    selectedAgentName,
+    shouldSeed: !existingState && !optedOut,
+    previewLabel: optedOut
+      ? 'disabled (preserved opt-out)'
+      : existingState
+        ? 'enabled'
+        : 'enabled (will seed missing ASCX state)',
+    reportState: existingState
+      || (optedOut ? existingOnboardingReport?.tokenOptimization || { enabled: false } : null),
+  };
+}
+
+export async function applyUpgradeTokenOptimizationPlan(targetDirectoryPath, plan) {
+  if (!plan.shouldSeed) {
+    return {
+      createdFileName: null,
+      reportState: plan.reportState,
+    };
+  }
+
+  const tokenOptimizationState = createTokenOptimizationState({
+    isEnabled: true,
+    selectedAgentName: plan.selectedAgentName,
+    rtkDetection: detectRtkBinary(),
+  });
+
+  await writeTokenOptimizationState(targetDirectoryPath, tokenOptimizationState);
+
+  return {
+    createdFileName: '.agent-context/state/token-optimization.json',
+    reportState: tokenOptimizationState,
+  };
+}

package/lib/cli/commands/upgrade.mjs

@@ -39,15 +39,21 @@ import {
 } from '../compiler.mjs';
 
 import { runPreflightChecks } from '../preflight.mjs';
-import { createBackup, ensureBackupGitignoreEntry } from '../backup.mjs';
-import { performRollback } from '../rollback.mjs';
 import {
-  detectProjectDocTemplateStaleness,
-  buildDesignIntentSeedFromSignals,
-} from '../project-scaffolder.mjs';
+  createBackup,
+  ensureBackupGitignoreEntry,
+  ensureRuntimeArtifactGitignoreEntries,
+} from '../backup.mjs';
+import { performRollback } from '../rollback.mjs';
+import { detectProjectDocTemplateStaleness } from '../project-scaffolder.mjs';
 import { migrateExistingDesignIntentToResearchDossierSchema } from '../project-scaffolder/design-contract/research-dossier-migration.mjs';
 import { ensureActiveMemorySnapshot } from '../memory-continuity.mjs';
 import { buildExistingProjectMajorConstraints } from '../init-detection-flow.mjs';
+import { buildUpgradeDesignIntentSeed } from './upgrade/design-intent-seed.mjs';
+import {
+  applyUpgradeTokenOptimizationPlan,
+  resolveUpgradeTokenOptimizationPlan,
+} from './upgrade/token-optimization-state.mjs';
 
 export function parseUpgradeArguments(commandArguments) {
   const parsedUpgradeOptions = {
@@ -102,46 +108,6 @@ export function parseUpgradeArguments(commandArguments) {
   return parsedUpgradeOptions;
 }
 
-function buildUpgradeDesignIntentSeed({
-  targetDirectoryPath,
-  packageManifest,
-  selectedStackFileName,
-  selectedBlueprintFileName,
-  uiScopeSignals,
-}) {
-  const projectName = String(packageManifest?.name || path.basename(targetDirectoryPath)).trim() || 'existing-ui-project';
-  const isMobileUiProject = String(selectedStackFileName || '').toLowerCase().includes('react-native')
-    || String(selectedStackFileName || '').toLowerCase().includes('flutter')
-    || uiScopeSignals.signalReasons.some((signalReason) => signalReason.includes('android') || signalReason.includes('ios'));
-  const resolvedDomain = isMobileUiProject ? 'Mobile app' : 'Web application';
-  const projectDescription = String(packageManifest?.description || '').trim()
-    || `Existing ${resolvedDomain.toLowerCase()} detected during upgrade. Create a project-specific dynamic design contract before shipping new UI work.`;
-
-  return buildDesignIntentSeedFromSignals({
-    projectName,
-    projectDescription,
-    primaryDomain: resolvedDomain,
-    features: [],
-    initContext: {
-      stackFileName: selectedStackFileName,
-      blueprintFileName: selectedBlueprintFileName,
-    },
-    status: 'seed-generated-during-upgrade',
-    supplementalFields: {
-      upgradeSignals: {
-        detectedFrom: uiScopeSignals.signalReasons,
-        generatedBy: 'upgrade-seed',
-      },
-      repoEvidence: {
-        uiSignalReasons: uiScopeSignals.signalReasons,
-        frontendMetrics: uiScopeSignals.frontendEvidenceMetrics || null,
-        designEvidenceSummary: uiScopeSignals.designEvidenceSummary || null,
-        workspaceUiEntries: uiScopeSignals.workspaceUiEntries || [],
-      },
-    },
-  });
-}
-
 export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions = {}) {
   const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
 
@@ -175,6 +141,10 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     const stackFileNames = await collectFileNames(path.join(AGENT_CONTEXT_DIR, 'stacks'));
     const blueprintFileNames = await collectFileNames(path.join(AGENT_CONTEXT_DIR, 'blueprints'));
     const existingOnboardingReport = await loadOnboardingReportIfExists(resolvedTargetDirectoryPath);
+    const tokenOptimizationPlan = await resolveUpgradeTokenOptimizationPlan(
+      resolvedTargetDirectoryPath,
+      existingOnboardingReport
+    );
     const projectDetection = await detectProjectContext(resolvedTargetDirectoryPath);
     const selectedProfileName = PROFILE_PRESETS[existingOnboardingReport?.selectedProfile]
       ? existingOnboardingReport.selectedProfile
@@ -302,6 +272,8 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     }
     console.log(`- CI/CD quality checks (guardrails): ${includeCiGuardrails ? 'enabled' : 'disabled'}`);
     console.log('- Instruction surface: AGENTS.md canonical with CLAUDE.md and GEMINI.md import bridges');
+    console.log('- Default activation cues: Adaptive Context bootstrap, ASCX wrappers, Compact Natural replies');
+    console.log(`- Token optimization policy: ${tokenOptimizationPlan.previewLabel}`);
     console.log('- Default response mode: Compact Natural Mode enabled');
     console.log(`- Managed surface stale files: ${managedSurfacePlan.staleFiles.length}`);
     console.log(`- Managed surface stale directories: ${managedSurfacePlan.staleDirectories.length}`);
@@ -374,6 +346,12 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     if (backupGitignoreResult.status !== 'unchanged') {
       console.log(`Local backup artifacts ignored in .gitignore (${backupGitignoreResult.entry}).`);
     }
+    const runtimeArtifactGitignoreResult = await ensureRuntimeArtifactGitignoreEntries(resolvedTargetDirectoryPath);
+    if (runtimeArtifactGitignoreResult.status !== 'unchanged') {
+      console.log(
+        `Local runtime artifacts ignored in .gitignore (${runtimeArtifactGitignoreResult.addedEntries.join(', ')}).`
+      );
+    }
 
     try {
       const governanceSyncResult = await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {
@@ -383,6 +361,13 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
       });
       const supplementalCreatedFileNames = [];
       const shouldEnsureActiveMemorySnapshot = existingOnboardingReport?.memoryContinuity?.enabled !== false;
+      const tokenOptimizationApplyResult = await applyUpgradeTokenOptimizationPlan(
+        resolvedTargetDirectoryPath,
+        tokenOptimizationPlan
+      );
+      if (tokenOptimizationApplyResult.createdFileName) {
+        supplementalCreatedFileNames.push(tokenOptimizationApplyResult.createdFileName);
+      }
 
       if (shouldSeedDesignIntentOnApply && designIntentSeedContent) {
         const docsDirectoryPath = path.join(resolvedTargetDirectoryPath, 'docs');
@@ -428,6 +413,7 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         projectDetection,
         runtimeEnvironment: existingOnboardingReport?.runtimeEnvironment || null,
         operationMode: 'upgrade',
+        tokenOptimization: tokenOptimizationApplyResult.reportState,
         detectionTransparency,
         uiScopeSignals,
       });
@@ -465,6 +451,7 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
       }
 
       console.log('\nRefreshed files: AGENTS.md, CLAUDE.md, GEMINI.md, .agent-context/, and .agent-context/state/onboarding-report.json');
+      console.log('Default activation cues remain Adaptive Context bootstrap, ASCX command wrappers, and Compact Natural final replies.');
       console.log('Default response mode remains Compact Natural Mode through .agent-context/prompts/compact-natural-mode.md.');
       console.log('\nNext-step suggestion (UI scope): run `npx @ryuenn3123/agentic-senior-core audit:design-anti-repeat` to scan CSS, SCSS, SASS, LESS, Tailwind config, and design-token files in this project for typography or palette values that match the anti-repeat ledger in docs/design-intent.json. Add it to your CI alongside `npm test` once the design dossier is populated.');
     } catch (error) {

package/lib/cli/project-scaffolder/prompt-builders.mjs

@@ -31,6 +31,7 @@ function buildDockerStrategyExecutionBlock(dockerStrategy) {
     '- Required asset floor: ' + requiredAssetFloor + '.',
     '- Keep development and production lanes separate when both are selected.',
     '- If the user asks to create files without commands, write the files and documented commands, but do not execute Docker build, Compose, or registry commands.',
+    '- If Docker is enabled for development, local development setup and first-build instructions in the README must use Docker (e.g., `docker compose up`) rather than fallback local commands like `npm run dev`.',
   ];
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "4.2.0",
+  "version": "4.2.1",
   "type": "module",
   "description": "Change your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {

package/scripts/build-release-benchmark-bundle.mjs

@@ -148,9 +148,7 @@ export function buildReleaseBenchmarkBundle(options = {}) {
       research_foundation: 'docs/architecture/decisions-foundation.md',
       d4_caching_scope_matrix: 'docs/architecture/decisions-foundation.md#d4',
       caching_reporting_format: 'docs/benchmark-reference.md',
-      phase_2_outcome: 'docs/archive/phase-2-outcome.md',
-      phase_3_outcome: 'docs/archive/phase-3-outcome.md',
-      phase_5_plan: 'docs/archive/phase-5-hardening.md',
+      historical_record: 'docs/archive/HISTORY.md',
     },
     integrity: {
       hash_algorithm: 'SHA-256',

package/scripts/clean-local-artifacts.mjs

@@ -25,6 +25,8 @@ const LOCAL_ARTIFACT_PATHS = [
   '.agent-context/state/docs-quality-drift-report.json',
   '.agent-context/state/memory-continuity-benchmark.json',
   '.agent-context/state/quality-trend-report.json',
+  '.agent-context/state/token-saver',
+  '.agent-context/state/token-optimization-report.json',
   '.agent-context/state/token-optimization-benchmark.json',
   '.agent-context/state/weekly-governance-report.json',
 ];

package/scripts/validate/config.mjs

@@ -281,6 +281,11 @@ export const REQUIRED_UPGRADE_UI_CONTRACT_WARNING_SNIPPETS = [
       'Planned seed on apply: docs/design-intent.json',
       'Upgrade synchronizes governance assets and can seed docs/design-intent.json, but it does not author project-specific docs/DESIGN.md automatically.',
       'detectUiScopeSignals',
+    ],
+  },
+  {
+    path: 'lib/cli/commands/upgrade/design-intent-seed.mjs',
+    snippets: [
       'seed-generated-during-upgrade',
     ],
   },