@urland/workspace 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,47 @@
1
+ import path from 'node:path';
2
+ import { parseFrontMatter } from './document.mjs';
3
+
4
+ function stripFrontMatter(text) {
5
+ return text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
6
+ }
7
+
8
+ function normalizeDocumentPathTokens(text) {
9
+ return text
10
+ .replace(/\b(specification|implementation)\/[A-Za-z0-9._/-]+/g, (token) => {
11
+ return `<document-path:${path.extname(token)}>`;
12
+ })
13
+ .replace(/(\]\()index\.(?:md|json)(?=\))/g, '$1<task-index>');
14
+ }
15
+
16
+ export function isPureDocumentPathMigration(previousText, currentText) {
17
+ try {
18
+ const previousMeta = parseFrontMatter(previousText, '基线任务');
19
+ const currentMeta = parseFrontMatter(currentText, '当前任务');
20
+ const comparable = (meta) => {
21
+ const copy = { ...meta };
22
+ delete copy.specification;
23
+ delete copy.implementation;
24
+ return JSON.stringify(copy);
25
+ };
26
+ return comparable(previousMeta) === comparable(currentMeta)
27
+ && normalizeDocumentPathTokens(stripFrontMatter(previousText))
28
+ === normalizeDocumentPathTokens(stripFrontMatter(currentText));
29
+ } catch {
30
+ return false;
31
+ }
32
+ }
33
+
34
+ export function isDocumentTreeRestructure(changed) {
35
+ const movedFromImplementation = [...changed].some((file) =>
36
+ /^implementation\/(?:data-model|domains|standards|backend|protocols)\//.test(file));
37
+ const movedToSpecification = [...changed].some((file) =>
38
+ /^specification\/(?:data-model|domain|standards)\//.test(file));
39
+ const taskIndexMigration = [...changed].some((file) =>
40
+ /^tasks\/(?:index|active\/index|drafts\/index|archive\/index|archive\/\d{4}-\d{2}\/index)\.(?:md|json)$/.test(file));
41
+ return (movedFromImplementation && movedToSpecification) || taskIndexMigration;
42
+ }
43
+
44
+ export function allowsHistoricalPathMigration({ documentTreeRestructure, isArchived, baseTask, status, previousText, currentText }) {
45
+ return Boolean(documentTreeRestructure && isArchived && baseTask
46
+ && baseTask.meta.status === status && isPureDocumentPathMigration(previousText, currentText));
47
+ }
@@ -0,0 +1,30 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { readIndexJson } from './index-schema.mjs';
4
+
5
+ export function checkPromotions(root, documents, baseline, fail) {
6
+ const { changed, draftFiles, activeDocuments } = baseline;
7
+ const draftsIndex = path.join(root, 'tasks/drafts/index.json');
8
+ const draftsIndexData = fs.existsSync(draftsIndex)
9
+ ? readIndexJson(draftsIndex, 'tasks-drafts-index', fail)
10
+ : undefined;
11
+ const draftReferences = (text) => new Set([...text.matchAll(/\bdraft-[a-z0-9-]+\.md\b/g)].map((match) => match[0]));
12
+ for (const { relative, text } of documents) {
13
+ if (!relative.startsWith('tasks/active/')) continue;
14
+ const existingText = activeDocuments.get(relative);
15
+ if (existingText !== undefined && !changed.has(relative)) continue;
16
+ const currentReferences = draftReferences(text);
17
+ for (const reference of draftReferences(existingText ?? '')) currentReferences.delete(reference);
18
+ for (const reference of currentReferences) {
19
+ const draftPath = `tasks/drafts/${reference}`;
20
+ if (!draftFiles.has(draftPath)) fail(`${relative}:来源草稿 ${draftPath} 不存在于基线,不能作为草稿转正来源`);
21
+ if (!changed.has(draftPath) || fs.existsSync(path.join(root, draftPath))) {
22
+ fail(`${relative}:正式任务引用来源草稿时,必须在同一变更中删除来源草稿 ${draftPath}`);
23
+ }
24
+ const stillListed = draftsIndexData?.entries?.some((draft) => draft.file === reference);
25
+ if (!changed.has('tasks/drafts/index.json') || stillListed) {
26
+ fail(`${relative}:正式任务引用来源草稿时,必须在同一变更中移除草稿索引登记 ${reference}`);
27
+ }
28
+ }
29
+ }
30
+ }
@@ -0,0 +1,142 @@
1
+ import path from 'node:path';
2
+ import { terminalStatusSet, activeStatusSet, parseLegacyName, documentSections } from './document.mjs';
3
+ import { allowsHistoricalPathMigration as historicalPathMigrationAllowed } from './migration.mjs';
4
+
5
+ function hasEvidenceSection(text) {
6
+ const heading = /^## .*?(?:验收证据|验证证据|当前证据|运行证据|收口证据)[^\n]*$/m.exec(text);
7
+ if (!heading) return false;
8
+ const section = text.slice(heading.index + heading[0].length).split(/^## /m, 1)[0];
9
+ return /\S/.test(section);
10
+ }
11
+ function statusTransitionAllowed(from, to) {
12
+ if (from === to) return true;
13
+ if (terminalStatusSet.has(from)) return false;
14
+ if (to === '已完成') return from === '待验收';
15
+ if (to === '已阻塞' || to === '待裁定') return activeStatusSet.has(from);
16
+ if (to === '已关闭' || to === '已合并' || to === '已取消') return activeStatusSet.has(from);
17
+ if (from === '已阻塞') return ['进行中', '待验收', '待裁定'].includes(to);
18
+ if (from === '待裁定') return ['待开始', '进行中', '已阻塞'].includes(to);
19
+ if (from === '待开始') return ['进行中', '实施中'].includes(to);
20
+ if (from === '进行中') return ['实施中', '待验收'].includes(to);
21
+ if (from === '实施中') return ['待验收', '已阻塞', '待裁定'].includes(to);
22
+ if (from === '待验收') return ['进行中', '实施中', '已阻塞', '待裁定'].includes(to);
23
+ return false;
24
+ }
25
+
26
+ function checkStartSpecification(current, changed, fail) {
27
+ const paths = current.meta.specification;
28
+ // 主任务校验统一报告字段类型和规范影响评估,这里只检查 Git 差异。
29
+ if (!Array.isArray(paths)) return;
30
+ const missing = paths.filter((file) => !changed.has(file));
31
+ if (missing.length) fail(`${current.relative}: 进入进行中前声明的 specification 文件未更新:${missing.join('、')}`);
32
+ }
33
+
34
+ export function checkTransitions(tasks, baseline, fail) {
35
+ const { baseTasks, documentTreeRestructure } = baseline;
36
+ const currentById = new Map(tasks.map((task) => [task.meta.id, task]));
37
+ for (const [id, current] of currentById) {
38
+ const previous = baseTasks.get(id);
39
+ const changed = previous?.closeChanges ?? baseline.changed;
40
+ if (!previous) {
41
+ if (!['待开始', '进行中'].includes(current.meta.status)) {
42
+ fail(`${current.relative}: 新建正式任务只能从 待开始 或 进行中 开始,当前为 ${current.meta.status}`);
43
+ continue;
44
+ }
45
+ if (!changed.has('tasks/active/index.json')) fail(`${current.relative}: 新建活动任务必须同步 tasks/active/index.json`);
46
+ if (current.meta.status === '进行中') checkStartSpecification(current, changed, fail);
47
+ continue;
48
+ }
49
+ const from = previous.meta.status;
50
+ const to = current.meta.status;
51
+ const previousExtensions = Array.isArray(previous.meta.extensions) ? previous.meta.extensions : [];
52
+ if (terminalStatusSet.has(from) && previous.file === current.relative) {
53
+ for (const name of previousExtensions) {
54
+ if (typeof name !== 'string') continue;
55
+ const extension = path.posix.join(path.posix.dirname(previous.file), name);
56
+ if (changed.has(extension)) fail(`${extension}: 已归档的扩展必须保留历史记录`);
57
+ }
58
+ }
59
+ const taskChanged = changed.has(current.relative) || changed.has(previous.file);
60
+ if (from === to && !taskChanged) continue;
61
+ const structuralArchiveMigration = current.relative.startsWith('tasks/archive/')
62
+ && previous.file.startsWith('tasks/')
63
+ && !previous.file.startsWith('tasks/active/')
64
+ && parseLegacyName(path.basename(previous.file))
65
+ && from === '进行中'
66
+ && to === '已完成'
67
+ && hasEvidenceSection(current.text);
68
+ if (!statusTransitionAllowed(from, to) && !structuralArchiveMigration) {
69
+ fail(`${current.relative}: 非法状态迁移 ${from} → ${to}`);
70
+ continue;
71
+ }
72
+ if (from === to) {
73
+ const relocated = current.relative.startsWith('tasks/archive/')
74
+ && terminalStatusSet.has(to)
75
+ && previous.file !== current.relative
76
+ && (parseLegacyName(path.basename(previous.file)) || previous.file.startsWith('archived-tasks/'));
77
+ const allowsHistoricalPathMigration = historicalPathMigrationAllowed({
78
+ documentTreeRestructure, isArchived: current.relative.startsWith('tasks/archive/'),
79
+ baseTask: previous, status: to, previousText: previous.text, currentText: current.text,
80
+ });
81
+ if (terminalStatusSet.has(to) && !hasEvidenceSection(current.text)) fail(`${current.relative}: 终态任务必须保留真实验收证据`);
82
+ if (terminalStatusSet.has(to) && !relocated && !allowsHistoricalPathMigration && changed.has(current.relative)) fail(`${current.relative}: 终态任务不能原地修改;请创建新的正式任务编号`);
83
+ if (relocated || allowsHistoricalPathMigration) {
84
+ for (const key of documentSections) {
85
+ for (const target of Array.isArray(current.meta[key]) ? current.meta[key] : []) if (!changed.has(target) && !allowsHistoricalPathMigration) fail(`${current.relative}: 归档迁移未同步 ${key} 文件 ${target}`);
86
+ }
87
+ if (relocated) {
88
+ for (const required of ['tasks/active/index.json', 'tasks/archive/index.json', `tasks/archive/${current.meta.updated?.slice(0, 7)}/index.json`]) {
89
+ if (!changed.has(required)) fail(`${current.relative}: 归档迁移必须同步 ${required}`);
90
+ }
91
+ }
92
+ }
93
+ continue;
94
+ }
95
+ if (!changed.has(current.relative) && !changed.has(previous.file)) fail(`${current.relative}: 状态迁移 ${from} → ${to} 未修改任务文件`);
96
+ if (!changed.has('tasks/active/index.json') && !terminalStatusSet.has(to)) fail(`${current.relative}: 活动状态迁移 ${from} → ${to} 必须同步 tasks/active/index.json`);
97
+ if (to === '进行中') checkStartSpecification(current, changed, fail);
98
+ if (to === '待验收' && !hasEvidenceSection(current.text)) {
99
+ fail(`${current.relative}: 进入待验收前必须记录实际命令、运行环境或待核对证据`);
100
+ }
101
+ if (from === '已阻塞' && ['进行中', '待验收'].includes(to) && !/解除证据|恢复证据|恢复条件已满足/.test(current.text)) {
102
+ fail(`${current.relative}: 从已阻塞恢复前必须记录解除证据`);
103
+ }
104
+ if (from === '待裁定' && ['待开始', '进行中'].includes(to) && !/裁定结论|决策结论|决策记录/.test(current.text)) {
105
+ fail(`${current.relative}: 从待裁定恢复前必须记录裁定或决策结论`);
106
+ }
107
+ if (to === '已完成' && !hasEvidenceSection(current.text)) fail(`${current.relative}: 进入已完成前必须记录真实验收证据`);
108
+ if (to === '已阻塞') {
109
+ for (const phrase of ['阻塞原因', '影响范围', '责任人', '恢复条件', '下一检查点']) {
110
+ if (!current.text.includes(phrase)) fail(`${current.relative}: 进入已阻塞必须记录${phrase}`);
111
+ }
112
+ }
113
+ if (to === '待裁定') {
114
+ for (const phrase of ['冲突口径', '决策人', '期限', '影响']) {
115
+ if (!current.text.includes(phrase)) fail(`${current.relative}: 进入待裁定必须记录${phrase}`);
116
+ }
117
+ }
118
+ if (to === '已取消' && !/取消原因/.test(current.text)) fail(`${current.relative}: 进入已取消必须记录取消原因`);
119
+ if (to === '已取消' && !/替代任务|替代范围|不再推进/.test(current.text)) fail(`${current.relative}: 进入已取消必须记录替代任务、替代范围或不再推进`);
120
+ if (to === '已关闭' && !/关闭原因/.test(current.text)) fail(`${current.relative}: 进入已关闭必须记录关闭原因`);
121
+ if (to === '已合并' && !/合并提交|合并结果/.test(current.text)) fail(`${current.relative}: 进入已合并必须记录合并提交或合并结果`);
122
+ if (terminalStatusSet.has(to)) {
123
+ const extensions = Array.isArray(current.meta.extensions) ? current.meta.extensions : [];
124
+ for (const name of previousExtensions) {
125
+ if (!extensions.includes(name)) fail(`${current.relative}: 归档时必须保留扩展 ${name}`);
126
+ }
127
+ for (const required of ['tasks/active/index.json', 'tasks/archive/index.json']) {
128
+ if (!changed.has(required)) fail(`${current.relative}: 进入终态必须同步 ${required}`);
129
+ }
130
+ const monthIndex = `tasks/archive/${current.meta.updated?.slice(0, 7)}/index.json`;
131
+ if (!changed.has(monthIndex)) fail(`${current.relative}: 进入终态必须同步月份索引 ${monthIndex}`);
132
+ }
133
+ }
134
+ for (const [id, previous] of baseTasks) {
135
+ if (currentById.has(id)) continue;
136
+ if (terminalStatusSet.has(previous.meta.status)) {
137
+ fail(`${previous.file}: 终态任务必须保留归档记录`);
138
+ } else {
139
+ fail(`${previous.file}: 活动任务从当前树消失,必须迁移到归档或保留在 active/`);
140
+ }
141
+ }
142
+ }
@@ -0,0 +1,8 @@
1
+ # 工作空间规则
2
+
3
+ 使用简体中文沟通和编写项目说明。缺少工具时按官方推荐方式安装。路径以工作空间根目录为基准。
4
+
5
+ - 子项目继承本文件。先读目标项目的规则,再按公司索引加载通用规则、工作空间规则以及匹配的技术栈和工作流。涉及 Git 时加载 Git 规则。[公司规则索引](https://agent-rules.topode.com/index.yaml)
6
+ - 根仓库跟踪工作空间说明、共享配置和内置开发文档。业务代码提交到所属子仓库。新增独立仓库时更新仓库清单和忽略规则。[仓库清单](README.md#独立仓库)
7
+ - 保留其他协作者的未提交改动。使用隔离检出前在所属仓库运行 `git worktree list` 核对分支与路径。
8
+ - 需求草稿和立项须由用户确认。验收通过后同步实现事实。收到完成指令时如仍需补证据,补齐后再次获得授权方可归档。[开发文档](dev-docs/index.md)
@@ -0,0 +1,19 @@
1
+ # 开发工作空间
2
+
3
+ [工作空间规则](AGENTS.md) · [开发文档](dev-docs/index.md)
4
+
5
+ ## 初始化与日常使用
6
+
7
+ 新建工作空间时,在目标目录运行 `npx @urland/workspace init`,再执行 `npm install` 生成锁文件。克隆已有工作空间后运行 `npm ci`。在根目录用 `npm run check:tasks` 检查任务和索引。[任务检查](dev-docs/index.md#任务检查)
8
+
9
+ ## 独立仓库
10
+
11
+ 按需克隆子项目,在下表填写实际信息,并将各检出目录加入根 `.gitignore`。内置的 `dev-docs/` 由根仓库跟踪。
12
+
13
+ | 目录与入口 | 职责 | 克隆地址 | 默认分支 |
14
+ | --- | --- | --- | --- |
15
+
16
+ ## 本地目录
17
+
18
+ - `storage/` 保存运行产物。
19
+ - `worktrees/` 保存独立仓库的隔离检出。
@@ -0,0 +1,3 @@
1
+ # 已确认事实
2
+
3
+ 在任务验收收口时登记事实和证据入口,注明验证的版本和范围。[返回当前实现](../index.md)
@@ -0,0 +1,3 @@
1
+ # 当前实现
2
+
3
+ 按项目或领域登记可复核的代码、数据库和运行证据。分别说明实现程度和实测范围。[已确认事实](facts/index.md) · [返回开发文档](../index.md)
@@ -0,0 +1,13 @@
1
+ # 开发文档
2
+
3
+ 从[系统规范](specification/index.md)确认目标,查阅[当前实现](implementation/index.md)与[已确认事实](implementation/facts/index.md),再从[任务索引](tasks/index.json)进入当前任务。
4
+
5
+ ## 统一工作流
6
+
7
+ 用户确认后建立需求草稿或直接立项。草稿使用 `tasks/drafts/draft-<slug>.md`。转正时将来源文件名记入正式任务,同步移除草稿及其索引登记。正式任务使用 `tasks/active/task-N-main-<slug>.md`,同步主任务元数据、正文状态、连续的 P 项和活动索引。
8
+
9
+ 在实现前评估规范影响。验收通过后再更新已确认的实现事实,将终态任务和扩展文档按更新月份归档。具体授权要求、状态与索引字段见公司索引中的 `workflow.dev-docs`。[公司规则索引](https://agent-rules.topode.com/index.yaml)
10
+
11
+ ## 任务检查
12
+
13
+ 在工作空间根目录执行 `npm run check:tasks`,由 `workspace check` 检查草稿、正式任务、扩展、进度及索引。审查草稿转正、状态迁移和归档时,使用 `npm run check:tasks -- --base <变更前提交>`。命令返回非零时,根据输出的文件路径修正记录并再次检查。[工作空间使用说明](../README.md)
@@ -0,0 +1,3 @@
1
+ # 系统规范
2
+
3
+ 按领域登记业务语义、状态、权限、接口契约和验收约束。新增领域时在本入口链接其目录。[返回开发文档](../index.md)
@@ -0,0 +1,10 @@
1
+ {
2
+ "kind": "tasks-active-index",
3
+ "version": 1,
4
+ "description": "当前活动任务。",
5
+ "notes": [],
6
+ "scope": {
7
+ "next_task_number": 1
8
+ },
9
+ "entries": []
10
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "kind": "tasks-archive-index",
3
+ "version": 1,
4
+ "description": "按更新月份登记终态任务。",
5
+ "notes": [],
6
+ "entries": []
7
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "kind": "tasks-drafts-index",
3
+ "version": 1,
4
+ "description": "尚未立项的需求草稿。",
5
+ "notes": [],
6
+ "entries": []
7
+ }
@@ -0,0 +1,23 @@
1
+ {
2
+ "kind": "tasks-root-index",
3
+ "version": 1,
4
+ "description": "任务生命周期入口,汇总需求草稿、活动任务和历史归档。",
5
+ "notes": [],
6
+ "entries": [
7
+ {
8
+ "name": "active",
9
+ "title": "活动任务",
10
+ "file": "active/index.json"
11
+ },
12
+ {
13
+ "name": "drafts",
14
+ "title": "需求草稿",
15
+ "file": "drafts/index.json"
16
+ },
17
+ {
18
+ "name": "archive",
19
+ "title": "历史归档",
20
+ "file": "archive/index.json"
21
+ }
22
+ ]
23
+ }
@@ -0,0 +1 @@
1
+ /node_modules/
@@ -0,0 +1,2 @@
1
+ /*
2
+ !/.gitignore
@@ -0,0 +1,2 @@
1
+ /*
2
+ !/.gitignore