speccore 8.3.312 → 8.3.332

package/dist/commands/init.js

@@ -63,6 +63,8 @@ const ask_1 = require("./ask");
 const agents_1 = require("../core/agents");
 // v6.85.0+: RULES 规范库
 const rule_loader_1 = require("../core/rule-loader");
+const task_utils_1 = require("../utils/task-utils");
+const asset_stamp_1 = require("../core/asset-stamp");
 // v6.87.0+: COMMANDS 命令模板
 const command_loader_1 = require("../core/command-loader");
 // v6.88.0+: SKILLS + HOOKS
@@ -367,6 +369,8 @@ async function createDefaultFiles(projectRoot, speccoreDir) {
 ## 字段对照总表
 
 > **AI 必读**：以下表格明确 CONSTITUTION.md 各字段与 PROJECT.yaml 的对应关系，以及每个字段的准确语义。请勿混淆。
+>
+> **事实源（v8.3.322+）**：CLI 命令的机器执行只认 PROJECT.yaml；CONSTITUTION.md 是 AI 阅读契约，仅在 PROJECT.yaml 未声明对应字段时作兼容回退。两处内容需保持语义一致。
 
 ### 项目信息表字段
 
@@ -424,6 +428,8 @@ async function createDefaultFiles(projectRoot, speccoreDir) {
 
 ## 项目信息
 
+> ⚠️ **机器事实源是 \`.speccore/PROJECT.yaml\` 的 \`platforms\`**（v8.3.323+）：源码路径→端的映射（变更检测等）以 platforms[].code_path 为准；本表为 AI 契约与兼容回退，两处需保持一致。
+
 | 工程标识 | 工程类型 | 工程名 | 项目名称 | 项目描述 | 工程源码路径 | 涉及需求端 | 备注 |
 | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
 | ${projectName} | 待填写 | 待填写 | 待填写 | 待填写 | ./ | 待填写 | 待填写 |
@@ -532,32 +538,44 @@ async function createDefaultFiles(projectRoot, speccoreDir) {
 
 ## 技术栈
 
-### 后端
-- 语言：Java / TypeScript / Go / Python
-- 框架：Spring Boot / NestJS / Gin / FastAPI
-- 数据库：MySQL / PostgreSQL / MongoDB
-- 缓存：Redis
+> 填写规则：**每端一行，只写「已选定」的技术与版本**（决策式声明，不是选项菜单）。
+> AI 生成代码时以本表为准；未填写的端回退到端级 TECH.md（analyze 产物）。
+> 可选技术域见本节末尾，仅作约束参考——未出现在上表中的均视为未选用。
+
+| 端 | 语言 | 框架 | 数据存储 | 依据（依赖清单文件） |
+| :--- | :--- | :--- | :--- | :--- |
+| backend-api | Java 17 | Spring Boot 3.x | MySQL 8 | pom.xml |
+| admin-web | TypeScript | Vue 3 | — | package.json |
 
-### 前端
-- 框架：Vue / React / Angular
-- 状态管理：Pinia / Redux / NgRx
-- UI 组件：Element Plus / Ant Design
+> 可选技术域（约束参考，非已选）：
+> - 后端语言：Java / TypeScript / Go / Python；框架：Spring Boot / NestJS / Gin / FastAPI
+> - 前端框架：Vue / React / Angular；状态管理：Pinia / Redux / NgRx；UI 组件：Element Plus / Ant Design
+> - 数据存储：MySQL / PostgreSQL / MongoDB；缓存：Redis
 
 ## 命名规范
 - 接口：/api/v1/{模块}/{操作}
-- 错误码：4 位数字，按模块划分
-- 数据库：snake_case
-- 代码：camelCase / PascalCase
+- 错误码：4 位数字，按「异常码体系」分段划分
+- 数据库：snake_case；代码：camelCase；类/组件：PascalCase
+- 目录：全小写短横线（user-service）；文件名与默认导出组件同名
+- Git 提交：type(scope): subject（feat/fix/docs/refactor/test）
 
 ## 异常码体系
-| 错误码 | 含义 | 场景 |
+
+> 错误码为 4 位数字，按段划分——**分段规则给 AI 的是「生成能力」，不是几个示例**：
+
+| 段 | 范围 | 归属 |
 | :--- | :--- | :--- |
-| 1001 | 用户不存在 | 登录时手机号未注册 |
-| 1002 | 密码错误 | 登录密码不匹配 |
-| ... | ... | ... |
+| 1xxx | 1000-1999 | 用户模块 |
+| 2xxx | 2000-2999 | 订单模块 |
+
+- 首位 = 模块段，后三位 = 段内序号；错误码全项目唯一，跨端共用同一套编号
+- 示例（演示用，按真实模块替换上表）：1001 用户不存在 / 2001 订单不存在
 
 ## Git 分支策略
 
+> ⚠️ **机器事实源是 \`.speccore/PROJECT.yaml\` 的 \`git\` 段**（v8.3.322+）：CLI 命令（分支创建、PR、保护分支拦截）只认 PROJECT.yaml；
+> 本节是 AI 阅读契约，仅在 PROJECT.yaml 未声明对应字段时作为兼容回退。修改策略请改 PROJECT.yaml，并保持本节语义一致。
+
 > 公共默认策略。各工程可在「Git 配置」表中覆盖。
 
 - 默认分支: main（可选: master / develop / trunk）
@@ -568,6 +586,15 @@ async function createDefaultFiles(projectRoot, speccoreDir) {
   - 保护分支上禁止直接 commit 和 push，只能通过 PR 合并
   - 支持精确匹配和通配符（如 release/*）
 `);
+        // v8.3.325: 自动检测技术栈并预填决策式技术栈表（模板刚生成，示例行可整体替换）
+        try {
+            const { enhanceConstitutionTechStack } = require('../core/constitution-builder');
+            await enhanceConstitutionTechStack(projectRoot, {
+                platformName: projectName,
+                freshTemplate: true,
+            });
+        }
+        catch { /* 检测失败不影响 init 主流程 */ }
     } // if CONSTITUTION.md 不存在
     // PROJECT files
     await (0, fs_extra_1.writeFile)((0, path_1.join)(speccoreDir, 'PROJECT', 'INDEX.md'), `# 项目索引
@@ -586,9 +613,18 @@ async function createDefaultFiles(projectRoot, speccoreDir) {
 `);
     await (0, fs_extra_1.writeFile)((0, path_1.join)(speccoreDir, 'PROJECT', 'TEAM.md'), `# 团队与 Git 映射
 
-| 成员 | Git 用户名 | 角色 | 技术栈 | 负责模块 |
-| :--- | :--- | :--- | :--- | :--- |
-| | | | | |
+> **全员名册（全局基座，v8.3.319+）**: 成员在此登记后，所有迭代的 STAFFING.md 自动继承。
+> 各迭代 STAFFING.md 只写差异（同名成员整体覆盖其方向/比例）；本表是团队人员的唯一事实源。
+
+| 成员 | Git 用户名 | 角色 | 技术栈 | 负责模块 | 平台方向 | 投入比例 | 状态 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| | | | | | | | |
+
+> 说明:
+> - **平台方向**: 后台 / 小程序 / Web / APP，多个用逗号分隔（也可直接写标准端名）
+> - **投入比例**: 0-100%（缺省按 100），用于 taskify 时自动分配和负荷均衡
+> - **状态**: 在职（缺省）/ 出项目——出项目成员不参与自动填充（analyze 候选推导、taskify 负荷均衡自动跳过）
+> - 旧版本表（无「平台方向」列）兼容读取：缺此列时全局基座不参与合并，各迭代 STAFFING.md 独立生效
 `);
     // ITERATIONS/README.md
     await (0, fs_extra_1.writeFile)((0, path_1.join)(speccoreDir, 'ITERATIONS', 'README.md'), `# 迭代索引
@@ -656,77 +692,11 @@ async function createDefaultFiles(projectRoot, speccoreDir) {
             },
         },
     }, null, 2));
-    // CODE_REVIEW.md
-    await (0, fs_extra_1.writeFile)((0, path_1.join)(speccoreDir, 'RULES', 'CODE_REVIEW.md'), `# 代码审查规则
-
-## 审查维度
-1. 规范遵循
-2. 代码质量
-3. 测试覆盖
-4. 性能指标
-5. 安全性
-
-## 评分标准
-| 等级 | 分数 | 说明 |
-| :--- | :--- | :--- |
-| A | 90-100 | 优秀 |
-| B | 75-89 | 良好 |
-| C | 60-74 | 合格 |
-| D | <60 | 不合格 |
-`);
-    // POST_COMPLETION.md (Feature 完成后的维护流程)
-    await (0, fs_extra_1.writeFile)((0, path_1.join)(speccoreDir, 'RULES', 'POST_COMPLETION.md'), `# Feature 完成后的维护流程
-
-> 当 Feature 已签署 ✅ 已完成 后，本文件定义其线上运行与维护期的标准流程。
-
-## 1. Feature 状态扩展
-
-| 状态 | 图标 | 含义 | 触发条件 |
-| :--- | :--- | :--- | :--- |
-| 已完成 | ✅ | Spec 与代码完全对齐，已上线 | 开发完成 + 验收通过 |
-| 待反向同步 | ⚠️ | 代码已改但 Spec 未同步 | 紧急补丁后 |
-| 维护中 | 🔄 | 正在回归或功能增强 | 分配维护任务后 |
-| 已废弃 | 🚫 | 功能下线，不再维护 | 业务下线 + 代码移除 |
-
-## 2. 补丁反向同步流程（⚠️ → ✅）
-
-1. AI 读取当前代码，对比 Spec 文件，生成差异报告
-2. 逐项更新：REQ.md、API_CONTRACT.yaml、TASK.md
-3. 更新变更履历
-4. 更新 PROJECT_GRAPH.md 状态
-
-## 3. Bug 修复流程（✅ → 🔄 → ✅）
-
-1. 标记状态为 🔄 维护中
-2. 根因分析 → 追加到 TASK.md「线上问题记录」
-3. 沉淀到 PATTERNS/ 模式库
-4. 回归验证 → 恢复状态到 ✅
-
-## 4. 功能增强流程（✅ → 🔄 → ✅）
-
-1. 标记状态为 🔄 维护中
-2. 在 REQ.md 追加新需求
-3. 更新 API_CONTRACT.yaml
-4. 更新 TASK.md 和 E2E-TEST-SPEC.md
-5. 完成后改回 ✅
-
-## 5. 功能下线流程（✅ → 🚫）
-
-1. 状态改为 🚫 已废弃
-2. PATTERNS/ 标记相关模式为「仅作历史参考」
-3. 代码保留至少一个迭代周期
-4. 最后一个周期后删除代码和 Spec
-
-## 6. 维护检查清单
-
-- [ ] 是否已更新所有受影响的 Spec 文件？
-- [ ] 是否已在变更履历中追加记录？
-- [ ] 是否已更新 PROJECT_GRAPH.md 状态？
-- [ ] 是否已沉淀到 PATTERNS/ 模式库？
-- [ ] 是否已回归 E2E-TEST-SPEC.md 测试场景？
-
-若有任何一项为"否"，不得将状态改回 ✅ 已完成。
-`);
+    // CODE_REVIEW.md / POST_COMPLETION.md（内容由 EXTRA_BUILTIN_RULES 常量统一维护，
+    // 首次 init 无条件写入；update 路径由 initRulesDir 缺失补写）
+    for (const rule of EXTRA_BUILTIN_RULES) {
+        await (0, fs_extra_1.writeFile)((0, path_1.join)(speccoreDir, 'RULES', rule.name), rule.content);
+    }
     // v8.3.41+: 用户自定义分析文档模板说明
     const templatesReadmePath = (0, path_1.join)(speccoreDir, 'templates', 'README.md');
     if (!(await (0, fs_extra_1.pathExists)(templatesReadmePath))) {
@@ -894,76 +864,6 @@ async function createGlobalFiles(speccoreDir) {
 | 缩写 | 全称 | 说明 |
 | :--- | :--- | :--- |
 | _待补充_ | - | - |
-`);
-    // v8.3.307+: TaskChain 内置约束集（.speccore/GLOBAL/CONSTRAINTS/）
-    // 「共同前提约束」的落盘：同类任务每次执行前重新加载，保证上下文不漂移
-    const { BUILTIN_CONSTRAINTS, CUSTOM_TYPES_DIR } = await Promise.resolve().then(() => __importStar(require('../core/task-type-registry')));
-    const constraintsDir = (0, path_1.join)(globalDir, 'CONSTRAINTS');
-    await (0, fs_extra_1.ensureDir)(constraintsDir);
-    for (const [name, content] of Object.entries(BUILTIN_CONSTRAINTS)) {
-        await (0, fs_extra_1.writeFile)((0, path_1.join)(constraintsDir, `${name}.md`), content);
-    }
-    // v8.3.308+: 自定义任务类型目录（开放类型系统引导文档）
-    // 用户在此声明自己的任务类型（如 summary/ppt/translation），非系统定义类型
-    // 默认与代码世界绝缘（不建分支/不写源码），spec 声明 code: true 才切代码形态
-    const customTypesDir = (0, path_1.join)(globalDir, 'TASK_TYPES');
-    await (0, fs_extra_1.ensureDir)(customTypesDir);
-    await (0, fs_extra_1.writeFile)((0, path_1.join)(customTypesDir, 'README.md'), `# 自定义任务类型（v8.3.308+ 开放类型系统）
-
-> 系统内置 8 种类型（feature/bugfix/refactor/research/doc/script/data/presentation）。
-> 本目录声明**用户自定义类型**——写总结、做 PPT、翻译、任何非编程工作都可以是任务。
-
-## 核心规则
-
-**非系统定义的类型，默认与代码世界绝缘**：
-
-- 不创建 git 分支
-- 不写源码路径、不读全局代码上下文
-- 不需要端子目录与技术规格
-- 仅在任务 spec 中**显式声明** \`code: true\`（或「需要写代码: true」）时才切代码形态
-
-## 如何声明一个自定义类型
-
-创建 \`{类型名}.md\`（如 \`summary.md\`），YAML frontmatter 声明定义：
-
-\`\`\`markdown
----
-label: 总结编写
-category: doc
-outputDir: docs/summaries/
-acceptance: 结构含「成果/问题/下一步」+ 数据有来源
-needsBranch: false
-needsPlatforms: false
-needsTechSpec: false
-constraints: [doc-standards]
----
-正文：类型说明（可选）。
-\`\`\`
-
-字段说明：
-
-| 字段 | 默认 | 说明 |
-| :--- | :--- | :--- |
-| label | 类型名 | 中文显示名 |
-| category | custom | 泛化类别（code/doc/research/script/data/custom） |
-| outputDir | outputs/ | 产出目录（相对项目根） |
-| acceptance | 按 spec 验收 | 验收方式描述 |
-| needsBranch | false | 是否创建 git 分支 |
-| needsPlatforms | false | 是否按端拆分子目录 |
-| needsTechSpec | false | 是否需要技术规格 |
-| constraints | [] | 默认约束集（对应 CONSTRAINTS/ 下的文件） |
-
-## 任务 spec 的显式覆盖
-
-任务 spec frontmatter 可覆盖类型默认：
-
-\`\`\`markdown
----
-type: summary
-code: true                # 显式声明要写代码 → 建分支 + 写源码
-constraints: [coding-standards, common-rules]
----
-\`\`\`
 `);
 }
 /**
@@ -1544,6 +1444,22 @@ async function initAgentsDir(projectRoot) {
         if (!(await (0, fs_extra_1.pathExists)(destPath))) {
             await (0, fs_extra_1.writeFile)(destPath, agent.content);
         }
+        else {
+            // v8.3.315+: 版本戳驱动同步 — 内置内容带当前版本戳：
+            //   有旧戳 → 旧版 CLI 生成 → 备份刷新
+            //   无戳且命中旧版特征（「# 角色：」标题、缺 systemPrompt frontmatter）→ 老项目首升级 → 备份刷新
+            //   无戳且无旧版特征 → 用户自定义 → 保留
+            const existing = await (0, fs_extra_1.readFile)(destPath, 'utf-8');
+            // 旧版特征 = 缺 systemPrompt frontmatter 且带「# 角色：」标题（新版无此标题）
+            const decision = (0, asset_stamp_1.decideStampedSync)(existing, agent.content, c => !/^---\s*[\s\S]*?systemPrompt:/m.test(c) && /#\s*角色[：:]\s*\(?/m.test(c));
+            if (decision === 'refresh') {
+                await safeWriteWithBackup(destPath, agent.content);
+                logger_1.logger.info(`   🔄 刷新旧版角色定义: ${agent.name}.md（原文件已备份）`);
+            }
+            else if (decision === 'restamp') {
+                await (0, fs_extra_1.writeFile)(destPath, agent.content);
+            }
+        }
     }
     // 复制注册表（不覆盖用户已自定义的）
     const registryContent = await (0, agents_1.getBuiltinRegistryContent)();
@@ -1552,6 +1468,19 @@ async function initAgentsDir(projectRoot) {
         if (!(await (0, fs_extra_1.pathExists)(registryPath))) {
             await (0, fs_extra_1.writeFile)(registryPath, registryContent);
         }
+        else {
+            // v8.3.315+: 版本戳驱动 + 缺失型旧特征兜底（老项目无戳且缺「叠加 RULES/」列）
+            // 已注册的自定义角色如有丢失可从备份文件恢复。
+            const existing = await (0, fs_extra_1.readFile)(registryPath, 'utf-8');
+            const decision = (0, asset_stamp_1.decideStampedSync)(existing, registryContent, c => !/叠加\s+RULES\//.test(c));
+            if (decision === 'refresh') {
+                await safeWriteWithBackup(registryPath, registryContent);
+                logger_1.logger.info('   🔄 刷新旧版 AGENTS 注册表: _INDEX.md（原文件已备份，自定义角色请从备份合并）');
+            }
+            else if (decision === 'restamp') {
+                await (0, fs_extra_1.writeFile)(registryPath, registryContent);
+            }
+        }
     }
     // 复制模板（不覆盖用户已自定义的）
     const templateContent = await (0, agents_1.getBuiltinTemplateContent)();
@@ -1573,17 +1502,110 @@ const OBSOLETE_MARKERS = [
     { pattern: /speccore\s+split|split\s+-I/, desc: 'split 死命令（v8.3.231+ 应为 taskify）' },
     { pattern: /taskify\s+-I/, desc: 'taskify -I（应为 -i）' },
     { pattern: /CONSTITUTION\.md\s+指定的源码路径(?!\s*\/\s*PROJECT\.yaml)/, desc: '缺少 PROJECT.yaml 引用' },
-    { pattern: /禁止在迭代目录下创建\s+10-backend/, desc: '旧表述：迭代目录（应为 任务目录）' },
+    { pattern: /禁止在迭代目录下创建\s+10-backend/, desc: '旧表述：迭代目录（应为任务目录）' },
+    { pattern: /dev\s+后生成/, desc: '旧流水线表述（dev 已更名 run，v8.3.280+）' },
+    { pattern: /必须开始新对话/, desc: 'SPECCORE_CONTINUE 旧文案（应为优先在同一会话继续）' },
 ];
-function detectObsoleteContent(content) {
+/**
+ * v8.3.46+: 智能过时检测（命中型）
+ * v8.3.314+: 支持 requiredPatterns 缺失型检测 — 新版模板独有的关键内容块，旧版文件缺失即视为过时
+ */
+function detectObsoleteContent(content, requiredPatterns = []) {
     const markers = [];
     for (const marker of OBSOLETE_MARKERS) {
         if (marker.pattern.test(content)) {
             markers.push(marker.desc);
         }
     }
+    for (const pattern of requiredPatterns) {
+        if (!pattern.test(content)) {
+            markers.push('缺少新版关键内容');
+        }
+    }
     return { hasObsolete: markers.length > 0, markers };
 }
+/**
+ * v8.3.314+: 不在 getBuiltinRuleContents 列表内的内置规则。
+ * 首次 init（createDefaultFiles）与 update（initRulesDir）都必须确保其存在，
+ * 否则 AGENTS.md 的引用会出现断链（update 路径此前只补列表内文件）。
+ */
+const EXTRA_BUILTIN_RULES = [
+    {
+        name: 'CODE_REVIEW.md',
+        content: `# 代码审查规则
+
+## 审查维度
+1. 规范遵循
+2. 代码质量
+3. 测试覆盖
+4. 性能指标
+5. 安全性
+
+## 评分标准
+| 等级 | 分数 | 说明 |
+| :--- | :--- | :--- |
+| A | 90-100 | 优秀 |
+| B | 75-89 | 良好 |
+| C | 60-74 | 合格 |
+| D | <60 | 不合格 |
+`,
+    },
+    {
+        name: 'POST_COMPLETION.md',
+        content: `# Feature 完成后的维护流程
+
+> 当 Feature 已签署 ✅ 已完成 后，本文件定义其线上运行与维护期的标准流程。
+
+## 1. Feature 状态扩展
+
+| 状态 | 图标 | 含义 | 触发条件 |
+| :--- | :--- | :--- | :--- |
+| 已完成 | ✅ | Spec 与代码完全对齐，已上线 | 开发完成 + 验收通过 |
+| 待反向同步 | ⚠️ | 代码已改但 Spec 未同步 | 紧急补丁后 |
+| 维护中 | 🔄 | 正在回归或功能增强 | 分配维护任务后 |
+| 已废弃 | 🚫 | 功能下线，不再维护 | 业务下线 + 代码移除 |
+
+## 2. 补丁反向同步流程（⚠️ → ✅）
+
+1. AI 读取当前代码，对比 Spec 文件，生成差异报告
+2. 逐项更新：REQ.md、API_CONTRACT.yaml、TASK.md
+3. 更新变更履历
+4. 更新 PROJECT_GRAPH.md 状态
+
+## 3. Bug 修复流程（✅ → 🔄 → ✅）
+
+1. 标记状态为 🔄 维护中
+2. 根因分析 → 追加到 TASK.md「线上问题记录」
+3. 沉淀到 PATTERNS/ 模式库
+4. 回归验证 → 恢复状态到 ✅
+
+## 4. 功能增强流程（✅ → 🔄 → ✅）
+
+1. 标记状态为 🔄 维护中
+2. 在 REQ.md 追加新需求
+3. 更新 API_CONTRACT.yaml
+4. 更新 TASK.md 和 E2E-TEST-SPEC.md
+5. 完成后改回 ✅
+
+## 5. 功能下线流程（✅ → 🚫）
+
+1. 状态改为 🚫 已废弃
+2. PATTERNS/ 标记相关模式为「仅作历史参考」
+3. 代码保留至少一个迭代周期
+4. 最后一个周期后删除代码和 Spec
+
+## 6. 维护检查清单
+
+- [ ] 是否已更新所有受影响的 Spec 文件？
+- [ ] 是否已在变更履历中追加记录？
+- [ ] 是否已更新 PROJECT_GRAPH.md 状态？
+- [ ] 是否已沉淀到 PATTERNS/ 模式库？
+- [ ] 是否已回归 E2E-TEST-SPEC.md 测试场景？
+
+若有任何一项为"否"，不得将状态改回 ✅ 已完成。
+`,
+    },
+];
 /**
  * v6.85.0+: 初始化 RULES 规范库
  * 将内置默认编码规范复制到 .speccore/RULES/ 目录
@@ -1602,9 +1624,11 @@ async function initRulesDir(projectRoot) {
     }
     // v6.98.0+: 创建 AGENTS.md 投影用的 .inline.md 文件
     // v8.3.46+: 智能过时检测 — 发现已知过时标记时自动覆盖
+    // v8.3.314+: required 缺失型检测 — 新版模板独有内容块缺失时同样覆盖
     const inlineTemplates = [
         {
             name: '01-PROJECT_STRUCTURE.inline.md',
+            required: [/SOURCE\.md/],
             content: `## 项目结构
 
 \`\`\`
@@ -1613,6 +1637,7 @@ Iteration-NNN-name/            ← 迭代目录
 ├── 010-requirements/          ← 需求层
 │   ├── sources/ converted/    ← [只读] 原始 PRD / doc2spec 转换
 │   ├── features/{功能单元}/   ← unitize 切分产出（功能单元目录 = analyze 对齐锚点）
+│   │   └── SOURCE.md          ← 需求原文切片（旧版为 README.md）
 │   ├── bugs/ refactors/ research/  ← 三类需求文档（与任务类型对应）
 │   └── CLARIFY_REPORT.md      ← 澄清报告
 ├── 020-specs/                 ← 需求分析（analyze 输出）
@@ -1682,6 +1707,7 @@ Iteration-NNN-name/            ← 迭代目录
 | \`[SPECCORE_STEP_FAIL: <cmd>]\` | Pipeline 步骤失败 | 提示用户选择重试/跳过/停止 |
 | \`[SPECCORE_AMBIGUOUS: <cmd1> \\| <cmd2>]\` | 意图模糊 | 展示匹配选项让用户选择 |
 | \`[SPECCORE_CONTINUE: <path>]\` | 批次执行完成，需续批 | **优先在同一会话继续**（按标记中的命令执行下一批）；上下文紧张时开新对话，先读取 \`<path>\` 恢复上下文再续批 |`,
+            required: [/SPECCORE_NEEDS_INFO/],
         },
         {
             name: '03-COMMAND_CHEATSHEET.inline.md',
@@ -1708,22 +1734,39 @@ speccore run --demand deploy             # 逃生舱：显式声明是需求（
 speccore analyze -g                      # 快捷糖：等价 speccore global analyze
 speccore unitize prd.md                  # 文件位置参数；doc2spec prd.docx 同理
 speccore verify deploy                   # 测试阶段位置参数（dev/pr/deploy/release）
-\`\`\``
+\`\`\``,
+            required: [/speccore\s+run\s+#/],
         },
     ];
+    // v8.3.314+: 补写 getBuiltinRuleContents 列表之外的内置规则（CODE_REVIEW/POST_COMPLETION）。
+    // update 路径此前只补列表内文件，旧项目缺失这两份时 AGENTS.md 引用断链。
+    for (const rule of EXTRA_BUILTIN_RULES) {
+        const destPath = (0, path_1.join)(rulesDir, rule.name);
+        if (!(await (0, fs_extra_1.pathExists)(destPath))) {
+            await (0, fs_extra_1.writeFile)(destPath, rule.content);
+        }
+    }
     for (const tpl of inlineTemplates) {
         const destPath = (0, path_1.join)(rulesDir, tpl.name);
+        const stampedContent = (0, asset_stamp_1.stampContent)(tpl.content);
         const exists = await (0, fs_extra_1.pathExists)(destPath);
         if (!exists) {
-            await (0, fs_extra_1.writeFile)(destPath, tpl.content);
+            await (0, fs_extra_1.writeFile)(destPath, stampedContent);
         }
-        else if (tpl.name.endsWith('.inline.md')) {
-            // v8.3.46+: 智能过时检测 — 发现已知过时标记时自动覆盖
+        else {
+            // v8.3.315+: 版本戳驱动同步（统一决策表 decideStampedSync）
+            //   有旧戳 → 旧版 CLI 生成 → 备份刷新（不再枚举旧特征，改模板即自动迁移）
+            //   无戳 → 旧特征兜底：过时标记命中 / 缺新版关键内容（required）→ 备份刷新
+            //   同版本戳或用户自定义 → 保留
+            // 覆盖一律 safeWriteWithBackup：旧版特征检测存在误判可能，备份保底可回滚
             const existingContent = await (0, fs_extra_1.readFile)(destPath, 'utf-8');
-            const { hasObsolete, markers } = detectObsoleteContent(existingContent);
-            if (hasObsolete) {
-                logger_1.logger.info(`   🔄 检测到过时内容 [${tpl.name}]: ${markers.join('、')}，已自动更新`);
-                await (0, fs_extra_1.writeFile)(destPath, tpl.content);
+            const decision = (0, asset_stamp_1.decideStampedSync)(existingContent, stampedContent, c => detectObsoleteContent(c, tpl.required).hasObsolete);
+            if (decision === 'refresh') {
+                logger_1.logger.info(`   🔄 检测到旧版内容 [${tpl.name}]，已备份并更新`);
+                await safeWriteWithBackup(destPath, stampedContent);
+            }
+            else if (decision === 'restamp') {
+                await (0, fs_extra_1.writeFile)(destPath, stampedContent);
             }
         }
     }
@@ -1813,12 +1856,12 @@ async function syncAgentsMd(projectRoot, force = false) {
     const agentRows = [];
     if (await (0, fs_extra_1.pathExists)(agentsDir)) {
         const files = (await (0, fs_extra_1.readdir)(agentsDir))
-            .filter(f => f.endsWith('.md') && !f.startsWith('_') && !f.startsWith('.'))
+            .filter(f => f.endsWith('.md') && !f.startsWith('_') && !f.startsWith('.') && !(0, task_utils_1.isTimestampBackup)(f))
             .sort();
         for (const f of files) {
             if (f.endsWith('.inline.md')) {
                 const content = await (0, fs_extra_1.readFile)((0, path_1.join)(agentsDir, f), 'utf-8');
-                agentInlines.push(content.trim());
+                agentInlines.push((0, asset_stamp_1.stripAssetStamp)(content).trim());
             }
             else {
                 const content = await (0, fs_extra_1.readFile)((0, path_1.join)(agentsDir, f), 'utf-8');
@@ -1858,12 +1901,13 @@ async function syncAgentsMd(projectRoot, force = false) {
     const ruleLinks = [];
     if (await (0, fs_extra_1.pathExists)(rulesDir)) {
         const files = (await (0, fs_extra_1.readdir)(rulesDir))
-            .filter(f => f.endsWith('.md') && !f.startsWith('_') && !f.startsWith('.'))
+            .filter(f => f.endsWith('.md') && !f.startsWith('_') && !f.startsWith('.') && !(0, task_utils_1.isTimestampBackup)(f))
             .sort();
         for (const f of files) {
             if (f.endsWith('.inline.md')) {
                 const content = await (0, fs_extra_1.readFile)((0, path_1.join)(rulesDir, f), 'utf-8');
-                ruleInlines.push(content.trim());
+                // v8.3.315+: 剥掉资产版本戳（投影内容不携带 CLI 内部戳）
+                ruleInlines.push((0, asset_stamp_1.stripAssetStamp)(content).trim());
             }
             else {
                 const name = f.replace(/\.md$/, '').replace(/[-_]/g, ' ');
@@ -1906,10 +1950,12 @@ async function createSampleIteration(projectRoot) {
     await (0, fs_extra_1.writeFile)((0, path_1.join)(iterDir, 'STAFFING.md'), [
         '# 示例 人员排期配置',
         '',
-        '| 成员 | 平台方向 | 投入比例 |',
-        '| :--- | :--- | :--- |',
-        '| 张三 | APP, H5 | 80% |',
-        '| 李四 | admin, 小程序 | 70% |',
+        '> 全员基座见 .speccore/PROJECT/TEAM.md（全局名册，自动继承）；本文件只写本迭代差异/覆盖',
+        '',
+        '| 成员 | 平台方向 | 投入比例 | 状态 |',
+        '| :--- | :--- | :--- | :--- |',
+        '| 张三 | APP, H5 | 80% | |',
+        '| 李四 | admin, 小程序 | 70% | |',
         '',
         '> 编辑此文件后重新运行 taskify 即可更新默认分配',
     ].join('\n'));
@@ -2165,7 +2211,7 @@ function generateAIRulesContent() {
         '1. **/spec:ask 是智能路由入口** — 用户说"新建迭代"、"分析需求" → 调用 `speccore ask`，不要自己写 mkdir/analyze',
         '2. **不要跨命令猜测** — 每个斜杠命令只做它描述的事，不要自动级联后续步骤',
         '3. **参数从命令描述获取** — /spec:execute 的描述中有完整的参数说明',
-        '4. **上下文不足时读取文件** — 查看 .speccore/CONSTITUTION.md、STAFFING.md 等',
+        '4. **上下文不足时读取文件** — 查看 .speccore/CONSTITUTION.md、STAFFING.md、.speccore/PROJECT/TEAM.md（全员名册）等',
         '',
         '## 核心流水线',
         '',
@@ -2342,6 +2388,8 @@ examples/
 ├── README.md                    ← 本文件
 ├── config/                      ← 配置文件示例
 │   ├── CONSTITUTION-EXAMPLE.md  ← CONSTITUTION.md 完整示例（多工程）
+│   ├── TEAM-EXAMPLE.md          ← TEAM.md 全员名册示例（7 列，含状态）
+│   ├── STAFFING-EXAMPLE.md      ← STAFFING.md 迭代排期示例（差异覆盖，含状态）
 │   ├── PROJECT-EXAMPLE.yaml     ← PROJECT.yaml 完整示例（多工程）
 │   ├── SPECCORE-YML-EXAMPLE.yml ← .speccore.yml 主配置完整示例（v8.3.296+）
 │   ├── GIT-CONFIG-EXAMPLE.txt   ← 子任务 .meta/git-config 格式示例
@@ -2368,8 +2416,9 @@ examples/
 8. 查看 \`config/DEPLOY-EXAMPLE.yaml\`，了解部署配置格式（用于 \`speccore deploy\`）
 9. 查看 \`config/VERIFY-EXAMPLE.yaml\`，了解测试验证配置格式（用于 \`speccore verify --config\`）
 10. 查看 \`config/SPECCORE-YML-EXAMPLE.yml\`，了解主配置 .speccore.yml 全部字段（质量门禁/冒烟三时机/流水线/AI provider）
-11. 查看 \`ci/github-actions.yml\`，复制到 \`.github/workflows/\` 启用 CI 校验
-12. 修改后运行 \`speccore update\` 自动同步到 PROJECT.yaml
+11. 查看 \`config/TEAM-EXAMPLE.md\` 与 \`config/STAFFING-EXAMPLE.md\`，了解人员配置两级继承（TEAM 全员基座 + STAFFING 迭代差异），「状态」列支持出项目成员免分配
+12. 查看 \`ci/github-actions.yml\`，复制到 \`.github/workflows/\` 启用 CI 校验
+13. 修改后运行 \`speccore update\` 更新配置结构（Git 策略以 \`.speccore/PROJECT.yaml\` 的 \`git\` 段为机器事实源）
 
 ## 注意事项
 
@@ -2381,7 +2430,7 @@ examples/
     const constitutionExample = `## 字段对照总表
 
 > **AI 必读**：以下表格明确 CONSTITUTION.md 各字段与 PROJECT.yaml 的对应关系。
-> 人类只需填写 CONSTITUTION.md，PROJECT.yaml 由 CLI 自动生成/同步。
+> 机器执行以 PROJECT.yaml 为事实源（CLI 只读 PROJECT.yaml）；CONSTITUTION.md 是 AI 阅读契约，仅在 PROJECT.yaml 未声明对应字段时作兼容回退。两处内容需保持语义一致。
 
 ### 项目信息表字段
 
@@ -2433,6 +2482,8 @@ examples/
 
 ## 项目信息
 
+> ⚠️ **机器事实源是 \`.speccore/PROJECT.yaml\` 的 \`platforms\`**（v8.3.323+）：源码路径→端的映射（变更检测等）以 platforms[].code_path 为准；本表为 AI 契约与兼容回退，两处需保持一致。
+
 | 工程标识 | 工程类型 | 工程名 | 项目名称 | 项目描述 | 工程源码路径 | 涉及需求端 | 备注 |
 | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
 | admin-web | Web管理后台 | 后台管理 | 运营后台 | 运营人员使用的后台管理系统 | ./packages/admin | 后台管理端需求文档 | 核心系统 |
@@ -2452,6 +2503,35 @@ examples/
 
 ---
 
+## 技术栈
+
+> 填写规则：**每端一行，只写「已选定」的技术与版本**（决策式声明，不是选项菜单）。
+> AI 生成代码时以本表为准；未填写的端回退到端级 TECH.md（analyze 产物）。
+
+| 端 | 语言 | 框架 | 数据存储 | 依据（依赖清单文件） |
+| :--- | :--- | :--- | :--- | :--- |
+| backend-api | Java 17 | Spring Boot 3.x | MySQL 8 | pom.xml |
+| admin-web | TypeScript | Vue 3 | — | package.json |
+| h5-mobile | TypeScript | Vue 3 | — | package.json |
+| miniapp | JavaScript | 原生小程序 | — | package.json |
+
+> 可选技术域（约束参考，非已选）：后端语言 Java/TypeScript/Go/Python；框架 Spring Boot/NestJS/Gin/FastAPI；前端框架 Vue/React/Angular；数据存储 MySQL/PostgreSQL/MongoDB；缓存 Redis。
+
+## 异常码体系
+
+> 错误码为 4 位数字，按段划分——**分段规则给 AI 的是「生成能力」，不是几个示例**：
+
+| 段 | 范围 | 归属 |
+| :--- | :--- | :--- |
+| 1xxx | 1000-1999 | 用户模块 |
+| 2xxx | 2000-2999 | 订单模块 |
+| 3xxx | 3000-3999 | 支付模块 |
+
+- 首位 = 模块段，后三位 = 段内序号；错误码全项目唯一，跨端共用同一套编号
+- 示例（演示用，按真实模块替换上表）：1001 用户不存在 / 2001 订单不存在 / 3001 支付超时
+
+---
+
 ## Git 公共配置
 
 > 公共默认值。各工程在「Git 配置」表中只写与公共配置不同的字段，未填写的字段自动使用此处默认值。
@@ -2541,10 +2621,46 @@ examples/
 
 > 📌 **使用说明**：
 > 1. 复制本示例内容到 \`CONSTITUTION.md\`，根据实际项目修改
-> 2. 修改后运行 \`speccore update\` 自动同步到 PROJECT.yaml
+> 2. 修改后运行 \`speccore update\` 更新配置结构（Git 策略以 \`.speccore/PROJECT.yaml\` 的 \`git\` 段为机器事实源）
 > 3. 子任务目录下的 \`.meta/git-config\` 可覆盖全局配置（见目录结构说明）
 `;
     await (0, fs_extra_1.writeFile)((0, path_1.join)(configDir, 'CONSTITUTION-EXAMPLE.md'), constitutionExample);
+    // v8.3.324: 人员配置示例（两级继承：TEAM 全员基座 + STAFFING 迭代差异，含「状态」列）
+    const teamExample = `# TEAM.md — 团队与 Git 映射（全员名册，示例）
+
+> **全员名册（全局基座，v8.3.319+）**: 成员在此登记后，所有迭代的 STAFFING.md 自动继承。
+> 各迭代 STAFFING.md 只写差异（同名成员整体覆盖其方向/比例/状态）；本表是团队人员的唯一事实源。
+
+| 成员 | Git 用户名 | 角色 | 技术栈 | 负责模块 | 平台方向 | 投入比例 | 状态 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| 张三 | zhangsan | 后端 | Java/Spring Boot | 订单模块 | backend-api | 100% | 在职 |
+| 李四 | lisi | 前端 | Vue 3 | 商城页面 | admin-web, h5-mobile | 80% | 在职 |
+| 王五 | wangwu | 前端 | 原生小程序 | 小程序 | miniapp | 60% | 在职 |
+| 赵六 | zhaoliu | 后端 | Go | 消息推送 | backend-api | 0% | 出项目 |
+
+> 说明:
+> - **平台方向**: 后台 / 小程序 / Web / APP，多个用逗号分隔（也可直接写标准端名）
+> - **投入比例**: 0-100%（缺省按 100），用于 taskify 时自动分配和负荷均衡
+> - **状态**: 在职（缺省）/ 出项目——出项目成员不参与自动填充（analyze 候选推导、taskify 负荷均衡自动跳过）；迭代层写「在职」可临时复活（如赵六回归某期）
+`;
+    await (0, fs_extra_1.writeFile)((0, path_1.join)(configDir, 'TEAM-EXAMPLE.md'), teamExample);
+    const staffingExample = `# STAFFING.md — 迭代人员排期（差异覆盖层，示例）
+
+> **本文件只写差异**: 与基座 TEAM.md 同名的成员整体覆盖其方向/比例/状态；基座成员未列出的默认参与本迭代。
+> 全员名册见 .speccore/PROJECT/TEAM.md（全局基座，自动继承）。
+
+| 成员 | 平台方向 | 投入比例 | 状态 |
+| :--- | :--- | :--- | :--- |
+| 李四 | admin-web | 100% | 在职 |
+| 赵六 | backend-api | 50% | 在职 |
+
+> 说明:
+> - **平台方向**: 后台 / 小程序 / Web / APP，多个用逗号分隔（也可直接写标准端名）
+> - **投入比例**: 0-100%，用于 taskify 时自动分配和负荷均衡；写 0% 表示本迭代不参与
+> - **状态**: 在职（缺省）/ 出项目——出项目成员不参与自动填充；留空则继承基座状态。示例中赵六基座「出项目」，本迭代写「在职 50%」= 临时回归
+> - 编辑此文件后重新运行 taskify 即可更新默认分配
+`;
+    await (0, fs_extra_1.writeFile)((0, path_1.join)(configDir, 'STAFFING-EXAMPLE.md'), staffingExample);
     // PROJECT.yaml 完整示例（多工程）
     const projectExample = `# PROJECT.yaml — 项目配置（由 CLI 自动生成，不建议手动编辑）
 # 如需修改，请编辑 CONSTITUTION.md 后运行 speccore update