scene-capability-engine 3.6.48 → 3.6.49

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.49] - 2026-03-14
+
+### Changed
+- Added `scripts/release-doc-version-audit.js` and wired it into package scripts, CI, release, and steering-hygiene workflows so README release metadata drift now blocks publish instead of relying on manual sync.
+- Synced `README.md`, `README.zh.md`, `.sce/README.md`, and `template/.sce/README.md` release footers to the current package version/date and removed stale hardcoded capability-version headings from long-lived project guide READMEs.
+- Added a new project-calibrated refactor trigger capability via `scripts/refactor-trigger-audit.js`, plus a matching steering baseline rule: each SCE project should periodically evaluate its own file-size distribution, while `2000 / 4000 / 10000` remains the default source-file fallback when no project-specific threshold is set.
+
 ## [3.6.48] - 2026-03-14
 
 ### Changed

package/README.md

@@ -143,6 +143,7 @@ SCE is opinionated by default.
 - `verify` and `release` enforce problem-closure and related gates when a spec is bound.
 - Autonomous program execution applies gate evaluation, fallback-chain logic, governance replay, and auto-remediation.
 - State persistence prefers SQLite, not ad hoc local caches.
+- Oversized source files must trigger periodic refactor assessment; SCE recommends project-specific thresholds, with `2000 / 4000 / 10000` as the default source-file fallback.
 - Release validation defaults to integration test coverage via `npm run test:release` for faster publish feedback.
 
 ---
@@ -216,5 +217,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.34
-**Last Updated**: 2026-03-08
+**Version**: 3.6.49
+**Last Updated**: 2026-03-14

package/README.zh.md

@@ -148,6 +148,7 @@ SCE 默认是强治理的。
 - 当 spec 绑定时，`verify` 和 `release` 默认执行 problem-closure 等相关门禁
 - `close-loop-program` 默认带 gate 评估、fallback-chain、governance replay、auto-remediation
 - 状态持久化默认优先走 SQLite，而不是零散本地缓存
+- 超大源文件必须定期触发重构评估；SCE 优先建议按项目给出阈值，若项目尚未设定，则默认参考 `2000 / 4000 / 10000`
 - 发布默认验证走 integration gate：`npm run test:release`
 
 ---
@@ -221,5 +222,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.34
-**最后更新**：2026-03-08
+**版本**：3.6.49
+**最后更新**：2026-03-14

package/lib/workspace/takeover-baseline.js

@@ -45,6 +45,16 @@ const BACKEND_API_PRECEDENCE_CORE_PRINCIPLE_SECTION = [
   '- 除非明确要求新建接口或修改后端接口，否则禁止为了迁就前端错误调用去随意改后端实现或契约。',
   '- 默认优先修正前端请求、映射、类型和兼容处理，使其与后端接口保持一致；若怀疑后端契约错误，应先确认再改。'
 ].join('\n');
+const LARGE_FILE_REFACTOR_CORE_PRINCIPLE_HEADING = '## 15. 单文件规模过大必须触发重构评估，禁止无限堆积';
+const LARGE_FILE_REFACTOR_CORE_PRINCIPLE_SECTION = [
+  LARGE_FILE_REFACTOR_CORE_PRINCIPLE_HEADING,
+  '',
+  '- SCE 应为每个项目定期评估代码规模分布，并给出项目级的重构参考节点；禁止假设所有项目都适用同一个固定行数阈值。',
+  '- 若项目尚未建立自己的阈值，默认参考源文件 `2000 / 4000 / 10000` 行三档触发：分别对应“必须评估”“必须发起重构收敛”“进入红线区”。',
+  '- 达到项目级或默认阈值后，后续改动必须优先评估拆分模块、服务、命令面或数据职责；超过重构/红线阈值时，不得继续无计划堆积复杂度。',
+  '- 项目开始较小时，阈值应更早触发；项目进入长期演进后，也必须按周或发布前重新评估，而不是让早期设定永久失效。',
+  '- 行数阈值只是强触发信号，不代表低于阈值就可以忽略耦合、职责混杂、测试失控和理解成本问题；若复杂度已明显失控，应提前启动重构。'
+].join('\n');
 const REQUIRED_CORE_PRINCIPLE_SECTIONS = Object.freeze([
   {
     heading: CLARIFICATION_FIRST_CORE_PRINCIPLE_HEADING,
@@ -61,6 +71,10 @@ const REQUIRED_CORE_PRINCIPLE_SECTIONS = Object.freeze([
   {
     heading: BACKEND_API_PRECEDENCE_CORE_PRINCIPLE_HEADING,
     section: BACKEND_API_PRECEDENCE_CORE_PRINCIPLE_SECTION
+  },
+  {
+    heading: LARGE_FILE_REFACTOR_CORE_PRINCIPLE_HEADING,
+    section: LARGE_FILE_REFACTOR_CORE_PRINCIPLE_SECTION
   }
 ]);
 
@@ -886,6 +900,8 @@ module.exports = {
   STEERING_CHANGE_EVALUATION_CORE_PRINCIPLE_SECTION,
   BACKEND_API_PRECEDENCE_CORE_PRINCIPLE_HEADING,
   BACKEND_API_PRECEDENCE_CORE_PRINCIPLE_SECTION,
+  LARGE_FILE_REFACTOR_CORE_PRINCIPLE_HEADING,
+  LARGE_FILE_REFACTOR_CORE_PRINCIPLE_SECTION,
   REQUIRED_CORE_PRINCIPLE_SECTIONS,
   ERRORBOOK_REGISTRY_DEFAULTS,
   ERRORBOOK_CONVERGENCE_DEFAULTS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.6.48",
+  "version": "3.6.49",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {
@@ -40,9 +40,13 @@
     "test:sce-tracking": "node scripts/check-sce-tracking.js",
     "gate:npm-runtime-assets": "node scripts/npm-package-runtime-asset-check.js --fail-on-violation",
     "test:brand-consistency": "node scripts/check-branding-consistency.js",
+    "audit:release-docs": "node scripts/release-doc-version-audit.js --fail-on-error",
+    "audit:refactor-trigger": "node scripts/refactor-trigger-audit.js",
     "audit:steering": "node scripts/steering-content-audit.js --fail-on-error",
     "audit:clarification-first": "node scripts/clarification-first-audit.js --fail-on-violation",
     "audit:state-storage": "node scripts/state-storage-tiering-audit.js",
+    "report:release-docs": "node scripts/release-doc-version-audit.js --json",
+    "report:refactor-trigger": "node scripts/refactor-trigger-audit.js --json",
     "report:steering-audit": "node scripts/steering-content-audit.js --json",
     "report:clarification-first-audit": "node scripts/clarification-first-audit.js --json",
     "report:state-storage": "node scripts/state-storage-tiering-audit.js --json",
@@ -86,7 +90,7 @@
     "gate:release-asset-integrity": "node scripts/release-asset-integrity-check.js",
     "report:release-risk-remediation": "node scripts/release-risk-remediation-bundle.js --json",
     "report:moqui-core-regression": "node scripts/moqui-core-regression-suite.js --json",
-    "prepublishOnly": "npm run test:release && npm run test:skip-audit && npm run test:sce-tracking && npm run gate:npm-runtime-assets && npm run test:brand-consistency && npm run audit:steering && npm run audit:clarification-first && npm run gate:git-managed && npm run gate:errorbook-registry-health && npm run gate:errorbook-release && npm run report:interactive-governance -- --fail-on-alert",
+    "prepublishOnly": "npm run test:release && npm run test:skip-audit && npm run test:sce-tracking && npm run gate:npm-runtime-assets && npm run test:brand-consistency && npm run audit:release-docs && npm run audit:steering && npm run audit:clarification-first && npm run gate:git-managed && npm run gate:errorbook-registry-health && npm run gate:errorbook-release && npm run report:interactive-governance -- --fail-on-alert",
     "publish:manual": "npm publish --access public",
     "install-global": "npm install -g .",
     "uninstall-global": "npm uninstall -g scene-capability-engine"

package/scripts/refactor-trigger-audit.js

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CODE_EXTENSIONS = new Set([
+  '.js', '.cjs', '.mjs', '.jsx',
+  '.ts', '.tsx',
+  '.py',
+  '.java',
+  '.go',
+  '.rb',
+  '.php',
+  '.cs'
+]);
+
+const DEFAULT_SCAN_DIRS = [
+  'src',
+  'lib',
+  'scripts',
+  'bin',
+  'app',
+  'server',
+  'client',
+  'packages',
+  'tests'
+];
+
+const SKIP_DIRS = new Set([
+  '.git',
+  '.hg',
+  '.svn',
+  'node_modules',
+  'dist',
+  'build',
+  'coverage',
+  '.next',
+  '.turbo',
+  '.idea',
+  '.vscode',
+  '.sce/reports'
+]);
+
+const THRESHOLD_PROFILES = Object.freeze({
+  source: {
+    floors: {
+      assessment: 800,
+      refactor: 1800
+    },
+    defaults: {
+      assessment: 2000,
+      refactor: 4000,
+      redline: 10000
+    }
+  },
+  test: {
+    floors: {
+      assessment: 1200,
+      refactor: 3000
+    },
+    defaults: {
+      assessment: 3000,
+      refactor: 6000,
+      redline: 15000
+    }
+  }
+});
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const options = {
+    projectPath: process.cwd(),
+    json: false,
+    failOnRedline: false,
+    out: null,
+    scanDirs: DEFAULT_SCAN_DIRS.slice()
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const next = argv[index + 1];
+    if (token === '--project-path' && next) {
+      options.projectPath = path.resolve(next);
+      index += 1;
+      continue;
+    }
+    if (token === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (token === '--fail-on-redline') {
+      options.failOnRedline = true;
+      continue;
+    }
+    if (token === '--out' && next) {
+      options.out = path.resolve(next);
+      index += 1;
+      continue;
+    }
+    if (token === '--scan-dir' && next) {
+      options.scanDirs.push(next.trim());
+      index += 1;
+      continue;
+    }
+  }
+
+  options.scanDirs = Array.from(new Set(options.scanDirs.filter(Boolean)));
+  return options;
+}
+
+function normalizePath(value) {
+  return `${value || ''}`.replace(/\\/g, '/');
+}
+
+function shouldSkipDir(relativePath, entryName) {
+  if (SKIP_DIRS.has(entryName)) {
+    return true;
+  }
+  return SKIP_DIRS.has(normalizePath(relativePath));
+}
+
+function collectFilesRecursive(rootDir, relativeRoot = '') {
+  if (!fs.existsSync(rootDir)) {
+    return [];
+  }
+
+  const results = [];
+  const entries = fs.readdirSync(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = path.join(rootDir, entry.name);
+    const relativePath = normalizePath(path.join(relativeRoot, entry.name));
+    if (entry.isDirectory()) {
+      if (shouldSkipDir(relativePath, entry.name)) {
+        continue;
+      }
+      results.push(...collectFilesRecursive(absolutePath, relativePath));
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    if (!CODE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+      continue;
+    }
+    results.push({
+      absolutePath,
+      relativePath
+    });
+  }
+  return results;
+}
+
+function classifyFile(relativePath) {
+  const normalized = normalizePath(relativePath).toLowerCase();
+  if (
+    normalized.startsWith('tests/')
+    || normalized.includes('/__tests__/')
+    || normalized.includes('.test.')
+    || normalized.includes('.spec.')
+  ) {
+    return 'test';
+  }
+  return 'source';
+}
+
+function countLines(content) {
+  if (!content) {
+    return 0;
+  }
+  return content.split(/\r?\n/).length;
+}
+
+function roundUp(value, step) {
+  if (!Number.isFinite(value) || value <= 0) {
+    return 0;
+  }
+  return Math.ceil(value / step) * step;
+}
+
+function quantile(sortedValues, ratio) {
+  if (!Array.isArray(sortedValues) || sortedValues.length === 0) {
+    return 0;
+  }
+  if (sortedValues.length === 1) {
+    return sortedValues[0];
+  }
+  const index = Math.max(0, Math.min(sortedValues.length - 1, Math.ceil(sortedValues.length * ratio) - 1));
+  return sortedValues[index];
+}
+
+function buildStats(files) {
+  const lineValues = files.map((item) => item.lines).sort((left, right) => left - right);
+  const count = lineValues.length;
+  return {
+    count,
+    max: count > 0 ? lineValues[count - 1] : 0,
+    p50: quantile(lineValues, 0.5),
+    p90: quantile(lineValues, 0.9),
+    p95: quantile(lineValues, 0.95)
+  };
+}
+
+function buildRecommendedThresholds(stats, profile) {
+  const assessmentRaw = roundUp(Math.max(profile.floors.assessment, stats.p90 * 1.25), 50);
+  const refactorRaw = roundUp(Math.max(profile.floors.refactor, stats.p95 * 1.35, assessmentRaw + 400), 50);
+
+  const assessment = Math.min(profile.defaults.assessment, Math.max(profile.floors.assessment, assessmentRaw));
+  const refactor = Math.min(profile.defaults.refactor, Math.max(profile.floors.refactor, refactorRaw, assessment + 400));
+  const redline = profile.defaults.redline;
+
+  return {
+    assessment,
+    refactor,
+    redline
+  };
+}
+
+function evaluateFile(lines, thresholds) {
+  if (lines >= thresholds.redline) {
+    return 'redline';
+  }
+  if (lines >= thresholds.refactor) {
+    return 'refactor';
+  }
+  if (lines >= thresholds.assessment) {
+    return 'assessment';
+  }
+  return 'ok';
+}
+
+function auditRefactorTriggers(options = {}) {
+  const projectPath = path.resolve(options.projectPath || process.cwd());
+  const scanDirs = Array.isArray(options.scanDirs) && options.scanDirs.length > 0
+    ? options.scanDirs
+    : DEFAULT_SCAN_DIRS;
+
+  const files = Array.from(new Set(scanDirs))
+    .flatMap((dirName) => collectFilesRecursive(path.join(projectPath, dirName), dirName))
+    .map((file) => {
+      const content = fs.readFileSync(file.absolutePath, 'utf8');
+      const kind = classifyFile(file.relativePath);
+      return {
+        file: file.relativePath,
+        kind,
+        lines: countLines(content)
+      };
+    })
+    .sort((left, right) => right.lines - left.lines || left.file.localeCompare(right.file));
+
+  const sourceFiles = files.filter((item) => item.kind === 'source');
+  const testFiles = files.filter((item) => item.kind === 'test');
+  const sourceStats = buildStats(sourceFiles);
+  const testStats = buildStats(testFiles);
+  const sourceThresholds = buildRecommendedThresholds(sourceStats, THRESHOLD_PROFILES.source);
+  const testThresholds = buildRecommendedThresholds(testStats, THRESHOLD_PROFILES.test);
+
+  const evaluatedFiles = files.map((file) => {
+    const thresholds = file.kind === 'test' ? testThresholds : sourceThresholds;
+    return {
+      ...file,
+      thresholds,
+      trigger: evaluateFile(file.lines, thresholds)
+    };
+  });
+
+  const offenders = evaluatedFiles.filter((item) => item.trigger !== 'ok');
+  const redline = offenders.filter((item) => item.trigger === 'redline');
+  const refactor = offenders.filter((item) => item.trigger === 'refactor');
+  const assessment = offenders.filter((item) => item.trigger === 'assessment');
+
+  const recommendations = [
+    'Run this audit weekly and before each release to recalibrate project-specific refactor trigger points.',
+    'When no project-specific threshold is agreed yet, keep the SCE default source thresholds as the outer guardrail: 2000 / 4000 / 10000 lines.',
+    redline.length > 0
+      ? 'Redline files already exist; new non-emergency changes touching those files should prioritize decomposition instead of feature accretion.'
+      : 'No redline file detected under the current recommended thresholds.'
+  ];
+
+  return {
+    mode: 'refactor-trigger-audit',
+    project_path: projectPath,
+    passed: redline.length === 0,
+    scan_dirs: scanDirs,
+    scanned_file_count: files.length,
+    cadence_recommendation: ['weekly', 'before_release'],
+    thresholds: {
+      source: sourceThresholds,
+      test: testThresholds
+    },
+    stats: {
+      source: sourceStats,
+      test: testStats
+    },
+    summary: {
+      offender_count: offenders.length,
+      assessment_count: assessment.length,
+      refactor_count: refactor.length,
+      redline_count: redline.length
+    },
+    offenders: offenders.slice(0, 50),
+    top_files: evaluatedFiles.slice(0, 20),
+    recommendations
+  };
+}
+
+function maybeWriteReport(result, outPath) {
+  if (!outPath) {
+    return;
+  }
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+}
+
+function printHumanReport(result) {
+  console.log(
+    `[refactor-trigger-audit] scanned=${result.scanned_file_count} offenders=${result.summary.offender_count} `
+    + `assessment=${result.summary.assessment_count} refactor=${result.summary.refactor_count} redline=${result.summary.redline_count}`
+  );
+  console.log(
+    `[refactor-trigger-audit] source-thresholds=${result.thresholds.source.assessment}/${result.thresholds.source.refactor}/${result.thresholds.source.redline} `
+    + `test-thresholds=${result.thresholds.test.assessment}/${result.thresholds.test.refactor}/${result.thresholds.test.redline}`
+  );
+  if (result.summary.redline_count > 0) {
+    result.offenders
+      .filter((item) => item.trigger === 'redline')
+      .slice(0, 10)
+      .forEach((item) => {
+        console.error(`[refactor-trigger-audit] redline ${item.kind} ${item.file} (${item.lines} lines)`);
+      });
+  }
+}
+
+if (require.main === module) {
+  const options = parseArgs(process.argv.slice(2));
+  const result = auditRefactorTriggers(options);
+  maybeWriteReport(result, options.out);
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    printHumanReport(result);
+  }
+
+  if (options.failOnRedline && result.summary.redline_count > 0) {
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  DEFAULT_SCAN_DIRS,
+  THRESHOLD_PROFILES,
+  auditRefactorTriggers,
+  buildRecommendedThresholds,
+  buildStats,
+  classifyFile,
+  parseArgs
+};

package/scripts/release-doc-version-audit.js

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const RELEASE_DOCS = [
+  {
+    file: 'README.md',
+    label: 'README.md',
+    versionField: 'Version',
+    versionPattern: /\*\*Version\*\*:\s*([^\s]+)/,
+    updatedField: 'Last Updated',
+    updatedPattern: /\*\*Last Updated\*\*:\s*(\d{4}-\d{2}-\d{2})/
+  },
+  {
+    file: 'README.zh.md',
+    label: 'README.zh.md',
+    versionField: '版本',
+    versionPattern: /\*\*版本\*\*[：:]\s*([^\s]+)/,
+    updatedField: '最后更新',
+    updatedPattern: /\*\*最后更新\*\*[：:]\s*(\d{4}-\d{2}-\d{2})/
+  },
+  {
+    file: '.sce/README.md',
+    label: '.sce/README.md',
+    versionField: 'sce Version',
+    versionPattern: /\*\*sce Version\*\*:\s*([^\s]+)/,
+    updatedField: 'Last Updated',
+    updatedPattern: /\*\*Last Updated\*\*:\s*(\d{4}-\d{2}-\d{2})/,
+    forbidVersionedHeadings: true
+  },
+  {
+    file: 'template/.sce/README.md',
+    label: 'template/.sce/README.md',
+    versionField: 'sce Version',
+    versionPattern: /\*\*sce Version\*\*:\s*([^\s]+)/,
+    updatedField: 'Last Updated',
+    updatedPattern: /\*\*Last Updated\*\*:\s*(\d{4}-\d{2}-\d{2})/,
+    forbidVersionedHeadings: true
+  }
+];
+
+const VERSIONED_HEADING_PATTERN = /^#{1,6}\s+.*\((?:v)?\d+\.\d+(?:\.\d+|\.x)\)\s*$/gm;
+const CHANGELOG_RELEASE_PATTERN = /^## \[([^\]]+)\] - (\d{4}-\d{2}-\d{2})(?:\s.*)?$/gm;
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const options = {
+    projectPath: process.cwd(),
+    json: false,
+    failOnError: false,
+    out: null
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--json') {
+      options.json = true;
+      continue;
+    }
+    if (value === '--fail-on-error') {
+      options.failOnError = true;
+      continue;
+    }
+    if (value === '--project-path') {
+      options.projectPath = path.resolve(argv[index + 1] || process.cwd());
+      index += 1;
+      continue;
+    }
+    if (value === '--out') {
+      options.out = path.resolve(argv[index + 1] || '');
+      index += 1;
+      continue;
+    }
+  }
+
+  return options;
+}
+
+function pushViolation(violations, file, rule, message, suggestion) {
+  violations.push({
+    severity: 'error',
+    file,
+    rule,
+    message,
+    suggestion
+  });
+}
+
+function loadPackageVersion(projectPath, violations) {
+  const packageJsonPath = path.join(projectPath, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    pushViolation(
+      violations,
+      'package.json',
+      'missing_package_json',
+      'package.json is required to resolve the current release version.',
+      'Restore package.json before running the release doc audit.'
+    );
+    return null;
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  return typeof packageJson.version === 'string' ? packageJson.version.trim() : null;
+}
+
+function extractLatestChangelogRelease(changelogContent) {
+  CHANGELOG_RELEASE_PATTERN.lastIndex = 0;
+  let match = CHANGELOG_RELEASE_PATTERN.exec(changelogContent);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    version: match[1].trim(),
+    date: match[2].trim()
+  };
+}
+
+function loadLatestChangelogRelease(projectPath, packageVersion, violations) {
+  const changelogPath = path.join(projectPath, 'CHANGELOG.md');
+  if (!fs.existsSync(changelogPath)) {
+    pushViolation(
+      violations,
+      'CHANGELOG.md',
+      'missing_changelog',
+      'CHANGELOG.md is required to resolve the latest release date.',
+      'Restore CHANGELOG.md before running the release doc audit.'
+    );
+    return null;
+  }
+
+  const changelogContent = fs.readFileSync(changelogPath, 'utf8');
+  const latestRelease = extractLatestChangelogRelease(changelogContent);
+  if (!latestRelease) {
+    pushViolation(
+      violations,
+      'CHANGELOG.md',
+      'missing_release_entry',
+      'Could not find a released version entry in CHANGELOG.md.',
+      'Add a release entry like `## [x.y.z] - YYYY-MM-DD` before publishing.'
+    );
+    return null;
+  }
+
+  if (packageVersion && latestRelease.version !== packageVersion) {
+    pushViolation(
+      violations,
+      'CHANGELOG.md',
+      'stale_latest_release_entry',
+      `CHANGELOG.md latest release is ${latestRelease.version} but package.json is ${packageVersion}.`,
+      'Update the top released CHANGELOG entry so version and release date match package.json.'
+    );
+  }
+
+  return latestRelease;
+}
+
+function extractField(content, pattern) {
+  const match = content.match(pattern);
+  return match ? match[1].trim() : null;
+}
+
+function collectVersionedHeadings(content) {
+  const matches = [];
+  let match = VERSIONED_HEADING_PATTERN.exec(content);
+  while (match) {
+    matches.push(match[0].trim());
+    match = VERSIONED_HEADING_PATTERN.exec(content);
+  }
+  VERSIONED_HEADING_PATTERN.lastIndex = 0;
+  return matches;
+}
+
+function auditReleaseDocs(options = {}) {
+  const projectPath = path.resolve(options.projectPath || process.cwd());
+  const violations = [];
+  const packageVersion = loadPackageVersion(projectPath, violations);
+  const latestRelease = loadLatestChangelogRelease(projectPath, packageVersion, violations);
+  const expectedVersion = packageVersion;
+  const expectedDate = latestRelease ? latestRelease.date : null;
+  const documents = [];
+
+  for (const doc of RELEASE_DOCS) {
+    const absolutePath = path.join(projectPath, doc.file);
+    if (!fs.existsSync(absolutePath)) {
+      pushViolation(
+        violations,
+        doc.file,
+        'missing_release_doc',
+        `${doc.file} is missing.`,
+        `Restore ${doc.file} so release metadata stays auditable.`
+      );
+      continue;
+    }
+
+    const content = fs.readFileSync(absolutePath, 'utf8');
+    const actualVersion = extractField(content, doc.versionPattern);
+    const actualUpdated = extractField(content, doc.updatedPattern);
+    const versionedHeadings = doc.forbidVersionedHeadings
+      ? collectVersionedHeadings(content)
+      : [];
+
+    if (!actualVersion) {
+      pushViolation(
+        violations,
+        doc.file,
+        'missing_doc_version_field',
+        `${doc.file} is missing the "${doc.versionField}" footer field.`,
+        `Add a "${doc.versionField}" footer line that matches package.json version ${expectedVersion || '<unknown>'}.`
+      );
+    } else if (expectedVersion && actualVersion !== expectedVersion) {
+      pushViolation(
+        violations,
+        doc.file,
+        'stale_doc_version',
+        `${doc.file} tracks version ${actualVersion} but package.json is ${expectedVersion}.`,
+        `Refresh ${doc.file} so "${doc.versionField}" matches ${expectedVersion}.`
+      );
+    }
+
+    if (!actualUpdated) {
+      pushViolation(
+        violations,
+        doc.file,
+        'missing_doc_updated_field',
+        `${doc.file} is missing the "${doc.updatedField}" footer field.`,
+        `Add a "${doc.updatedField}" footer line that matches the latest CHANGELOG release date ${expectedDate || '<unknown>'}.`
+      );
+    } else if (expectedDate && actualUpdated !== expectedDate) {
+      pushViolation(
+        violations,
+        doc.file,
+        'stale_doc_updated_date',
+        `${doc.file} last updated date is ${actualUpdated} but latest CHANGELOG release date is ${expectedDate}.`,
+        `Refresh ${doc.file} so "${doc.updatedField}" matches ${expectedDate}.`
+      );
+    }
+
+    if (versionedHeadings.length > 0) {
+      pushViolation(
+        violations,
+        doc.file,
+        'versioned_capability_headings',
+        `${doc.file} contains version-stamped headings: ${versionedHeadings.join(' | ')}.`,
+        'Remove release/version markers from long-lived README headings and keep current version tracking only in the footer.'
+      );
+    }
+
+    documents.push({
+      file: doc.file,
+      path: absolutePath,
+      actual_version: actualVersion,
+      expected_version: expectedVersion,
+      actual_updated: actualUpdated,
+      expected_updated: expectedDate,
+      versioned_heading_count: versionedHeadings.length
+    });
+  }
+
+  return {
+    mode: 'release-doc-version-audit',
+    passed: violations.length === 0,
+    project_path: projectPath,
+    package_version: packageVersion,
+    changelog_release: latestRelease,
+    error_count: violations.length,
+    documents,
+    violations
+  };
+}
+
+function printHumanReport(result) {
+  if (result.violations.length === 0) {
+    console.log('Release doc version audit passed: README release metadata matches package.json and CHANGELOG.');
+    return;
+  }
+
+  console.error(`Release doc version audit found ${result.error_count} error(s).`);
+  for (const violation of result.violations) {
+    console.error(`- ${violation.file} / ${violation.rule}: ${violation.message}`);
+    if (violation.suggestion) {
+      console.error(`  suggestion: ${violation.suggestion}`);
+    }
+  }
+}
+
+function maybeWriteReport(outputPath, result) {
+  if (!outputPath) {
+    return;
+  }
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+}
+
+if (require.main === module) {
+  const options = parseArgs(process.argv.slice(2));
+  const result = auditReleaseDocs(options);
+  maybeWriteReport(options.out, result);
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    printHumanReport(result);
+  }
+
+  if (options.failOnError && result.error_count > 0) {
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  RELEASE_DOCS,
+  auditReleaseDocs,
+  extractLatestChangelogRelease,
+  parseArgs
+};

package/template/.sce/README.md

@@ -20,7 +20,7 @@ This project uses **Spec-driven development** - a structured approach where:
 
 ---
 
-## 🚀 sce Capabilities (v1.45.x)
+## 🚀 sce Capabilities
 
 **IMPORTANT**: After installing or updating sce, read this section to understand all available capabilities. Using the right tool for the job ensures efficient, high-quality development.
 
@@ -63,7 +63,7 @@ This project uses **Spec-driven development** - a structured approach where:
 - Master Spec + Sub-Specs with dependency management
 - Interface contracts for cross-Spec compatibility
 
-### Multi-Agent Parallel Coordination (v1.43.0)
+### Multi-Agent Parallel Coordination
 When multiple AI agents work on the same project simultaneously:
 - **AgentRegistry** (`lib/collab`) — Agent lifecycle with heartbeat monitoring
 - **TaskLockManager** (`lib/lock`) — File-based task mutual exclusion
@@ -75,7 +75,7 @@ When multiple AI agents work on the same project simultaneously:
 - All components are no-ops in single-agent mode (zero overhead)
 - See `docs/multi-agent-coordination-guide.md` for full API reference
 
-### Spec-Level Steering & Context Sync (v1.44.0)
+### Spec-Level Steering & Context Sync
 Fourth steering layer (L4) and Spec lifecycle coordination for multi-agent scenarios:
 - **SpecSteering** (`lib/steering`) — Per-Spec `steering.md` CRUD with template generation, Markdown ↔ structured object roundtrip
 - **SteeringLoader** (`lib/steering`) — Unified L1-L4 four-layer steering loader with merged output
@@ -92,7 +92,7 @@ Fourth steering layer (L4) and Spec lifecycle coordination for multi-agent scena
 - `sce auto status/resume/stop/config` — Manage autonomous execution
 - Intelligent error recovery, checkpoint system, learning from history
 
-### Agent Orchestrator — Multi-Agent Spec Execution (v1.45.0)
+### Agent Orchestrator — Multi-Agent Spec Execution
 Automate parallel Spec execution via Codex CLI sub-agents (replaces manual multi-terminal workflow):
 - `sce orchestrate run --specs "spec-a,spec-b,spec-c" --max-parallel 3` — Start multi-agent orchestration
 - `sce orchestrate status` — View orchestration progress (per-Spec status, overall state)
@@ -243,6 +243,6 @@ A Spec is a complete feature definition with three parts:
 ---
 
 **Project Type**: Spec-driven development  
-**sce Version**: 1.44.x  
-**Last Updated**: 2026-02-12  
+**sce Version**: 3.6.49  
+**Last Updated**: 2026-03-14  
 **Purpose**: Guide AI tools to work effectively with this project

package/template/.sce/steering/CORE_PRINCIPLES.md

@@ -58,3 +58,11 @@
 - 前端调用后端 API 不匹配时，默认以后端现有接口契约为准。
 - 除非明确要求新建或修改后端接口，否则不要为了迁就前端错误调用去改后端。
 - 优先调整前端请求、映射、类型和兼容处理，使其与后端接口一致。
+
+## 11. 单文件规模过大时必须触发重构评估
+
+- SCE 应先评估当前项目的代码规模分布，再给出项目级的重构参考节点；不要把一个固定阈值生硬套到所有项目。
+- 如果项目还没有自己的阈值，默认参考源文件 `2000 / 4000 / 10000` 行三档触发：分别对应“必须评估”“必须发起重构收敛”“进入红线区”。
+- 达到项目级或默认阈值后，继续加功能前先评估是否应拆分职责；超过重构/红线阈值时，优先做拆分和降复杂度，而不是继续堆代码。
+- 项目早期应更早触发评估，后期也要按周或发布前复评，避免阈值长期失效。
+- 行数阈值只是强触发信号；如果文件虽然没到阈值，但职责混杂、测试困难、理解成本失控，也应提前重构。