@ryuenn3123/agentic-senior-core 3.0.46 → 3.0.48

package/README.md

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

package/lib/cli/backup.mjs

@@ -4,6 +4,9 @@ import crypto from 'node:crypto';
 import { pathExists, ensureDirectory } from './utils.mjs';
 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';
+
 /**
  * Calculates a SHA-256 hash of a file's contents.
  */
@@ -54,6 +57,7 @@ export async function createBackup(targetDirectoryPath) {
   await ensureDirectory(objectsDir);
 
   const pathsToTrack = [
+    path.join(targetDirectoryPath, '.gitignore'),
     ...entryPointFiles.map((entryPointFileName) => path.join(targetDirectoryPath, entryPointFileName)),
     path.join(targetDirectoryPath, '.agent-context'),
   ];
@@ -122,3 +126,36 @@ export async function createBackup(targetDirectoryPath) {
     durationMs: Date.now() - startTime
   };
 }
+
+export async function ensureBackupGitignoreEntry(targetDirectoryPath) {
+  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());
+
+  if (existingLines.includes(BACKUP_GITIGNORE_ENTRY) || existingLines.includes(BACKUP_DIR_NAME)) {
+    return {
+      status: 'unchanged',
+      gitignorePath,
+      entry: BACKUP_GITIGNORE_ENTRY,
+    };
+  }
+
+  let nextContent = existingContent;
+  if (nextContent.length > 0 && !nextContent.endsWith('\n')) {
+    nextContent += '\n';
+  }
+  if (nextContent.length > 0 && !nextContent.endsWith('\n\n')) {
+    nextContent += '\n';
+  }
+  nextContent += `${BACKUP_GITIGNORE_COMMENT}\n${BACKUP_GITIGNORE_ENTRY}\n`;
+
+  await fs.writeFile(gitignorePath, nextContent, 'utf8');
+
+  return {
+    status: existingContent ? 'updated' : 'created',
+    gitignorePath,
+    entry: BACKUP_GITIGNORE_ENTRY,
+  };
+}

package/lib/cli/commands/init.mjs

@@ -34,7 +34,7 @@ import {
   formatDetectionCandidates,
   detectUiScopeSignals,
 } from '../detector.mjs';
-import { compileDynamicContext, writeSelectedPolicy, writeOnboardingReport } from '../compiler.mjs';
+import { writeSelectedPolicy, writeOnboardingReport } from '../compiler.mjs';
 import {
   normalizeAdditionalStackSelection,
   normalizeAdditionalBlueprintSelection,
@@ -44,7 +44,7 @@ import {
   resolveDetectedSetupDecision,
 } from '../init-detection-flow.mjs';
 import { runPreflightChecks } from '../preflight.mjs';
-import { createBackup } from '../backup.mjs';
+import { createBackup, ensureBackupGitignoreEntry } from '../backup.mjs';
 import {
   runProjectDiscovery,
   generateProjectDocumentation,
@@ -153,7 +153,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     }
 
     console.log(`\nAgentic-Senior-Core CLI v${CLI_VERSION}`);
-    console.log('I will copy the project guidance pack into your target folder and compile a single rulebook for your AI tools.');
+    console.log('I will copy the project guidance pack into your target folder with AGENTS.md and native import bridges for your AI tools.');
 
     if (selectedPreset) {
       console.log(`Using preset: ${initOptions.preset} (${selectedPreset.description}).`);
@@ -198,19 +198,10 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         ? buildDetectionSummary(projectDetection)
         : 'No existing project markers were detected.',
       activeRulesSummary: {
-        canonicalSource: '.instructions.md',
-        compiledRulebook: '.agent-instructions.md',
-        legacyThinAdapters: ['.cursorrules', '.windsurfrules', '.clauderc'],
-        generatedBridgeAdapters: [
-          'AGENTS.md',
-          'CLAUDE.md',
-          'GEMINI.md',
-          '.cursor/rules/agentic-senior-core.mdc',
-          '.windsurf/rules/agentic-senior-core.md',
-          '.github/copilot-instructions.md',
-          '.github/instructions/agentic-senior-core.instructions.md',
-          '.gemini/instructions.md',
-        ],
+        canonicalSource: 'AGENTS.md',
+        compiledRulebook: null,
+        legacyThinAdapters: [],
+        generatedBridgeAdapters: ['CLAUDE.md', 'GEMINI.md'],
         stackLoadingMode: 'lazy',
         domainRuleLoadingMode: 'lazy',
         selectedProfile: selectedPolicyProfileName,
@@ -249,7 +240,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         console.log('- Detected stack: unresolved (insufficient markers).');
       }
 
-      console.log('- Active rules baseline: canonical .instructions.md -> compiled .agent-instructions.md + legacy thin root adapters');
+      console.log('- Active rules baseline: canonical AGENTS.md + .agent-context/ lazy rule library');
       console.log(
         `- Active review thresholds: ${formatBlockingSeverities(selectedPolicyProfile.blockingSeverities)}`
       );
@@ -376,6 +367,10 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     detectionTransparency.decision.selectedProjectScopeLabel = selectedProjectScopeLabel;
 
     await createBackup(resolvedTargetDirectoryPath);
+    const backupGitignoreResult = await ensureBackupGitignoreEntry(resolvedTargetDirectoryPath);
+    if (backupGitignoreResult.status !== 'unchanged') {
+      console.log(`Local backup artifacts ignored in .gitignore (${backupGitignoreResult.entry}).`);
+    }
 
     await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {
       includeMcpTemplate: shouldIncludeMcpTemplate,
@@ -489,15 +484,6 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       console.log('\nExisting UI/frontend scope detected. Seeded docs/design-intent.json so the machine-readable design contract exists before UI implementation work continues.');
     }
 
-    await compileDynamicContext({
-      targetDirectoryPath: resolvedTargetDirectoryPath,
-      selectedStackFileName: selectedResolvedStackFileName,
-      selectedAdditionalStackFileNames,
-      selectedBlueprintFileName: selectedResolvedBlueprintFileName,
-      selectedAdditionalBlueprintFileNames,
-      includeCiGuardrails,
-    });
-
     await writeSelectedPolicy(resolvedTargetDirectoryPath, selectedPolicyProfileName);
 
     const setupDurationMs = Date.now() - setupStartedAt;
@@ -566,7 +552,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     console.log(`- CI/CD quality checks (guardrails): ${includeCiGuardrails ? 'enabled' : 'disabled'}`);
     console.log(`- Review thresholds: ${formatBlockingSeverities(selectedPolicyProfile.blockingSeverities)}`);
     console.log(`- Setup time: ${formatDuration(setupDurationMs)}`);
-    console.log('- Generated files: .instructions.md, .agent-instructions.md, legacy thin adapters, generated bridge adapters, and .agent-context/state/onboarding-report.json');
+    console.log('- Generated files: AGENTS.md, CLAUDE.md, GEMINI.md, .agent-context/, and .agent-context/state/onboarding-report.json');
     if (scaffoldingResult?.bootstrapMode === 'ai-synthesis') {
       console.log(`- Bootstrap prompts: ${(scaffoldingResult.generatedPromptFileNames || []).length} files generated in .agent-context/prompts/`);
       if ((scaffoldingResult.materializedFileNames || []).length > 0) {
@@ -582,7 +568,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       console.log(`- Design seed docs: ${supplementalMaterializedDocFileNames.length} files generated in docs/`);
     }
     console.log(`- Repository workflows copied: no (workflows remain source-repo assets)`);
-    console.log(`- MCP configuration: ${shouldIncludeMcpTemplate ? 'auto-configured for your IDEs (VS Code, Cursor, Zed, Gemini)' : 'disabled (--no-mcp-template)'}`);
+    console.log(`- MCP configuration: ${shouldIncludeMcpTemplate ? 'auto-configured for your IDEs (VS Code, Cursor, Zed, Gemini)' : 'disabled (use --mcp-template to enable)'}`);
     if (isMemoryContinuityEnabled) {
       console.log('- Memory continuity policy: enabled (index + selective hydration; host support required)');
     } else {
@@ -630,7 +616,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       console.log('- If docs/DESIGN.md is missing, execute .agent-context/prompts/bootstrap-design.md now and refine docs/design-intent.json into a complete design contract before building UI components.');
       console.log('- Keep docs/design-intent.json and docs/DESIGN.md synchronized whenever the UI direction changes.');
     }
-    console.log('Your AI tools will now receive one compiled rulebook, thin discovery adapters, and the original source rules. Your review threshold is stored in .agent-context/policies/llm-judge-threshold.json.');
+    console.log('Your AI tools will now receive AGENTS.md, native import bridges, and the lazy-loaded .agent-context rule library. Your review threshold is stored in .agent-context/policies/llm-judge-threshold.json.');
     console.log('MCP server registration is manual inside your IDE settings, even when mcp.json exists.');
   } catch (error) {
     console.error('\n[FATAL] An error occurred during initialization. Attempting automatic rollback...');

package/lib/cli/commands/optimize.mjs

@@ -2,11 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 
 import { ensureDirectory, formatDuration } from '../utils.mjs';
-import { compileDynamicContext, loadOnboardingReportIfExists } from '../compiler.mjs';
-import {
-  AGENT_DECISION_STACK_FILE_NAME,
-  AGENT_DECISION_BLUEPRINT_FILE_NAME,
-} from '../constants.mjs';
+import { loadOnboardingReportIfExists } from '../compiler.mjs';
 import {
   TOKEN_OPTIMIZATION_REPORT_FILE_NAME,
   normalizeAgentName,
@@ -18,17 +14,6 @@ import {
   writeTokenOptimizationState,
 } from '../token-optimization.mjs';
 
-function normalizeMarkdownFileName(rawFileName, fallbackFileName) {
-  if (typeof rawFileName !== 'string' || rawFileName.trim().length === 0) {
-    return fallbackFileName;
-  }
-
-  const normalizedFileName = rawFileName.trim();
-  return normalizedFileName.endsWith('.md')
-    ? normalizedFileName
-    : `${normalizedFileName}.md`;
-}
-
 export function parseOptimizeArguments(commandArguments) {
   const parsedOptimizeOptions = {
     targetDirectory: '.',
@@ -119,37 +104,6 @@ export async function runOptimizeCommand(targetDirectoryArgument, optimizeOption
 
   await writeTokenOptimizationState(resolvedTargetDirectoryPath, tokenOptimizationState);
 
-  const hasExplicitRuntimeConstraint = onboardingReport?.runtimeDecision?.mode === 'explicit-constraint';
-  const hasExplicitArchitectureConstraint = onboardingReport?.architectureDecision?.mode === 'explicit-constraint';
-  const selectedStackFileName = hasExplicitRuntimeConstraint
-    ? normalizeMarkdownFileName(onboardingReport.selectedStack, AGENT_DECISION_STACK_FILE_NAME)
-    : AGENT_DECISION_STACK_FILE_NAME;
-  const selectedAdditionalStackFileNames = hasExplicitRuntimeConstraint && Array.isArray(onboardingReport.selectedAdditionalStacks)
-    ? onboardingReport.selectedAdditionalStacks
-      .map((stackFileName) => normalizeMarkdownFileName(stackFileName, ''))
-      .filter((stackFileName) => stackFileName && stackFileName !== selectedStackFileName)
-    : [];
-  const selectedBlueprintFileName = hasExplicitArchitectureConstraint
-    ? normalizeMarkdownFileName(onboardingReport.selectedBlueprint, AGENT_DECISION_BLUEPRINT_FILE_NAME)
-    : AGENT_DECISION_BLUEPRINT_FILE_NAME;
-  const selectedAdditionalBlueprintFileNames = hasExplicitArchitectureConstraint && Array.isArray(onboardingReport.selectedAdditionalBlueprints)
-    ? onboardingReport.selectedAdditionalBlueprints
-      .map((blueprintFileName) => normalizeMarkdownFileName(blueprintFileName, ''))
-      .filter((blueprintFileName) => blueprintFileName && blueprintFileName !== selectedBlueprintFileName)
-    : [];
-  const includeCiGuardrails = typeof onboardingReport.ciGuardrailsEnabled === 'boolean'
-    ? onboardingReport.ciGuardrailsEnabled
-    : true;
-
-  await compileDynamicContext({
-    targetDirectoryPath: resolvedTargetDirectoryPath,
-    selectedStackFileName,
-    selectedAdditionalStackFileNames,
-    selectedBlueprintFileName,
-    selectedAdditionalBlueprintFileNames,
-    includeCiGuardrails,
-  });
-
   const optimizationDurationMs = Date.now() - optimizationStartedAt;
   const tokenOptimizationReport = {
     generatedAt: new Date().toISOString(),
@@ -174,7 +128,7 @@ export async function runOptimizeCommand(targetDirectoryArgument, optimizeOption
   console.log(`- Agent profile: ${tokenOptimizationState.selectedAgent}`);
   console.log(`- Preferred shell proxy: ${tokenOptimizationState.preferredShellProxy}`);
   console.log(`- Setup time: ${formatDuration(optimizationDurationMs)}`);
-  console.log('- Updated files: .agent-instructions.md, legacy thin adapters, and .agent-context/state/token-optimization.json');
+  console.log('- Updated files: .agent-context/state/token-optimization.json and .agent-context/state/token-optimization-report.json');
 
   if (tokenOptimizationState.enabled) {
     if (rtkDetection.isAvailable) {

package/lib/cli/commands/upgrade.mjs

@@ -33,15 +33,13 @@ import {
   detectUiScopeSignals,
 } from '../detector.mjs';
 import {
-  buildCompiledRulesContent,
-  compileDynamicContext,
   writeSelectedPolicy,
   writeOnboardingReport,
   loadOnboardingReportIfExists,
 } from '../compiler.mjs';
 
 import { runPreflightChecks } from '../preflight.mjs';
-import { createBackup } from '../backup.mjs';
+import { createBackup, ensureBackupGitignoreEntry } from '../backup.mjs';
 import { performRollback } from '../rollback.mjs';
 import {
   detectProjectDocTemplateStaleness,
@@ -55,7 +53,7 @@ export function parseUpgradeArguments(commandArguments) {
     targetDirectory: '.',
     dryRun: false,
     skipConfirmation: false,
-    includeMcpTemplate: true,
+    includeMcpTemplate: false,
     pruneManagedSurface: true,
   };
 
@@ -243,19 +241,10 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
       declarationShown: true,
       detectionSummary: buildDetectionSummary(projectDetection),
       activeRulesSummary: {
-        canonicalSource: '.instructions.md',
-        compiledRulebook: '.agent-instructions.md',
-        legacyThinAdapters: ['.cursorrules', '.windsurfrules', '.clauderc'],
-        generatedBridgeAdapters: [
-          'AGENTS.md',
-          'CLAUDE.md',
-          'GEMINI.md',
-          '.cursor/rules/agentic-senior-core.mdc',
-          '.windsurf/rules/agentic-senior-core.md',
-          '.github/copilot-instructions.md',
-          '.github/instructions/agentic-senior-core.instructions.md',
-          '.gemini/instructions.md',
-        ],
+        canonicalSource: 'AGENTS.md',
+        compiledRulebook: null,
+        legacyThinAdapters: [],
+        generatedBridgeAdapters: ['CLAUDE.md', 'GEMINI.md'],
         stackLoadingMode: 'lazy',
         domainRuleLoadingMode: 'lazy',
         selectedProfile: selectedProfileName,
@@ -285,7 +274,7 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     } else {
       console.log('- Detected stack: unresolved (insufficient markers).');
     }
-    console.log('- Active rules baseline: canonical .instructions.md -> compiled .agent-instructions.md + legacy thin root adapters');
+    console.log('- Active rules baseline: canonical AGENTS.md + .agent-context/ lazy rule library');
     console.log(
       `- Active review thresholds: ${(
         PROFILE_PRESETS[selectedProfileName]?.blockingSeverities || []
@@ -300,24 +289,6 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
 
     const projectDocStalenessReport = await detectProjectDocTemplateStaleness(resolvedTargetDirectoryPath);
 
-    const currentRulesPath = path.join(resolvedTargetDirectoryPath, '.agent-instructions.md');
-    const currentRulesContent = await pathExists(currentRulesPath)
-      ? await fs.readFile(currentRulesPath, 'utf8')
-      : '';
-
-    const plannedRulesContent = await buildCompiledRulesContent({
-      targetDirectoryPath: resolvedTargetDirectoryPath,
-      selectedStackFileName,
-      selectedAdditionalStackFileNames,
-      selectedBlueprintFileName,
-      selectedAdditionalBlueprintFileNames,
-      includeCiGuardrails,
-    });
-
-    const isRulesContentChanged = currentRulesContent !== plannedRulesContent;
-    const currentRuleLineCount = currentRulesContent ? currentRulesContent.split(/\r?\n/).length : 0;
-    const plannedRuleLineCount = plannedRulesContent.split(/\r?\n/).length;
-
     console.log('\nUpgrade preview:');
     console.log(`- Target directory: ${resolvedTargetDirectoryPath}`);
     console.log(`- Runtime decision: ${selectedStackFileName === AGENT_DECISION_STACK_FILE_NAME ? 'agent recommendation required from repo evidence' : toTitleCase(selectedStackFileName)}`);
@@ -329,14 +300,12 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
       console.log(`- Additional blueprints: ${selectedAdditionalBlueprintFileNames.map((blueprintFileName) => toTitleCase(blueprintFileName)).join(', ')}`);
     }
     console.log(`- CI/CD quality checks (guardrails): ${includeCiGuardrails ? 'enabled' : 'disabled'}`);
-    console.log(`- Existing rules lines: ${currentRuleLineCount}`);
-    console.log(`- Planned rules lines: ${plannedRuleLineCount}`);
-    console.log(`- Rules changed: ${isRulesContentChanged ? 'yes' : 'no'}`);
+    console.log('- Instruction surface: AGENTS.md canonical with CLAUDE.md and GEMINI.md import bridges');
     console.log(`- Managed surface stale files: ${managedSurfacePlan.staleFiles.length}`);
     console.log(`- Managed surface stale directories: ${managedSurfacePlan.staleDirectories.length}`);
     console.log(`- Managed surface sync mode: 1:1 (prune enabled)`);
     console.log(`- Managed surface prune mode: ${upgradeOptions.pruneManagedSurface === true ? 'enabled (default)' : 'disabled (--no-prune)'}`);
-    console.log(`- MCP config write mode: ${upgradeOptions.includeMcpTemplate === true ? 'enabled (default)' : 'disabled (--no-mcp-template)'}`);
+    console.log(`- MCP config write mode: ${upgradeOptions.includeMcpTemplate === true ? 'enabled (--mcp-template)' : 'disabled (default)'}`);
     if (projectDocStalenessReport.hasProjectDocs) {
       console.log(`- Project docs detected: ${projectDocStalenessReport.checkedFileNames.length}`);
       console.log(`- Project docs expected template version: ${projectDocStalenessReport.expectedTemplateVersion}`);
@@ -399,6 +368,10 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     }
 
     await createBackup(resolvedTargetDirectoryPath);
+    const backupGitignoreResult = await ensureBackupGitignoreEntry(resolvedTargetDirectoryPath);
+    if (backupGitignoreResult.status !== 'unchanged') {
+      console.log(`Local backup artifacts ignored in .gitignore (${backupGitignoreResult.entry}).`);
+    }
 
     try {
       const governanceSyncResult = await copyGovernanceAssetsToTarget(resolvedTargetDirectoryPath, {
@@ -427,15 +400,6 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         }
       }
 
-      const compileResult = await compileDynamicContext({
-        targetDirectoryPath: resolvedTargetDirectoryPath,
-        selectedStackFileName,
-        selectedAdditionalStackFileNames,
-        selectedBlueprintFileName,
-        selectedAdditionalBlueprintFileNames,
-        includeCiGuardrails,
-        preserveUserOwnedEntrypoints: true,
-      });
       await writeSelectedPolicy(resolvedTargetDirectoryPath, selectedProfileName);
 
       const setupDurationMs = Date.now() - setupStartedAt;
@@ -458,10 +422,8 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
 
       console.log('\nUpgrade complete.');
       console.log(`- Governance surface sync: 1:1 (${governanceSyncResult.updatedFiles.length} updated, ${governanceSyncResult.createdFiles.length} new, ${governanceSyncResult.deletedManagedFiles.length} deleted, ${governanceSyncResult.unchangedFiles.length} unchanged)`);
-      console.log(`- Rules rewritten: ${isRulesContentChanged ? 'yes' : 'no (metadata refreshed)'}`);
       const preservedInstructionEntrypoints = Array.from(new Set([
         ...(governanceSyncResult.preservedFiles || []),
-        ...(compileResult.preservedEntrypoints || []),
       ])).sort();
       if (preservedInstructionEntrypoints.length > 0) {
         console.log(`- User-owned instruction entrypoints preserved: ${preservedInstructionEntrypoints.length}`);
@@ -490,7 +452,7 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         supplementalCreatedFileNames.forEach((fileName) => console.log(`  [NEW]     ${fileName} (seed)`));
       }
 
-      console.log('\nRefreshed files: .instructions.md, .agent-instructions.md, legacy thin adapters, generated bridge adapters, and .agent-context/state/onboarding-report.json');
+      console.log('\nRefreshed files: AGENTS.md, CLAUDE.md, GEMINI.md, .agent-context/, and .agent-context/state/onboarding-report.json');
     } catch (error) {
       console.error('\n[FATAL] An error occurred during upgrade. Attempting automatic rollback...');
       try {