@ryuenn3123/agentic-senior-core 2.0.23 → 2.0.24

package/.cursorrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.0.23
+Generated by Agentic-Senior-Core CLI v2.0.24
 Timestamp: 2026-04-15T00:14:51.184Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json

package/.github/workflows/docs-quality-drift-report.yml

@@ -0,0 +1,37 @@
+name: Docs Quality Drift Report
+
+on:
+  schedule:
+    - cron: '30 3 * * 2'
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  docs-quality-drift-report:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Run docs quality drift report
+        run: |
+          node ./scripts/docs-quality-drift-report.mjs > docs-quality-drift-report.json
+          test -s docs-quality-drift-report.json
+
+      - name: Upload docs quality drift artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-quality-drift-report
+          path: docs-quality-drift-report.json

package/.windsurfrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.0.23
+Generated by Agentic-Senior-Core CLI v2.0.24
 Timestamp: 2026-04-15T00:14:51.184Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json

package/README.md

@@ -57,6 +57,9 @@ npx @ryuenn3123/agentic-senior-core init
 npm exec --yes @ryuenn3123/agentic-senior-core init
 ```
 
+If the target folder is empty, `init` now offers a quick-choice discovery mode by default.
+You can finish setup using numbered options (Enter selects the first option), and switch to detailed typing when needed.
+
 **Alternative: Global install (optional)**
 
 If you want the tool available system-wide without repeating `npx`:
@@ -139,6 +142,9 @@ npx @ryuenn3123/agentic-senior-core init --newbie
 
 - `init` creates governance files **in your project folder** (the folder where you run the command).
 - `init` does not copy repository workflows from this project into your target repository.
+- `init` project discovery accepts answers in any language; prompts stay in English, but non-English answers are supported.
+- Generated docs default to English for consistency; use `--docs-lang` only when you explicitly need a different output language.
+- After docs scaffolding, CLI prints prompt starter examples so users can iterate by prompt without rewriting full project context.
 - MCP server registration and trust/start are manual in IDE settings.
 - MCP workspace scaffold is opt-in via `--mcp-template` and creates `.vscode/mcp.json`.
 
@@ -293,6 +299,20 @@ npm run benchmark:bundle
 
 This gives a fast baseline of accuracy, writer-judge comparison, and evidence packaging in one pass.
 
+### Documentation Quality Drift Report
+
+Generate a machine-readable documentation-quality drift artifact:
+
+```bash
+npm run report:docs-quality-drift
+```
+
+For CI pipelines that only need stdout JSON:
+
+```bash
+node ./scripts/docs-quality-drift-report.mjs --stdout-only
+```
+
 ### Install and Setup Choices
 
 The CLI now supports a smaller decision surface for first-time setup:

package/lib/cli/commands/init.mjs

@@ -471,7 +471,9 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
           discoveryAnswers = await loadProjectConfig(initOptions.projectConfig);
           console.log(`\nLoaded project configuration from: ${initOptions.projectConfig}`);
         } else {
-          discoveryAnswers = await runProjectDiscovery(userInterface);
+          discoveryAnswers = await runProjectDiscovery(userInterface, {
+            defaultProjectName: path.basename(resolvedTargetDirectoryPath),
+          });
         }
 
         const normalizedConfigDocsLanguage = normalizeDocsLanguage(discoveryAnswers.docsLang || '');
@@ -563,6 +565,12 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     console.log(`I prepared a ${selectedProfile.displayName.toLowerCase()} governance pack for a ${toTitleCase(selectedResolvedStackFileName)} project using the ${toTitleCase(selectedResolvedBlueprintFileName)} blueprint.`);
     if (scaffoldingResult) {
       console.log(`I also generated project documentation (${scaffoldingResult.docsLanguage}) based on your project description. AI agents will use docs/ as project context.`);
+
+      const promptProjectName = scaffoldingResult.discoveryAnswers?.projectName || 'this project';
+      console.log('\nPrompt starter examples (copy and adapt in your IDE):');
+      console.log(`- Build an MVP for ${promptProjectName}. Follow Layer 9 docs and keep the current stack, database, and auth constraints.`);
+      console.log('- Add [new feature] and update docs/project-brief.md plus docs/flow-overview.md in the same change.');
+      console.log('- If this change needs architecture migration, propose a migration plan first, then implement after approval.');
     }
     console.log('Your AI tools will now receive one compiled rulebook plus the original source rules, and 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.');

package/lib/cli/project-scaffolder.mjs

@@ -8,7 +8,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { CLI_VERSION } from './constants.mjs';
-import { ensureDirectory, askChoice, toTitleCase, pathExists } from './utils.mjs';
+import { ensureDirectory, askChoice, askYesNo, toTitleCase, pathExists } from './utils.mjs';
 
 const CURRENT_FILE_PATH = fileURLToPath(import.meta.url);
 const CURRENT_DIRECTORY_PATH = path.dirname(CURRENT_FILE_PATH);
@@ -50,6 +50,73 @@ const AUTH_CHOICES = [
   'Other',
 ];
 
+const DISCOVERY_MODE_CHOICES = [
+  'Quick mode (mostly choices, fastest)',
+  'Detailed mode (type your own answers)',
+];
+
+const DESCRIPTION_TEMPLATE_CHOICES = [
+  'Marketplace / commerce platform',
+  'Internal operations dashboard',
+  'SaaS workflow product',
+  'Developer platform / API product',
+  'Content and community platform',
+  'Other',
+];
+
+const FEATURE_PRESET_CHOICES = [
+  'MVP foundation (auth, core CRUD, role-based access)',
+  'Commerce flow (catalog, cart, checkout)',
+  'Operations flow (dashboard, approvals, reporting)',
+  'API platform flow (keys, rate-limit, webhooks)',
+  'Content flow (publish, moderation, search)',
+  'Other',
+];
+
+const FEATURE_PRESET_MAP = {
+  'MVP foundation (auth, core CRUD, role-based access)': [
+    'Authentication and user profiles',
+    'Core CRUD workflow for primary resources',
+    'Role-based access control',
+  ],
+  'Commerce flow (catalog, cart, checkout)': [
+    'Product catalog and filtering',
+    'Shopping cart and wishlist',
+    'Checkout and payment processing flow',
+  ],
+  'Operations flow (dashboard, approvals, reporting)': [
+    'Operational dashboard with KPIs',
+    'Approval workflow and audit trail',
+    'Reporting and export functionality',
+  ],
+  'API platform flow (keys, rate-limit, webhooks)': [
+    'API key management',
+    'Rate limiting and usage quotas',
+    'Webhook delivery and retry handling',
+  ],
+  'Content flow (publish, moderation, search)': [
+    'Draft and publish workflow',
+    'Moderation queue and policy checks',
+    'Search and discovery experience',
+  ],
+};
+
+async function askFeatureList(userInterface) {
+  console.log('\nList your key features (one per line, press Enter to finish):');
+
+  const features = [];
+  while (features.length < 10) {
+    const featureLine = (await userInterface.question(`  Feature ${features.length + 1}: `)).trim();
+    if (!featureLine) {
+      break;
+    }
+
+    features.push(featureLine);
+  }
+
+  return features;
+}
+
 export function normalizeDocsLanguage(rawDocsLanguage = 'en') {
   const normalizedDocsLanguage = String(rawDocsLanguage || 'en').trim().toLowerCase();
   return SUPPORTED_DOC_LANGUAGES.has(normalizedDocsLanguage) ? normalizedDocsLanguage : null;
@@ -83,17 +150,67 @@ async function resolveTemplateFilePath(templateFileName, docsLanguage) {
  * Run the project discovery interview.
  * Returns a structured object with all user responses.
  */
-export async function runProjectDiscovery(userInterface) {
+export async function runProjectDiscovery(userInterface, options = {}) {
   console.log('\n--- Project Discovery ---');
   console.log('I will ask a few questions to generate project-specific documentation.');
   console.log('This helps AI agents understand your project before writing code.\n');
+  console.log('You can answer in your own language.');
+  console.log('CLI prompts stay in English, but non-English answers are fully supported.\n');
+
+  const selectedDiscoveryMode = await askChoice(
+    'How do you want to answer project questions?',
+    DISCOVERY_MODE_CHOICES,
+    userInterface
+  );
+
+  const isQuickMode = selectedDiscoveryMode === DISCOVERY_MODE_CHOICES[0];
+
+  const defaultProjectName = (options.defaultProjectName || '').trim();
+  let projectName = '';
+
+  if (isQuickMode && defaultProjectName) {
+    const projectNameSource = await askChoice(
+      'Project name source:',
+      [
+        `Use folder name (${defaultProjectName})`,
+        'Type custom project name',
+      ],
+      userInterface
+    );
+
+    if (projectNameSource.startsWith('Use folder name')) {
+      projectName = defaultProjectName;
+    }
+  }
+
+  if (!projectName) {
+    projectName = (await userInterface.question('Project name: ')).trim();
+  }
 
-  const projectName = (await userInterface.question('Project name: ')).trim();
   if (!projectName) {
     throw new Error('Project name is required for documentation scaffolding.');
   }
 
-  const projectDescription = (await userInterface.question('One-line description: ')).trim() || `A ${projectName} project.`;
+  let projectDescription = '';
+  if (isQuickMode) {
+    const selectedDescriptionTemplate = await askChoice(
+      'Project description template:',
+      DESCRIPTION_TEMPLATE_CHOICES,
+      userInterface
+    );
+
+    if (selectedDescriptionTemplate === 'Other') {
+      projectDescription = (await userInterface.question('One-line description: ')).trim();
+    } else {
+      projectDescription = `${selectedDescriptionTemplate} for ${projectName}.`;
+    }
+  } else {
+    projectDescription = (await userInterface.question('One-line description: ')).trim();
+  }
+
+  if (!projectDescription) {
+    projectDescription = `A ${projectName} project.`;
+  }
 
   const domainSelection = await askChoice(
     'Primary domain:',
@@ -128,31 +245,43 @@ export async function runProjectDiscovery(userInterface) {
     authStrategy = (await userInterface.question('Describe your auth setup: ')).trim() || 'Custom auth';
   }
 
-  console.log('\nList your key features (one per line, press Enter twice to finish):');
-  const features = [];
-  let consecutiveEmptyLineCount = 0;
-
-  while (features.length < 10) {
-    const featureLine = (await userInterface.question(`  Feature ${features.length + 1}: `)).trim();
+  let features = [];
+  if (isQuickMode) {
+    const selectedFeaturePreset = await askChoice(
+      'Feature set:',
+      FEATURE_PRESET_CHOICES,
+      userInterface
+    );
 
-    if (!featureLine) {
-      consecutiveEmptyLineCount += 1;
-      if (consecutiveEmptyLineCount >= 1 && features.length >= 1) {
-        break;
-      }
-      continue;
+    if (selectedFeaturePreset === 'Other') {
+      features = await askFeatureList(userInterface);
+    } else {
+      features = FEATURE_PRESET_MAP[selectedFeaturePreset] || [];
     }
-
-    consecutiveEmptyLineCount = 0;
-    features.push(featureLine);
+  } else {
+    features = await askFeatureList(userInterface);
   }
 
   if (features.length === 0) {
     features.push('Core functionality (define during development)');
   }
 
-  const additionalContext = (await userInterface.question('\nAdditional context (optional, press Enter to skip): ')).trim()
-    || 'No additional context provided.';
+  let additionalContext = 'No additional context provided.';
+  if (isQuickMode) {
+    const wantsAdditionalContext = await askYesNo(
+      'Add additional context now?',
+      userInterface,
+      false
+    );
+
+    if (wantsAdditionalContext) {
+      additionalContext = (await userInterface.question('Additional context: ')).trim()
+        || 'No additional context provided.';
+    }
+  } else {
+    additionalContext = (await userInterface.question('\nAdditional context (optional, press Enter to skip): ')).trim()
+      || 'No additional context provided.';
+  }
 
   return {
     projectName,

package/lib/cli/utils.mjs

@@ -52,7 +52,7 @@ export function printUsage() {
   console.log('  --mcp-template   Create .vscode/mcp.json workspace template (MCP trust/start remains manual in IDE)');
   console.log('  --scaffold-docs  Force project documentation scaffolding (architecture, database, API, flow)');
   console.log('  --no-scaffold-docs  Skip project documentation scaffolding');
-  console.log('  --docs-lang      Language for generated project docs (en, id; default: en)');
+  console.log('  --docs-lang      Optional override for generated project docs language (default: en)');
   console.log('  --project-config Path to a project config file for non-interactive doc scaffolding');
   console.log('  --dry-run    Preview upgrade without writing files');
   console.log('  --yes        Skip confirmation prompts for upgrade');
@@ -167,8 +167,14 @@ export async function askChoice(promptMessage, options, userInterface) {
   });
 
   while (true) {
-    const selectedRawInput = await userInterface.question('Choose a number: ');
-    const selectedIndex = Number.parseInt(selectedRawInput.trim(), 10) - 1;
+    const selectedRawInput = await userInterface.question('Choose a number (press Enter for 1): ');
+    const normalizedInput = selectedRawInput.trim();
+
+    if (!normalizedInput) {
+      return options[0];
+    }
+
+    const selectedIndex = Number.parseInt(normalizedInput, 10) - 1;
 
     if (Number.isNaN(selectedIndex) || selectedIndex < 0 || selectedIndex >= options.length) {
       console.log('Invalid choice. Please select a valid number.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "2.0.23",
+  "version": "2.0.24",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -53,6 +53,7 @@
     "benchmark:gate": "node ./scripts/benchmark-gate.mjs",
     "benchmark:intelligence": "node ./scripts/benchmark-intelligence.mjs",
     "report:quality-trend": "node ./scripts/quality-trend-report.mjs",
+    "report:docs-quality-drift": "node ./scripts/docs-quality-drift-report.mjs",
     "report:governance-weekly": "node ./scripts/governance-weekly-report.mjs",
     "validate": "node ./scripts/validate.mjs",
     "test": "node --test ./tests/cli-smoke.test.mjs ./tests/mcp-server.test.mjs ./tests/llm-judge.test.mjs ./tests/enterprise-ops.test.mjs ./tests/skill-tier-gate.test.mjs"

package/scripts/docs-quality-drift-report.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+
+/**
+ * docs-quality-drift-report.mjs
+ *
+ * Generates a machine-readable documentation quality drift artifact.
+ * Tracks plain-language readability signals and trend deltas over time.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const SCRIPT_DIR = dirname(SCRIPT_FILE_PATH);
+const REPOSITORY_ROOT = resolve(SCRIPT_DIR, '..');
+const REPORT_PATH = join(REPOSITORY_ROOT, '.agent-context', 'state', 'docs-quality-drift-report.json');
+const ARGUMENT_FLAGS = new Set(process.argv.slice(2));
+const isStdoutOnlyMode = ARGUMENT_FLAGS.has('--stdout-only');
+const HISTORY_LIMIT = 52;
+const LONG_SENTENCE_WORD_THRESHOLD = 28;
+
+const MONITORED_STATIC_FILE_PATHS = [
+  'README.md',
+  'CHANGELOG.md',
+  '.instructions.md',
+  'AGENTS.md',
+  '.github/copilot-instructions.md',
+  '.gemini/instructions.md',
+  'docs/deep_analysis_and_roadmap_backlog.md',
+];
+
+const MONITORED_DIRECTORY_PATHS = [
+  'docs',
+  '.agent-context/prompts',
+  '.agent-context/review-checklists',
+];
+
+const FORBIDDEN_BUZZWORDS = [
+  'delve',
+  'leverage',
+  'robust',
+  'utilize',
+  'seamless',
+];
+
+function normalizeLineEndings(content) {
+  return content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
+function extractWordCount(content) {
+  const words = content.match(/[A-Za-z0-9']+/g) || [];
+  return words.length;
+}
+
+function extractSentenceWordCounts(content) {
+  const sentenceFragments = content
+    .split(/[.!?]+/u)
+    .map((fragment) => fragment.trim())
+    .filter((fragment) => fragment.length > 0);
+
+  const sentenceWordCounts = [];
+  for (const sentenceFragment of sentenceFragments) {
+    const sentenceWordCount = extractWordCount(sentenceFragment);
+    if (sentenceWordCount > 0) {
+      sentenceWordCounts.push(sentenceWordCount);
+    }
+  }
+
+  return sentenceWordCounts;
+}
+
+function countEmoji(content) {
+  const emojiMatches = content.match(/[\p{Extended_Pictographic}]/gu) || [];
+  return emojiMatches.length;
+}
+
+function countForbiddenBuzzwords(content) {
+  const buzzwordCounts = {};
+
+  for (const forbiddenBuzzword of FORBIDDEN_BUZZWORDS) {
+    const buzzwordRegex = new RegExp(`\\b${forbiddenBuzzword}\\b`, 'gi');
+    const matchCount = (content.match(buzzwordRegex) || []).length;
+    buzzwordCounts[forbiddenBuzzword] = matchCount;
+  }
+
+  return buzzwordCounts;
+}
+
+async function collectMarkdownFiles(directoryPath) {
+  const markdownFilePaths = [];
+
+  async function walk(currentDirectoryPath) {
+    if (!existsSync(currentDirectoryPath)) {
+      return;
+    }
+
+    const directoryEntries = await fs.readdir(currentDirectoryPath, { withFileTypes: true });
+
+    for (const directoryEntry of directoryEntries) {
+      if (directoryEntry.name === 'node_modules' || directoryEntry.name === '.git' || directoryEntry.name === '.benchmarks') {
+        continue;
+      }
+
+      const entryPath = join(currentDirectoryPath, directoryEntry.name);
+
+      if (directoryEntry.isDirectory()) {
+        await walk(entryPath);
+        continue;
+      }
+
+      if (directoryEntry.isFile() && directoryEntry.name.toLowerCase().endsWith('.md')) {
+        markdownFilePaths.push(entryPath);
+      }
+    }
+  }
+
+  await walk(directoryPath);
+  return markdownFilePaths;
+}
+
+async function collectMonitoredFiles() {
+  const collectedFilePathSet = new Set();
+
+  for (const relativeFilePath of MONITORED_STATIC_FILE_PATHS) {
+    const absoluteFilePath = join(REPOSITORY_ROOT, relativeFilePath);
+    if (existsSync(absoluteFilePath)) {
+      collectedFilePathSet.add(absoluteFilePath);
+    }
+  }
+
+  for (const relativeDirectoryPath of MONITORED_DIRECTORY_PATHS) {
+    const absoluteDirectoryPath = join(REPOSITORY_ROOT, relativeDirectoryPath);
+    const markdownFiles = await collectMarkdownFiles(absoluteDirectoryPath);
+
+    for (const markdownFilePath of markdownFiles) {
+      collectedFilePathSet.add(markdownFilePath);
+    }
+  }
+
+  return Array.from(collectedFilePathSet).sort((firstPath, secondPath) => firstPath.localeCompare(secondPath));
+}
+
+function readJsonOrNull(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function clamp(value, minimum, maximum) {
+  return Math.max(minimum, Math.min(maximum, value));
+}
+
+function buildQualityScore(metrics) {
+  const longSentencePenalty = metrics.longSentenceRatePercent * 0.4;
+  const buzzwordPenalty = metrics.totalForbiddenBuzzwordHits * 1.5;
+  const emojiPenalty = metrics.emojiCount * 5;
+  const averageSentencePenalty = metrics.averageWordsPerSentence > 24
+    ? (metrics.averageWordsPerSentence - 24) * 1.2
+    : 0;
+
+  const rawScore = 100 - longSentencePenalty - buzzwordPenalty - emojiPenalty - averageSentencePenalty;
+  return Number(clamp(rawScore, 0, 100).toFixed(2));
+}
+
+function summarizeTrend(currentSummary, previousSummary) {
+  if (!previousSummary) {
+    return {
+      hasBaseline: false,
+      trend: 'baseline-created',
+      deltaQualityScore: null,
+      deltaLongSentenceRatePercent: null,
+      deltaForbiddenBuzzwordHits: null,
+      deltaEmojiCount: null,
+    };
+  }
+
+  const deltaQualityScore = Number((currentSummary.qualityScore - previousSummary.qualityScore).toFixed(2));
+  const deltaLongSentenceRatePercent = Number((currentSummary.longSentenceRatePercent - previousSummary.longSentenceRatePercent).toFixed(2));
+  const deltaForbiddenBuzzwordHits = currentSummary.totalForbiddenBuzzwordHits - previousSummary.totalForbiddenBuzzwordHits;
+  const deltaEmojiCount = currentSummary.emojiCount - previousSummary.emojiCount;
+
+  let trend = 'stable';
+  if (deltaQualityScore >= 1 && deltaLongSentenceRatePercent <= 0 && deltaForbiddenBuzzwordHits <= 0 && deltaEmojiCount <= 0) {
+    trend = 'improving';
+  } else if (deltaQualityScore <= -1 || deltaLongSentenceRatePercent > 0 || deltaForbiddenBuzzwordHits > 0 || deltaEmojiCount > 0) {
+    trend = 'regressing';
+  }
+
+  return {
+    hasBaseline: true,
+    trend,
+    deltaQualityScore,
+    deltaLongSentenceRatePercent,
+    deltaForbiddenBuzzwordHits,
+    deltaEmojiCount,
+  };
+}
+
+function buildHistoryEntry(report) {
+  return {
+    generatedAt: report.generatedAt,
+    qualityScore: report.summary.qualityScore,
+    documentCount: report.summary.documentCount,
+    averageWordsPerSentence: report.summary.averageWordsPerSentence,
+    longSentenceRatePercent: report.summary.longSentenceRatePercent,
+    totalForbiddenBuzzwordHits: report.summary.totalForbiddenBuzzwordHits,
+    emojiCount: report.summary.emojiCount,
+  };
+}
+
+function mergeHistory(previousReport, currentHistoryEntry) {
+  const existingHistory = Array.isArray(previousReport?.history) ? previousReport.history : [];
+  const mergedHistory = [...existingHistory, currentHistoryEntry];
+
+  if (mergedHistory.length <= HISTORY_LIMIT) {
+    return mergedHistory;
+  }
+
+  return mergedHistory.slice(mergedHistory.length - HISTORY_LIMIT);
+}
+
+async function runDocsQualityDriftReport() {
+  const monitoredFilePaths = await collectMonitoredFiles();
+
+  const fileSummaries = [];
+  let totalLineCount = 0;
+  let totalWordCount = 0;
+  let totalSentenceCount = 0;
+  let totalLongSentenceCount = 0;
+  let totalEmojiCount = 0;
+  const forbiddenBuzzwordTotals = Object.fromEntries(FORBIDDEN_BUZZWORDS.map((word) => [word, 0]));
+
+  for (const monitoredFilePath of monitoredFilePaths) {
+    const rawContent = await fs.readFile(monitoredFilePath, 'utf8');
+    const normalizedContent = normalizeLineEndings(rawContent);
+
+    const lineCount = normalizedContent.length === 0 ? 0 : normalizedContent.split('\n').length;
+    const wordCount = extractWordCount(normalizedContent);
+    const sentenceWordCounts = extractSentenceWordCounts(normalizedContent);
+    const sentenceCount = sentenceWordCounts.length;
+    const longSentenceCount = sentenceWordCounts.filter((sentenceWordCount) => sentenceWordCount > LONG_SENTENCE_WORD_THRESHOLD).length;
+    const emojiCount = countEmoji(normalizedContent);
+    const forbiddenBuzzwordCounts = countForbiddenBuzzwords(normalizedContent);
+
+    totalLineCount += lineCount;
+    totalWordCount += wordCount;
+    totalSentenceCount += sentenceCount;
+    totalLongSentenceCount += longSentenceCount;
+    totalEmojiCount += emojiCount;
+
+    for (const forbiddenBuzzword of FORBIDDEN_BUZZWORDS) {
+      forbiddenBuzzwordTotals[forbiddenBuzzword] += forbiddenBuzzwordCounts[forbiddenBuzzword];
+    }
+
+    fileSummaries.push({
+      filePath: relative(REPOSITORY_ROOT, monitoredFilePath).replace(/\\/g, '/'),
+      lineCount,
+      wordCount,
+      sentenceCount,
+      longSentenceCount,
+      emojiCount,
+      forbiddenBuzzwordCounts,
+    });
+  }
+
+  const averageWordsPerSentence = totalSentenceCount === 0
+    ? 0
+    : Number((totalWordCount / totalSentenceCount).toFixed(2));
+  const longSentenceRatePercent = totalSentenceCount === 0
+    ? 0
+    : Number(((totalLongSentenceCount / totalSentenceCount) * 100).toFixed(2));
+  const totalForbiddenBuzzwordHits = FORBIDDEN_BUZZWORDS.reduce(
+    (sum, forbiddenBuzzword) => sum + forbiddenBuzzwordTotals[forbiddenBuzzword],
+    0
+  );
+
+  const summary = {
+    documentCount: monitoredFilePaths.length,
+    totalLineCount,
+    totalWordCount,
+    totalSentenceCount,
+    averageWordsPerSentence,
+    longSentenceCount: totalLongSentenceCount,
+    longSentenceRatePercent,
+    emojiCount: totalEmojiCount,
+    forbiddenBuzzwordTotals,
+    totalForbiddenBuzzwordHits,
+    qualityScore: 0,
+  };
+
+  summary.qualityScore = buildQualityScore(summary);
+
+  const previousReport = readJsonOrNull(REPORT_PATH);
+  const previousSummary = previousReport?.summary || null;
+  const trend = summarizeTrend(summary, previousSummary);
+
+  const sortedBuzzwordBreakdown = Object.entries(forbiddenBuzzwordTotals)
+    .map(([term, hits]) => ({ term, hits }))
+    .sort((firstEntry, secondEntry) => secondEntry.hits - firstEntry.hits);
+
+  const docsQualityDriftReportSnapshot = {
+    generatedAt: new Date().toISOString(),
+    reportName: 'docs-quality-drift-report',
+    passed: summary.emojiCount === 0,
+    methodology: {
+      monitoredStaticFiles: MONITORED_STATIC_FILE_PATHS,
+      monitoredDirectories: MONITORED_DIRECTORY_PATHS,
+      forbiddenBuzzwords: FORBIDDEN_BUZZWORDS,
+      longSentenceWordThreshold: LONG_SENTENCE_WORD_THRESHOLD,
+    },
+    summary,
+    trend,
+    buzzwordBreakdown: sortedBuzzwordBreakdown,
+    topLongSentenceRiskFiles: fileSummaries
+      .map((fileSummary) => ({
+        filePath: fileSummary.filePath,
+        longSentenceCount: fileSummary.longSentenceCount,
+      }))
+      .filter((fileSummary) => fileSummary.longSentenceCount > 0)
+      .sort((firstFile, secondFile) => secondFile.longSentenceCount - firstFile.longSentenceCount)
+      .slice(0, 10),
+    fileSummaries,
+    artifact: {
+      path: REPORT_PATH,
+      writeMode: isStdoutOnlyMode ? 'stdout-only' : 'stdout-and-file',
+    },
+  };
+
+  const history = mergeHistory(previousReport, buildHistoryEntry(docsQualityDriftReportSnapshot));
+  const docsQualityDriftReport = {
+    ...docsQualityDriftReportSnapshot,
+    history,
+  };
+
+  if (!isStdoutOnlyMode) {
+    await fs.mkdir(dirname(REPORT_PATH), { recursive: true });
+    await fs.writeFile(REPORT_PATH, JSON.stringify(docsQualityDriftReport, null, 2) + '\n', 'utf8');
+  }
+
+  return docsQualityDriftReport;
+}
+
+runDocsQualityDriftReport()
+  .then((docsQualityDriftReport) => {
+    console.log(JSON.stringify(docsQualityDriftReport, null, 2));
+  })
+  .catch((docsQualityError) => {
+    const errorMessage = docsQualityError instanceof Error ? docsQualityError.message : String(docsQualityError);
+    console.error(`Docs quality drift report failed: ${errorMessage}`);
+    process.exit(1);
+  });

package/scripts/validate.mjs

@@ -166,6 +166,7 @@ async function validateRequiredFiles() {
     'scripts/benchmark-writer-judge-matrix.mjs',
     'scripts/benchmark-gate.mjs',
     'scripts/benchmark-intelligence.mjs',
+    'scripts/docs-quality-drift-report.mjs',
     'scripts/governance-weekly-report.mjs',
     'scripts/mcp-server.mjs',
     'scripts/frontend-usability-audit.mjs',
@@ -198,6 +199,7 @@ async function validateRequiredFiles() {
     '.github/workflows/release-gate.yml',
     '.github/workflows/sbom-compliance.yml',
     '.github/workflows/benchmark-intelligence.yml',
+    '.github/workflows/docs-quality-drift-report.yml',
     '.github/workflows/governance-weekly-report.yml',
     'tests/cli-smoke.test.mjs',
     'tests/mcp-server.test.mjs',