depa-codument 0.4.1

package/src/cli/utils/track-time.ts

@@ -0,0 +1,75 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { ARCHIVE_DIR } from './index';
+
+function parseDate(value: string | undefined): Date | null {
+  if (!value) {
+    return null;
+  }
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function readUpdatedAtFromTrack(trackXmlPath: string): Date | null {
+  if (!fs.existsSync(trackXmlPath)) {
+    return null;
+  }
+  const content = fs.readFileSync(trackXmlPath, 'utf-8');
+  const meta = content.match(/<Metadata>([\s\S]*?)<\/Metadata>/)?.[1] ?? content;
+  const updatedAt = meta.match(/<UpdatedAt>([\s\S]*?)<\/UpdatedAt>/)?.[1]?.trim();
+  const createdAt = meta.match(/<CreatedAt>([\s\S]*?)<\/CreatedAt>/)?.[1]?.trim();
+  return parseDate(updatedAt) ?? parseDate(createdAt);
+}
+
+function maxMtimeMs(dir: string): number {
+  if (!fs.existsSync(dir)) {
+    return 0;
+  }
+
+  const stat = fs.statSync(dir);
+  if (stat.isFile()) {
+    return stat.mtimeMs;
+  }
+
+  let max = stat.mtimeMs;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const childPath = path.join(dir, entry.name);
+    const childMax = maxMtimeMs(childPath);
+    if (childMax > max) {
+      max = childMax;
+    }
+  }
+  return max;
+}
+
+export function resolveTrackUpdatedDate(trackDir: string, now = new Date()): Date {
+  const trackDate = readUpdatedAtFromTrack(path.join(trackDir, 'track.xml'));
+  if (trackDate) {
+    return trackDate;
+  }
+
+  const mtime = maxMtimeMs(trackDir);
+  return mtime > 0 ? new Date(mtime) : now;
+}
+
+function pad(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+export function formatLocalMinutePrefix(date: Date): { monthBucket: string; minutePrefix: string } {
+  const year = date.getFullYear();
+  const month = pad(date.getMonth() + 1);
+  const day = pad(date.getDate());
+  const hour = pad(date.getHours());
+  const minute = pad(date.getMinutes());
+  return {
+    monthBucket: `${year}-${month}`,
+    minutePrefix: `${year}-${month}-${day}-${hour}${minute}`,
+  };
+}
+
+export function buildArchiveDestination(trackDir: string, trackId: string, archiveDir = ARCHIVE_DIR): string {
+  const updatedDate = resolveTrackUpdatedDate(trackDir);
+  const prefix = formatLocalMinutePrefix(updatedDate);
+  return path.join(archiveDir, prefix.monthBucket, `${prefix.minutePrefix}-${trackId}`);
+}

package/src/cli/utils/vfs.ts

@@ -0,0 +1,102 @@
+export const CODUMENT_VFS_SCHEMES = [
+  'behavior',
+  'spec',
+  'decision',
+  'memory',
+  'attractor',
+  'track',
+  'archive',
+  'knowledge',
+  'test',
+] as const;
+
+export type CodumentVfsScheme = typeof CODUMENT_VFS_SCHEMES[number];
+
+export interface CodumentVfsUri {
+  raw: string;
+  scheme: CodumentVfsScheme;
+  authority: string;
+  path: string;
+  segments: string[];
+  query: Record<string, string>;
+  fragment?: string;
+}
+
+const SCHEME_SET = new Set<string>(CODUMENT_VFS_SCHEMES);
+
+function parseQuery(rawQuery: string): Record<string, string> {
+  const query: Record<string, string> = {};
+  if (!rawQuery) {
+    return query;
+  }
+
+  for (const part of rawQuery.split('&')) {
+    if (!part) {
+      continue;
+    }
+    const [rawKey, rawValue = ''] = part.split('=');
+    const key = decodeURIComponent(rawKey);
+    query[key] = decodeURIComponent(rawValue);
+  }
+  return query;
+}
+
+export function isCodumentVfsScheme(value: string): value is CodumentVfsScheme {
+  return SCHEME_SET.has(value);
+}
+
+export function parseCodumentVfsUri(input: string): CodumentVfsUri {
+  const match = input.match(/^([a-z][a-z0-9+.-]*):\/\/([^/?#]+)([^?#]*)(?:\?([^#]*))?(?:#(.+))?$/);
+  if (!match) {
+    throw new Error(`Invalid Codument VFS URI: ${input}`);
+  }
+
+  const [, rawScheme, authority, rawPath = '', rawQuery = '', fragment] = match;
+  if (!isCodumentVfsScheme(rawScheme)) {
+    throw new Error(`Unsupported Codument VFS scheme: ${rawScheme}`);
+  }
+
+  const pathPart = rawPath.startsWith('/') ? rawPath.slice(1) : rawPath;
+  const segments = [authority, ...pathPart.split('/').filter(Boolean)].map(decodeURIComponent);
+  if (segments.length === 0 || segments.some((segment) => segment.trim().length === 0)) {
+    throw new Error(`Invalid Codument VFS path: ${input}`);
+  }
+
+  return {
+    raw: input,
+    scheme: rawScheme,
+    authority: decodeURIComponent(authority),
+    path: pathPart,
+    segments,
+    query: parseQuery(rawQuery),
+    fragment: fragment ? decodeURIComponent(fragment) : undefined,
+  };
+}
+
+export function tryParseCodumentVfsUri(input: string): CodumentVfsUri | null {
+  try {
+    return parseCodumentVfsUri(input);
+  } catch {
+    return null;
+  }
+}
+
+export function buildCodumentVfsUri(
+  scheme: CodumentVfsScheme,
+  segments: string[],
+  query?: Record<string, string>,
+): string {
+  if (segments.length === 0) {
+    throw new Error('A Codument VFS URI requires at least one segment.');
+  }
+
+  const [authority, ...rest] = segments.map(encodeURIComponent);
+  const path = rest.length > 0 ? `/${rest.join('/')}` : '';
+  const queryString = query && Object.keys(query).length > 0
+    ? `?${Object.entries(query)
+      .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+      .join('&')}`
+    : '';
+
+  return `${scheme}://${authority}${path}${queryString}`;
+}

package/src/templates/codument/README.md

@@ -0,0 +1,59 @@
+# Codument Workspace
+
+本目录是项目内自包含的 Codument 工作区。它保存项目吸引子、行为登记表、track、内置规程与操作提示词，使 AI 助手可以在项目本地完成 planning、实现、验证、归档和迁移。
+
+Codument 的核心状态文件是 `tracks/<id>/track.xml`。它把一次变更拆成三条正交轴：
+
+| 轴 | 位置 | 作用 |
+|---|---|---|
+| 结构 | `<TaskSpace>` | 记录任务树、阶段、任务状态与验收信息 |
+| 调度 | `<Schedule>` | 记录顺序 / DAG 依赖与并行约束 |
+| 行为 | `<Hooks>` | 记录方向审查、gap-loop、人工确认、制品同步等生命周期动作 |
+
+旧 `plan.xml`、`specs/`、`spec_deltas/` 等路径已迁移到当前标准：`track.xml`、`behaviors/`、`behavior_deltas/`。
+
+## 目录职责
+
+```text
+codument/
+├── std/                         内置标准、规程、操作提示词；upgrade-workspace 会刷新
+│   ├── AGENTS.md                AI 入口与路由
+│   ├── root-agents.md           项目根 AGENTS.md 受管块模板
+│   ├── kernel-pointer.md        Codument 与通用 workflow/task 内核的关系
+│   ├── spec/                    文件格式规范
+│   ├── attractors/              可升级标准 attractor（knowledge/docs/memory/DEPA）
+│   ├── sop/                     内置执行规程
+│   └── operations/              codument-* skill 的权威操作 body
+├── attractors/                  项目、产品等项目自有吸引子
+├── config/                      profile 与 operation hook 配置
+├── workflows/                   结构化 workflow definitions / instances
+├── sop/                         项目自定义执行流程
+├── backlog/                     候选工作与 AI 自主度规则
+├── missions/                    跨多个 track 的 mission / roadmap
+├── memory/                      长期记忆：lessons / incidents / patterns / summaries
+├── behaviors/                   行为登记表，归档时由 behavior_deltas 提升
+└── tracks/                      运行期创建的变更追踪目录
+```
+
+## 当前标准
+
+1. `track.xml` 是 track 状态真源；任务状态在 XML 内维护，不再依赖 `state.json`。
+2. 第一层 `TaskGroup` 表示 phase；其下可继续嵌套 `TaskGroup` 或 `Task`。
+3. 调度按层声明：需要并行的层标 `cdt:child-mode="dag"`，依赖写入 `<Schedule><Dag>`.
+4. `summary` 不手维护；统计由工具遍历 TaskSpace 派生。
+5. 变更输入输出使用目录物料：`behavior_deltas/`、`docs/`、`codument/behaviors/` 等。
+6. 能力开关使用 `config/attractor-profiles.xml` 的 `<Profile enabled>`；不再使用 `config/feature.json`。
+7. 内置规程在 `std/sop/`，项目自定义规程在顶层 `sop/`，结构化 workflow 放在 `workflows/`。
+8. 行为登记表使用 `codument/behaviors/`；行为增量使用 `behavior_deltas/`；selector 使用 `behavior://`。
+9. 跨多个 track 的长期路线放在 `missions/<id>/roadmap.md`；单次变更仍以 `tracks/<id>/track.xml` 为状态真源。
+10. `std/operations/` 是各 `codument-*` skill 的权威提示词 body；agent skill 目录只安装薄壳入口。
+
+## 常用入口
+
+- `std/AGENTS.md`：给 AI 助手的总入口。
+- `std/spec/track-xml-spec.md`：`track.xml` 格式。
+- `std/spec/behavior-delta.md`：行为增量格式。
+- `std/spec/behavior-registry.md`：行为登记表格式。
+- `std/sop/workflow.md`：Codument 工作流总纲。
+- `missions/README.md`：跨 track 路线图写法。
+- `std/operations/README.md`：所有操作提示词索引。

package/src/templates/codument/attractors/product.md

@@ -0,0 +1,17 @@
+# 产品级 Attractor
+
+## 产品愿景
+
+待定义
+
+## 目标用户
+
+- 待定义
+
+## 核心功能
+
+- 待定义
+
+## 成功指标
+
+- 待定义

package/src/templates/codument/attractors/project.md

@@ -0,0 +1,10 @@
+# 项目级 Attractor
+
+---
+
+## 什么是 Attractor
+
+Attractor（吸引子）是系统无论如何变化，都会持续向着其靠拢的方向性力量。不是从 A 到 B 的路径规范，而是在目标和路径周围，持续吸引和引导如何走的力量。
+
+---
+

package/src/templates/codument/backlog/README.md

@@ -0,0 +1,33 @@
+# codument/backlog —— 候选工作清单 + AI 自主度
+
+> 目录职责 · holds: 跨 track 的候选工作项 + 优先级 + AI 自主度标签 · excludes: 需求(→track proposal)、owner 真源(→docs/behaviors)、执行计划(→track.xml) · tier: 活的工作面（就地改、不带日期，非真源） · ⬆from: 用户/复盘提出的下一步 · ⬇to: 选中后开 track
+
+本目录是 codument 对 AGE `docs/backlog/` 的对应物：一份**活的、可变的**"下一步该做什么"清单。它**不替代** track 的 proposal/behavior_deltas（需求）、`docs/`+`behaviors/`（owner 真源）、`track.xml`（执行计划），只用来**选下一个 track**。
+
+## 工作项表
+
+| 优先级 | 工作项 | 关联 behavior/需求 | owner 文档 | track | 状态 | AI 自主度 | 阻塞 | 最后检查 |
+|---|---|---|---|---|---|---|---|---|
+| P0 | `<一句话>` | `behaviors/<cap>` 或 `<待澄清>` | `docs/...` 或 `<无>` | `tracks/<id>` 或 `<未开>` | `needs-track` | `blocked` | `<占位未替换>` | `<YYYY-MM-DD>` |
+
+## AI 自主度（沿用 codument 校验/审查语义）
+
+- `implement` — 已读关联需求/owner 文档/校验命令后可直接开 track 并实现。
+- `plan-first` — 可起草 track.xml，但实现前要过校验（cdt:GapLoop/HumanConfirm）或受保护区批准。
+- `ask-first` — 改代码/用户可见行为前必须先问。
+- `research-only` — 只能调研/总结/提选项，不改产品行为。
+- `blocked` — 阻塞未解前不动。
+
+## ready 不变量（可被选中执行的前提）
+
+`ready` 当且仅当：
+- 关联 behavior/需求已明确、有可测验收（或能在开 track 的澄清里立刻定清）；
+- owner 文档存在且对该 slice 不是已知 stale（见 `knowledge-tiers.md` 新鲜度）；
+- 不触发受保护区（破坏性/数据/权限/外部集成）或已有批准路径；
+- 阻塞为空或显式标注非阻塞。
+
+## 选择规则
+
+用户让"继续"但没点名任务时：选**优先级最高、自主度=`implement`、无阻塞**的工作项开 track。无安全 `implement` 项时，总结最高优先级的 `blocked`/`plan-first`/`ask-first` 项并请用户定夺。AI 可凭证据把 `ready` 降级为 `needs-*`/`blocked`；**不得**在无人确认下把项升为 `ready`、把自主度调成 `implement`、或清除阻塞。
+
+> 本文件是单一可变清单（就地改），不要按日期拆分；跨 track 复发的教训应进 `memory/`，稳定真源应进 `docs/`/`behaviors/`，都不留在这里。

package/src/templates/codument/config/attractor-profiles.xml

@@ -0,0 +1,31 @@
+<!--
+  config/attractor-profiles.xml —— 命名 attractor 组合（XML，vfs 标准）。
+  取代旧 attractor-profiles.json。被 track.xml / operation-hooks.xml 的 <cdt:AttractorCheck use="<name>"/> 按 profile 名引用。
+  每个 <Profile enabled="true|false">（默认 true）。profile 的开关【取代 feature.json 的能力开关】——
+  例如 docs profile 启用 = 开启 docs 知识同步能力；未来不再需要 codument/config/feature.json。
+-->
+<AttractorProfiles version="1">
+
+  <Profile name="coding" enabled="true">
+    <Description>编码方向（DEPA 标准架构吸引子 + 项目工程约束）</Description>
+    <Attractor ref="vfs://@/codument/std/attractors/depa-attractor.md"/>
+    <Attractor ref="vfs://@/codument/attractors/project.md"/>
+  </Profile>
+
+  <!-- 启用即开启 docs 知识同步能力；停用则 docs 相关 hook/同步不触发 -->
+  <Profile name="docs" enabled="true">
+    <Description>docs 知识方向（分层晋升 + 分形规范）</Description>
+    <Attractor ref="vfs://@/codument/std/attractors/knowledge-tiers.md"/>
+    <Attractor ref="vfs://@/codument/std/attractors/model-driven-docs.md"/>
+    <Attractor ref="vfs://@/codument/std/docs-modeling-fractal/index.md"/>
+    <Attractor ref="vfs://@/codument/std/docs-impl-fractal/index.md"/>
+    <Attractor ref="vfs://@/codument/std/spec/folder-manifest.md"/>
+  </Profile>
+
+  <!-- 启用即开启长期项目记忆提升能力（取代旧 feature.json projectMemory.enabled）；停用则归档不提升 memory:// -->
+  <Profile name="memory" enabled="true">
+    <Description>长期记忆方向（lessons/incidents/patterns/summaries）</Description>
+    <Attractor ref="vfs://@/codument/std/attractors/project-memory.md"/>
+  </Profile>
+
+</AttractorProfiles>

package/src/templates/codument/config/engineering.xml

@@ -0,0 +1,22 @@
+<!--
+  config/engineering.xml —— 长期工程知识 registry 能力开关 + merge 策略（XML，vfs 标准；仿 modeling.xml）。
+  默认 disabled：无此文件或 enabled="false" 时，track / implement / archive / lint 全部跳过 engineering，行为不变。
+  启用后：track 产出 engineering_deltas、archive 做节点级 3-way 合并进 codument/engineering/、engineering lint 给分形拆分建议。
+  规范见 codument/std/spec/engineering-registry.md、engineering-delta.md、engineering-node-schema.md。
+-->
+<Engineering version="1" enabled="false">
+
+  <!-- registry 工作树根（宿主 git 版本化；不持久化平行 vcs 仓库） -->
+  <Registry dir="vfs://@/codument/engineering/"/>
+
+  <!-- 分形拆分 lint 阈值（codument engineering lint）；超阈即建议拆同名文件夹 -->
+  <Lint maxLines="400" maxNodes="8"/>
+
+  <!-- 归档 3-way 合并的冲突策略：默认保守（human=报告并暂停，不静默覆盖）；可改 ours|theirs|base -->
+  <MergePolicy>
+    <Conflict type="same-field" resolve="human"/>
+    <Conflict type="delete-modify" resolve="human"/>
+    <Conflict type="add-add" resolve="human"/>
+  </MergePolicy>
+
+</Engineering>

package/src/templates/codument/config/modeling.xml

@@ -0,0 +1,22 @@
+<!--
+  config/modeling.xml —— 领域建模 registry 能力开关 + merge 策略（XML，vfs 标准；仿 attractor-profiles.xml）。
+  默认 disabled：无此文件或 enabled="false" 时，track / implement / archive / lint 全部跳过 modeling，行为不变。
+  启用后：track 产出 modeling_delta、archive 做节点级 3-way 合并进 codument/modeling/、modeling lint 给分形拆分建议。
+  规范见 codument/std/spec/modeling-registry.md、modeling-delta.md、modeling-node-schema.md。
+-->
+<Modeling version="1" enabled="false">
+
+  <!-- registry 工作树根（宿主 git 版本化；不持久化平行 vcs 仓库） -->
+  <Registry dir="vfs://@/codument/modeling/"/>
+
+  <!-- 分形拆分 lint 阈值（codument modeling lint）；超阈即建议拆同名文件夹 -->
+  <Lint maxLines="400" maxNodes="8"/>
+
+  <!-- 归档 3-way 合并的冲突策略：默认保守（human=报告并暂停，不静默覆盖）；可改 ours|theirs|base -->
+  <MergePolicy>
+    <Conflict type="same-field" resolve="human"/>
+    <Conflict type="delete-modify" resolve="human"/>
+    <Conflict type="add-add" resolve="human"/>
+  </MergePolicy>
+
+</Modeling>

package/src/templates/codument/config/operation-hooks.xml

@@ -0,0 +1,55 @@
+<!--
+  config/operation-hooks.xml —— 命令生命周期 hook（无独立 track.xml 的操作）。
+  与 track.xml 的 <Hooks> 同语法（统一 <Hook on>），只是宿主是命令生命周期点而非节点。
+  typed check 用 cdt: 命名空间，配置直接写在节点上：
+    AttractorCheck use="<profile>"（指 config/attractor-profiles.xml 的 profile；fresh-subagent 由 std 提示词约定）
+    ArtifactSync   use="<artifact>"（归档后按 track 的 output MaterialBundle 同步）
+-->
+<OperationHooks version="1" xmlns:cdt="urn:codument:v1">
+
+  <Operation name="plan-track">
+    <Hooks>
+      <Hook on="plan-track:before"><cdt:AttractorCheck use="coding"/></Hook>
+    </Hooks>
+  </Operation>
+
+  <Operation name="plan-mission">
+    <Hooks>
+      <Hook on="plan-mission:before"><cdt:AttractorCheck use="coding"/></Hook>
+    </Hooks>
+  </Operation>
+
+  <Operation name="discuss">
+    <Hooks>
+      <Hook on="discuss:before"><cdt:AttractorCheck use="coding"/></Hook>
+    </Hooks>
+  </Operation>
+
+  <Operation name="impl-quick">
+    <Hooks>
+      <Hook on="impl-quick:before"><cdt:AttractorCheck use="coding"/></Hook>
+    </Hooks>
+  </Operation>
+
+  <Operation name="archive-track">
+    <Hooks>
+      <Hook on="archive-track:after"><cdt:ArtifactSync use="docs"/></Hook>
+    </Hooks>
+  </Operation>
+
+  <Operation name="revise-track">
+    <Hooks>
+      <Hook on="revise-track:before"><cdt:AttractorCheck use="coding"/></Hook>
+    </Hooks>
+  </Operation>
+
+  <Operation name="gap-loop">
+    <!--
+      gap-loop 全局默认：verify-round 控制「首轮 NO_GAP 后是否再追一轮（轻量）验证轮」做首轮怀疑。
+      默认 false（关）。节点 <cdt:GapLoop verify-round="true|false"> 覆盖此全局默认（per-scope）。
+      详见 std/operations/gap-loop.md §0.2.4。
+    -->
+    <cdt:GapLoopDefaults verify-round="false"/>
+  </Operation>
+
+</OperationHooks>

package/src/templates/codument/memory/README.md

@@ -0,0 +1,13 @@
+# codument/memory —— 长期项目记忆
+
+> 目录职责 · holds: 跨 track 的耐久 lessons/incidents/patterns/summaries · excludes: 任务日志(→track reports)、behaviors/docs/源码里的事实、未解决的猜测 · tier: stable·追加（每条目录自包含，无全局 index） · ⬆from: track 复盘提供的候选 · ⬇to: 复发的固化为 sop/skill/check
+
+记忆规则、类别语义、提升判定见吸引子 [std/attractors/project-memory.md](../std/attractors/project-memory.md)；分层与晋升阶梯见 [std/attractors/knowledge-tiers.md](../std/attractors/knowledge-tiers.md)。
+
+## 结构
+
+```text
+memory/<category>/YYYY-MM/YYYY-MM-DD-HHmm-slug/   # category ∈ lessons|incidents|patterns|summaries
+```
+
+每条目录自包含；**不建全局 `index.md`**（跨分支会冲突）。归档时若该 track 无耐久教训，不造条目。仅当 `memory` profile 启用且 track 显式给出候选时才提升（见 `std/operations/archive-track.md`）。

package/src/templates/codument/missions/README.md

@@ -0,0 +1,125 @@
+# codument/missions —— 长周期 mission
+
+> 目录职责 · holds: 跨多个 track 的长周期 mission、mission.xml 状态真源、proposal/design、执行期 evidence/report 外部记忆 · excludes: 单次变更需求(→tracks/<id>/proposal.md)、代码落地状态(→track.xml)、长期 owner 真源(→docs/behaviors/decisions/memory) · tier: 长周期控制面（活层，非行为真源） · from: backlog/用户战略目标/复盘 · to: 多个 tracks
+
+mission 是比 track 跨度更长的任务类型。它用于把战略目标拆成多个 plan 节点和落地 track，并在较长时间内通过控制论反馈循环持续收敛。mission **不替代 track**：真实代码、规范、测试、迁移仍由 track 承担；mission 负责编排、观察、重规划和归档。
+
+## 目录结构
+
+```text
+codument/missions/
+  README.md
+
+  pending/
+    <mission-id>/
+      mission.xml
+      proposal.md
+      design.md
+      decisions.md
+      decisions/
+      memory/
+      analysis/     # 默认不进 git
+      reports/      # 默认不进 git
+
+  active/
+    <mission-id>/
+      mission.xml
+      proposal.md
+      design.md
+      decisions.md
+      decisions/
+      memory/
+      analysis/     # 默认不进 git
+      reports/      # 默认不进 git
+
+  archived/
+    YYYY-MM-DD-<mission-id>/
+      mission.xml
+      proposal.md
+      design.md
+      decisions.md
+      decisions/
+      memory/
+      analysis/
+      reports/
+```
+
+- `pending/`：已规划但未批准 / 未启动。
+- `active/`：正在执行；允许基于 evidence 或 human decision 受控重规划。
+- `archived/`：完成、取消、废弃或被替代后的 mission。归档目录名必须使用 `YYYY-MM-DD-<mission-id>` 前缀。
+
+## 标准制品
+
+新 mission 的标准制品是三件套：
+
+- `mission.xml`：唯一结构 / 状态 / 调度真源。它与 `track.xml` 同构，但根为 `<Mission>`，顶层默认 DAG。顶层 `TaskGroup` 可 DAG 调度；组内 leaf `Task` 默认按 `order` 顺序执行。
+- `proposal.md`：为什么要做、目标 / 非目标、成功判据、为什么这是 mission 而不是单个 track。
+- `design.md`：控制论 + DEPA actor 模型、执行协议、重规划规则、人工介入规则、风险与迁移。
+
+`cdt:TrackLink` 只挂在 leaf `Task` 上，用 `state="candidate|bound"` + `id` 记录推荐或真实 track id；不写 path/archive-path，active/archive 位置从真实 track id 推导。
+
+新 mission **不创建 `roadmap.md`**。旧 roadmap 内容按职责拆分：
+
+| 原路线内容 | 新落点 |
+|---|---|
+| mission 目标、Non-Goals、成功判据 | `proposal.md` |
+| 阶段路线、节点依赖、状态、TrackLink candidate/bound | `mission.xml` |
+| plan vs track 区分规则 | `design.md` |
+| 当前判断、阻塞、风险 | `design.md` + `mission.xml` 状态 |
+| 证据链接、执行报告链接 | `reports/` |
+| 移交项 | `design.md` 或后续 track proposal |
+
+## 控制论 + DEPA actor 执行模型
+
+mission execution is a cybernetic actor loop over a DAG-shaped desired state.
+
+| Actor | 控制论角色 | DEPA 归属 | 职责 |
+|---|---|---|---|
+| `MissionPlanner` | 期望态产出者 | Processor + Actor | 产出或修订 desired mission graph：TaskGroup/Task、依赖、门禁、TrackLink |
+| `MissionObserver` | 传感器 | Data + Actor | 读取 actual state projection：mission.xml、track 状态、archive、测试结果、reports、用户新约束 |
+| `MissionReconciler` | 控制器 | Processor + Actor | 比较 desired vs actual，判定 drift / ready / blocked / done |
+| `MissionApplier` | 执行器 | Effect + Actor | 唯一执行收敛动作：启动 mission、创建/续跑/归档 track、修订 mission.xml、写 reports |
+
+循环协议：
+
+```text
+MissionObserver 观测实际态
+-> MissionReconciler 比较 mission.xml 期望态 vs 实际态
+-> MissionPlanner 在必要时提出重规划
+-> MissionApplier 执行一个 bounded action
+-> 写 report / 更新 mission.xml
+-> 下一轮
+```
+
+纪律：
+
+- **level-triggered**：每轮读取当前实际态，不依赖“上一轮我以为做过什么”。
+- **evidence-based**：重规划必须有 evidence 或 human decision。
+- **idempotent**：同样 desired + actual 不重复创建 track、不重复归档。
+- **bounded action**：每轮只执行一个有限动作，避免长周期自动化漂移。
+- **chat history is not state**：恢复点只来自 `mission.xml`、`analysis/`、`reports/` 和实际 track 状态。
+
+## 受控重规划
+
+active mission 执行中允许：
+
+- 新增节点：发现必须先补证据、先建底座 track、先跑验证。
+- 删除节点：证伪、过时、被合并。
+- 修改节点：目标、验收、依赖、状态变化。
+- 修改 DAG：依赖顺序变化、并行转串行、拆分 wave。
+- 人工介入：用户暂停、改目标、批准 / 拒绝某个 convergence action。
+
+每次重规划必须：
+
+1. 写 `reports/replan-XXX.md` 或 `reports/human-intervention-XXX.md`。
+2. 说明 trigger、actual state、desired state、diff、decision、applied change。
+3. 更新 `mission.xml` 的 `Metadata.Revision` 和 `UpdatedAt`。
+4. 若决策有长期约束，追加到 `decisions.md`，必要时写 `decisions/<slug>.md`。
+
+## 使用规则
+
+- 用 `codument-plan-mission` 创建 pending mission。
+- 用 `codument-impl-mission` 启动或续跑 active mission。
+- 用 `codument-archive-mission` 归档 completed / cancelled / superseded mission。
+- 发现稳定领域知识、承重决策、复用教训时，仍按 `std/attractors/knowledge-tiers.md` 晋升到 owner 层；不要让 mission 成为长期知识垃圾桶。
+- 旧 `missions/<mission-id>/roadmap.md` 形态可以手工迁移为新结构；新规范不要求自动迁移旧 mission。

package/src/templates/codument/sop/README.md

@@ -0,0 +1,14 @@
+# codument/sop/ —— 项目自定义执行流程（项目级，非内置）
+
+本目录放**本项目特有**的执行流程 / 方法论（文字或轻结构化）。它与 `codument/std/sop/`（codument **内置标准** sop：workflow、questioning、validation、tdd、wave-exec、gap-loop、archive、artifact-sync）区分：
+
+- **`std/sop/`** = 随 codument 分发、init 落盘的**内置标准规程**；升级时刷新。
+- **`sop/`（本目录）** = 项目团队自己加的规程（特定领域套路、团队约定流程），不被 codument 升级覆盖。
+
+## 约定
+
+- 两段式可选（「轻量 XML 骨架 + prose」，同 `std/operations/_operation-spec.md` 精神）。
+- 项目自定义 skill / 或对内置 skill 的项目特化，可经 `<protocols><ref>codument/sop/<name>.md</ref>` 引用本目录。
+- 与内置规程同名时，项目可在此覆盖/扩展（由引用方决定优先级）。
+
+> 内置规程不放这里——它们在 `std/sop/`。本目录初始为空（仅本 README）。