@ryuenn3123/agentic-senior-core 4.2.0 → 4.2.2

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

@@ -27,8 +27,10 @@ For non-trivial coding, review, planning, or governance work, run `agentic-senio
 
 Keep it short. Do not load every rule just to fill it out.
 
-## Command Economy
-Avoid repeated command output. Do not rerun broad inspections unless edits changed the result. Prefer targeted reads, 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
+Before any non-trivial task, run `agentic-senior-core context` and emit the Bootstrap Receipt. Skip only for trivial tasks: version bumps, typo fixes, single-line commits.
+Always prefix noisy shell commands: `ascx git status`, `ascx git diff`, `ascx npm test`, `ascx rg` searches. Use raw commands only for pipes, redirects, or commands not supported by ascx.
+Always read and apply `.agent-context/prompts/compact-natural-mode.md` for every final user-facing reply. Never repeat full command output; reference tee file paths when truncated.
 
 ## Layer Index
 ### Layer 1: Rules (21 Files) [SCOPE-RESOLVED]
@@ -163,11 +165,11 @@ Never claim done without:
 2. PR and architecture checklists considered.
 3. Universal SOP gates satisfied: public and developer root `README.md`; `docs/architecture-decision-record.md`; plus `docs/DESIGN.md` and `docs/design-intent.json` for UI scope.
 4. If `.agent-context/state/active-memory.json` exists and material project progress happened, refresh it while preserving privacy rules and user-owned entries.
-5. MCP validation passed through `npm run validate`.
+5. Project validation passed through `npm run validate`.
 
 ## Knowledge Inventory Checklist
 
-Verify reachability when relevant: Layer 1 Rules, Layer 2 Runtime Decision Signals, Layer 3 Structural Planning Signals, Layer 4 Execution Contracts, Layer 5 Prompts, Layer 6 Governance Modes, Layer 7 State, Layer 8 Policies, Layer 9 Project Context.
+Verify reachability of relevant files in Layer 1 to Layer 9 before generating implementation code. If a required instruction file is missing or unreachable, halt and report the missing dependency.
 
 ## Operating Gates
 
@@ -175,4 +177,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

@@ -46,16 +46,14 @@ Preview changes with `--dry-run`, then apply with `--yes`. Upgrade prunes obsole
 | `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 |
+| `ascx <command>` | Run a command through the local evidence-preserving output wrapper (safely falls back to passthrough if unsupported) |
 | `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 |
 
-`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.
+`ascx` dynamically compresses supported commands with noisy output (e.g., builds, tests, searches, and git logs). Other commands, pipes, redirects, and unsupported shell shapes safely 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`.
 
@@ -68,7 +66,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.2",
   "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',
     ],
   },