trigrams-toolkit 0.1.0__py3-none-any.whl

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.
Files changed (103) hide show
  1. trigrams_toolkit/__init__.py +1 -0
  2. trigrams_toolkit/handbook/__init__.py +6 -0
  3. trigrams_toolkit/handbook/cli.py +122 -0
  4. trigrams_toolkit/handbook/guide_headers.py +43 -0
  5. trigrams_toolkit/handbook/guides.py +141 -0
  6. trigrams_toolkit/handbook/location.py +79 -0
  7. trigrams_toolkit/handbook/model.py +4 -0
  8. trigrams_toolkit/handbook/package.py +165 -0
  9. trigrams_toolkit/handbook/principle_import.py +101 -0
  10. trigrams_toolkit/handbook/project_resources.py +80 -0
  11. trigrams_toolkit/handbook/skill_sources.py +59 -0
  12. trigrams_toolkit/handbook/source_catalog.py +55 -0
  13. trigrams_toolkit/handbook/sources.py +16 -0
  14. trigrams_toolkit/installation/__init__.py +0 -0
  15. trigrams_toolkit/installation/archive_project.py +50 -0
  16. trigrams_toolkit/installation/global_skills.py +45 -0
  17. trigrams_toolkit/installation/harness_install.py +89 -0
  18. trigrams_toolkit/installation/installation_candidate.py +135 -0
  19. trigrams_toolkit/installation/installation_help.py +49 -0
  20. trigrams_toolkit/installation/installation_materials.py +73 -0
  21. trigrams_toolkit/installation/installation_service.py +14 -0
  22. trigrams_toolkit/installation/installation_sources.py +34 -0
  23. trigrams_toolkit/installation/operation_files.py +94 -0
  24. trigrams_toolkit/installation/operation_runtime.py +144 -0
  25. trigrams_toolkit/installation/package_metadata.py +48 -0
  26. trigrams_toolkit/plan/__init__.py +5 -0
  27. trigrams_toolkit/plan/cli.py +136 -0
  28. trigrams_toolkit/plan/definitions.py +131 -0
  29. trigrams_toolkit/plan/model.py +61 -0
  30. trigrams_toolkit/plan/scheduling.py +126 -0
  31. trigrams_toolkit/plan/service.py +139 -0
  32. trigrams_toolkit/plan/state.py +146 -0
  33. trigrams_toolkit/project_context/__init__.py +16 -0
  34. trigrams_toolkit/project_context/paths.py +36 -0
  35. trigrams_toolkit/py.typed +0 -0
  36. trigrams_toolkit/resources/__init__.py +35 -0
  37. trigrams_toolkit/resources/adapters/claude/README.md +7 -0
  38. trigrams_toolkit/resources/adapters/claude/evaluator.md +7 -0
  39. trigrams_toolkit/resources/adapters/claude/task_developer.md +7 -0
  40. trigrams_toolkit/resources/adapters/codex/README.md +9 -0
  41. trigrams_toolkit/resources/adapters/codex/evaluator.toml +6 -0
  42. trigrams_toolkit/resources/adapters/codex/task_developer.toml +6 -0
  43. trigrams_toolkit/resources/adapters/pi-web/evaluator.md +7 -0
  44. trigrams_toolkit/resources/adapters/pi-web/task_developer.md +7 -0
  45. trigrams_toolkit/resources/handbook/PROTOCOL.md +82 -0
  46. trigrams_toolkit/resources/handbook/README.md +45 -0
  47. trigrams_toolkit/resources/handbook/commands.json +31 -0
  48. trigrams_toolkit/resources/handbook/guides.schema.json +253 -0
  49. trigrams_toolkit/resources/installation/PROTOCOL.md +35 -0
  50. trigrams_toolkit/resources/installation/cli.schema.json +89 -0
  51. trigrams_toolkit/resources/installation/commands.json +23 -0
  52. trigrams_toolkit/resources/installation/examples/install-apply-input.json +48 -0
  53. trigrams_toolkit/resources/installation/examples/install-preview-input.json +7 -0
  54. trigrams_toolkit/resources/installation/examples/installation.json +20 -0
  55. trigrams_toolkit/resources/installation/global-skills.json +6 -0
  56. trigrams_toolkit/resources/installation/installation.schema.json +295 -0
  57. trigrams_toolkit/resources/plan/PROTOCOL.md +89 -0
  58. trigrams_toolkit/resources/plan/README.md +61 -0
  59. trigrams_toolkit/resources/plan/commands.json +36 -0
  60. trigrams_toolkit/resources/plan/plan.schema.json +192 -0
  61. trigrams_toolkit/resources/shared/GLOBAL-TOOLS.md +31 -0
  62. trigrams_toolkit/resources/shared/common.schema.json +234 -0
  63. trigrams_toolkit/resources/state/PROTOCOL.md +85 -0
  64. trigrams_toolkit/resources/state/README.md +88 -0
  65. trigrams_toolkit/resources/state/cli.schema.json +326 -0
  66. trigrams_toolkit/resources/state/commands.json +55 -0
  67. trigrams_toolkit/resources/state/core-types.json +5 -0
  68. trigrams_toolkit/resources/state/help.json +86 -0
  69. trigrams_toolkit/resources/state/sources.schema.json +89 -0
  70. trigrams_toolkit/resources/state/state.schema.json +200 -0
  71. trigrams_toolkit/shared/__init__.py +1 -0
  72. trigrams_toolkit/shared/cli_help.py +195 -0
  73. trigrams_toolkit/shared/errors.py +29 -0
  74. trigrams_toolkit/shared/files.py +66 -0
  75. trigrams_toolkit/shared/locking.py +49 -0
  76. trigrams_toolkit/shared/paths.py +89 -0
  77. trigrams_toolkit/shared/process_lock.py +77 -0
  78. trigrams_toolkit/shared/schema.py +60 -0
  79. trigrams_toolkit/shared/serialization.py +84 -0
  80. trigrams_toolkit/shared/skill_installations.py +66 -0
  81. trigrams_toolkit/shared/state_json.py +45 -0
  82. trigrams_toolkit/state/__init__.py +4 -0
  83. trigrams_toolkit/state/arguments.py +68 -0
  84. trigrams_toolkit/state/cli.py +37 -0
  85. trigrams_toolkit/state/frontmatter.py +176 -0
  86. trigrams_toolkit/state/help.py +25 -0
  87. trigrams_toolkit/state/identity.py +123 -0
  88. trigrams_toolkit/state/location.py +59 -0
  89. trigrams_toolkit/state/model.py +76 -0
  90. trigrams_toolkit/state/providers.py +77 -0
  91. trigrams_toolkit/state/registration.py +82 -0
  92. trigrams_toolkit/state/relations.py +105 -0
  93. trigrams_toolkit/state/service.py +90 -0
  94. trigrams_toolkit/state/store.py +33 -0
  95. trigrams_toolkit/state/views.py +64 -0
  96. trigrams_toolkit/version.py +6 -0
  97. trigrams_toolkit-0.1.0.dist-info/METADATA +69 -0
  98. trigrams_toolkit-0.1.0.dist-info/RECORD +103 -0
  99. trigrams_toolkit-0.1.0.dist-info/WHEEL +5 -0
  100. trigrams_toolkit-0.1.0.dist-info/entry_points.txt +5 -0
  101. trigrams_toolkit-0.1.0.dist-info/licenses/LICENSE +21 -0
  102. trigrams_toolkit-0.1.0.dist-info/licenses/THIRD_PARTY_NOTICES.md +18 -0
  103. trigrams_toolkit-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,23 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "tool": "harness-install",
4
+ "commands": [
5
+ {
6
+ "name": "install preview",
7
+ "mutation": false,
8
+ "input": "urn:harness:installation-cli#/$defs/installPreviewInput",
9
+ "output": "urn:harness:installation#/$defs/preview"
10
+ },
11
+ {
12
+ "name": "install apply",
13
+ "mutation": true,
14
+ "input": "urn:harness:installation-cli#/$defs/applyInput",
15
+ "output": "urn:harness:installation-cli#/$defs/operationResult"
16
+ },
17
+ {
18
+ "name": "archive",
19
+ "mutation": true,
20
+ "usage": "archive PATH [PATH ...]"
21
+ }
22
+ ]
23
+ }
@@ -0,0 +1,48 @@
1
+ {
2
+ "preview": {
3
+ "schemaVersion": 2,
4
+ "operationId": "operation_example",
5
+ "kind": "install",
6
+ "projectRoot": "C:/isolated/project",
7
+ "parameters": {
8
+ "agent": "codex",
9
+ "extensions": [
10
+ "example"
11
+ ],
12
+ "platforms": []
13
+ },
14
+ "baseRevision": 0,
15
+ "sources": {
16
+ "example": "C:/isolated/project/.agents/skills/extension-setup-example/assets"
17
+ },
18
+ "changes": [
19
+ {
20
+ "path": ".agents/extensions/example/extension.json",
21
+ "action": "write",
22
+ "before": null,
23
+ "after": {
24
+ "path": ".agents/extensions/example/extension.json",
25
+ "source": "example",
26
+ "kind": "file",
27
+ "contentDigest": "sha256:9ef3b7dcd7daa43322c66511f806e551176d2d41b6c065302f0bef9f8265f959"
28
+ }
29
+ },
30
+ {
31
+ "path": ".agents/harness.json",
32
+ "action": "write",
33
+ "before": null,
34
+ "after": {
35
+ "path": ".agents/harness.json",
36
+ "source": "core",
37
+ "kind": "file",
38
+ "contentDigest": "sha256:d2965e6966727dc8877cca52c795513835109ac7c0fbb79a962f5eb9fe6a56f1"
39
+ }
40
+ }
41
+ ],
42
+ "conflicts": []
43
+ },
44
+ "confirmedBy": {
45
+ "id": "developer",
46
+ "kind": "human"
47
+ }
48
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "agent": "codex",
3
+ "extensions": [
4
+ "example"
5
+ ],
6
+ "platforms": []
7
+ }
@@ -0,0 +1,20 @@
1
+ {
2
+ "schemaVersion": 2,
3
+ "stateRevision": 1,
4
+ "agent": "codex",
5
+ "extensions": [
6
+ {
7
+ "extension": "example",
8
+ "version": "1.0.0"
9
+ }
10
+ ],
11
+ "platforms": [],
12
+ "managed": [
13
+ {
14
+ "path": ".agents/extensions/example/extension.json",
15
+ "source": "example",
16
+ "kind": "file",
17
+ "contentDigest": "sha256:9ef3b7dcd7daa43322c66511f806e551176d2d41b6c065302f0bef9f8265f959"
18
+ }
19
+ ]
20
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "dependencies": [
3
+ {"name": "archify", "source": "https://archify.si", "package": "skills@latest"},
4
+ {"name": "smell-check", "source": "Zhen-Bo/smell-check", "package": "skills"}
5
+ ]
6
+ }
@@ -0,0 +1,295 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "urn:harness:installation",
4
+ "$defs": {
5
+ "platforms": {
6
+ "type": "array",
7
+ "uniqueItems": true,
8
+ "items": {
9
+ "enum": [
10
+ "codex",
11
+ "claude",
12
+ "pi-web"
13
+ ]
14
+ }
15
+ },
16
+ "managed": {
17
+ "$ref": "#/$defs/snapshotFile"
18
+ },
19
+ "change": {
20
+ "type": "object",
21
+ "additionalProperties": false,
22
+ "required": [
23
+ "path",
24
+ "action",
25
+ "before",
26
+ "after"
27
+ ],
28
+ "properties": {
29
+ "path": {
30
+ "$ref": "urn:harness:common#/$defs/path"
31
+ },
32
+ "action": {
33
+ "enum": [
34
+ "write",
35
+ "remove"
36
+ ]
37
+ },
38
+ "before": {
39
+ "oneOf": [
40
+ {
41
+ "type": "null"
42
+ },
43
+ {
44
+ "$ref": "#/$defs/managed"
45
+ }
46
+ ]
47
+ },
48
+ "after": {
49
+ "oneOf": [
50
+ {
51
+ "type": "null"
52
+ },
53
+ {
54
+ "$ref": "#/$defs/managed"
55
+ }
56
+ ]
57
+ }
58
+ },
59
+ "allOf": [
60
+ {
61
+ "if": {
62
+ "properties": {
63
+ "action": {
64
+ "const": "write"
65
+ }
66
+ }
67
+ },
68
+ "then": {
69
+ "properties": {
70
+ "after": {
71
+ "$ref": "#/$defs/managedFile"
72
+ }
73
+ }
74
+ }
75
+ },
76
+ {
77
+ "if": {
78
+ "properties": {
79
+ "action": {
80
+ "const": "remove"
81
+ }
82
+ }
83
+ },
84
+ "then": {
85
+ "properties": {
86
+ "after": {
87
+ "type": "null"
88
+ }
89
+ }
90
+ }
91
+ }
92
+ ]
93
+ },
94
+ "preview": {
95
+ "type": "object",
96
+ "additionalProperties": false,
97
+ "required": [
98
+ "schemaVersion",
99
+ "operationId",
100
+ "kind",
101
+ "projectRoot",
102
+ "parameters",
103
+ "baseRevision",
104
+ "changes",
105
+ "conflicts",
106
+ "sources"
107
+ ],
108
+ "properties": {
109
+ "schemaVersion": {
110
+ "const": 2
111
+ },
112
+ "operationId": {
113
+ "type": "string",
114
+ "pattern": "^operation_[A-Za-z0-9_-]+$"
115
+ },
116
+ "kind": {
117
+ "const": "install"
118
+ },
119
+ "projectRoot": {
120
+ "$ref": "urn:harness:common#/$defs/text"
121
+ },
122
+ "parameters": {
123
+ "$ref": "urn:harness:installation-cli#/$defs/installPreviewInput"
124
+ },
125
+ "baseRevision": {
126
+ "$ref": "urn:harness:common#/$defs/revision"
127
+ },
128
+ "changes": {
129
+ "type": "array",
130
+ "items": {
131
+ "$ref": "#/$defs/change"
132
+ }
133
+ },
134
+ "conflicts": {
135
+ "$ref": "urn:harness:common#/$defs/texts"
136
+ },
137
+ "sources": {
138
+ "type": "object",
139
+ "additionalProperties": {
140
+ "$ref": "urn:harness:common#/$defs/text"
141
+ }
142
+ }
143
+ }
144
+ },
145
+ "operation": {
146
+ "type": "object",
147
+ "additionalProperties": false,
148
+ "required": [
149
+ "schemaVersion",
150
+ "requestId",
151
+ "request",
152
+ "phase",
153
+ "backups",
154
+ "result"
155
+ ],
156
+ "properties": {
157
+ "schemaVersion": {
158
+ "const": 1
159
+ },
160
+ "requestId": {
161
+ "type": "string",
162
+ "pattern": "^req_[A-Za-z0-9_-]+$"
163
+ },
164
+ "request": {
165
+ "type": "object"
166
+ },
167
+ "phase": {
168
+ "enum": [
169
+ "applying",
170
+ "committed",
171
+ "rolled_back"
172
+ ]
173
+ },
174
+ "backups": {
175
+ "type": "array",
176
+ "items": {
177
+ "$ref": "#/$defs/change"
178
+ }
179
+ },
180
+ "result": {
181
+ "type": [
182
+ "object",
183
+ "null"
184
+ ]
185
+ }
186
+ }
187
+ },
188
+ "managedFile": {
189
+ "$ref": "#/$defs/snapshotFile"
190
+ },
191
+ "installation": {
192
+ "$ref": "#/$defs/snapshotInstallation"
193
+ },
194
+ "snapshotInstallation": {
195
+ "type": "object",
196
+ "additionalProperties": false,
197
+ "required": [
198
+ "schemaVersion",
199
+ "stateRevision",
200
+ "extensions",
201
+ "platforms",
202
+ "managed",
203
+ "agent"
204
+ ],
205
+ "properties": {
206
+ "schemaVersion": {
207
+ "const": 2
208
+ },
209
+ "stateRevision": {
210
+ "$ref": "urn:harness:common#/$defs/revision"
211
+ },
212
+ "extensions": {
213
+ "type": "array",
214
+ "uniqueItems": true,
215
+ "items": {
216
+ "$ref": "#/$defs/snapshotExtension"
217
+ }
218
+ },
219
+ "platforms": {
220
+ "$ref": "#/$defs/platforms"
221
+ },
222
+ "managed": {
223
+ "type": "array",
224
+ "uniqueItems": true,
225
+ "items": {
226
+ "$ref": "#/$defs/snapshotFile"
227
+ }
228
+ },
229
+ "agent": {
230
+ "$ref": "#/$defs/agent"
231
+ }
232
+ }
233
+ },
234
+ "agent": {
235
+ "enum": [
236
+ "codex",
237
+ "claude-code",
238
+ "pi"
239
+ ]
240
+ },
241
+ "snapshotExtension": {
242
+ "type": "object",
243
+ "additionalProperties": false,
244
+ "required": [
245
+ "extension",
246
+ "version"
247
+ ],
248
+ "properties": {
249
+ "extension": {
250
+ "allOf": [
251
+ {
252
+ "$ref": "urn:harness:common#/$defs/token"
253
+ },
254
+ {
255
+ "not": {
256
+ "enum": [
257
+ "core",
258
+ "project"
259
+ ]
260
+ }
261
+ }
262
+ ]
263
+ },
264
+ "version": {
265
+ "$ref": "urn:harness:guides#/$defs/version"
266
+ }
267
+ }
268
+ },
269
+ "snapshotFile": {
270
+ "type": "object",
271
+ "additionalProperties": false,
272
+ "required": [
273
+ "path",
274
+ "source",
275
+ "kind",
276
+ "contentDigest"
277
+ ],
278
+ "properties": {
279
+ "path": {
280
+ "$ref": "urn:harness:common#/$defs/path"
281
+ },
282
+ "source": {
283
+ "$ref": "urn:harness:common#/$defs/token"
284
+ },
285
+ "kind": {
286
+ "const": "file"
287
+ },
288
+ "contentDigest": {
289
+ "type": "string",
290
+ "pattern": "^sha256:[a-f0-9]{64}$"
291
+ }
292
+ }
293
+ }
294
+ }
295
+ }
@@ -0,0 +1,89 @@
1
+ # Plan 调度与当前状态契约
2
+
3
+ ## 命令
4
+
5
+ | 命令 | 效果 |
6
+ | --- | --- |
7
+ | `validate PLAN [--sync]` | 检查格式、声明一致性、混合依赖与完成路径;--sync 编译快照 |
8
+ | `get-task PLAN` | 读取当前可开工 Task 与等待原因 |
9
+ | `inspect PLAN [TASK] [--full]` | 默认读取精简状态;--full 返回完整交接视图 |
10
+ | `mark PLAN [TASK] STATE [--note TEXT]` | 写入 pending / doing / rework / done,联动 Stub |
11
+ | `block PLAN [TASK] --reason TEXT` | 写入 blocked 与原因 |
12
+ | `cancel PLAN [TASK] --reason TEXT` | 写入 cancelled 与原因 |
13
+
14
+ PLAN 为目录,TASK 为 tasks/<TASK>/task.md 的目录编号。省略 TASK 的状态命令修改 Plan。可在任意目录用 `-h` 或 `--help` 查看帮助,用根命令的 `-v` 或 `--version` 查看版本。validate 与 get-task 不接受 TASK,只有 validate 接受 --sync,只有 inspect 接受 --full。
15
+
16
+ ## 文稿定义
17
+
18
+ summary.md 保存总体要求与 Stub 详情;Task YAML 保存 dependsOn、specs、workspace、installs、fills、uses,工作要求写正文。Task ID 为 T 加数字。依赖和 Spec 列表缺省为空,workspace 可省略。未知头字段、重复键及重复引用会报错。
19
+
20
+ installs、fills、uses 为数组,每项只含 id 和 name,名称与 summary 中相同 ID 的标题一致。新计划的每个 Task 显式写这 3 项,未使用时为空数组。无 Stub 的既有精简文稿可省略,读取时按空数组处理;含 Stub 的 Plan 中不允许省略。
21
+
22
+ Stub ID 为 S 加数字,在 Plan 内唯一。summary 的块格式为:
23
+
24
+ ```markdown
25
+ <!-- harness:stub S01 -->
26
+ ### S01 库存服务
27
+ 安装与装填要求、交接位置及各阶段验收。
28
+ <!-- /harness:stub S01 -->
29
+ ```
30
+
31
+ 块不嵌套,首标题固定为三级标题、编号、名称;标题后有非空要求正文。Task 仅声明 ID 与名称,不复制详情。每个 Stub 恰有一个安装者与一个不同的装填者。
32
+
33
+ dependsOn 等待指定 Task done。uses 等待 Stub installed 或 filled。fills 隐含等待该 Stub installed,不必再写 uses;完整行为依赖通过 dependsOn 指向装填 Task。安装者依赖自身安装结果、同 Task 安装并装填同一 Stub、未知生产者与依赖环均不合规。
34
+
35
+ ## 快照与状态
36
+
37
+ [plan.schema.json](plan.schema.json) 定义 plan.json。根包含 status、tasks、stubs。每个 Task 记录 status、dependsOn、installs、fills、uses;引用列表只保存 ID。Stub 记录 name 与 status,不保存正文或重复的生产者字段。反向生产关系从 Task 声明推导。
38
+
39
+ Plan 与 Task 状态为 pending、doing、rework、blocked、done、cancelled。有信息时保存 note;blocked 和 cancelled 要求非空 reason,其他状态不接受 reason。状态动作替换目标当前说明,未提供的说明清除,不改动声明快照。
40
+
41
+ Stub 状态为 uninstalled、installed、filled。安装者未 done 时为 uninstalled;安装者 done 且装填者未 done 时为 installed;两者均 done 时为 filled。保存的 Stub 状态应与 Task 状态一致。
42
+
43
+ validate --sync 首次建立快照,后续保留既有 status、note、reason,从文稿同步声明并推导 Stub 状态。新增 Task 为 pending,新增 Plan 为 pending。删除非 pending Task、修改 doing / done Task 的调度声明、丢弃已有交付阶段的 Stub 时返回 progress_conflict。删除尚未开工的 pending Task 可在无剩余引用时同步。
44
+
45
+ 同步前先验证已有文件格式与进展一致性。候选通过当前进展与完成路径检查后才写入,不修复损坏状态。普通 validate、get-task 和状态写入要求快照已存在且与文稿相同;缺少时返回 missing_state,过期时返回 definition_out_of_sync。inspect 在没有状态文件时可预览 pending 状态。
46
+
47
+ ## 依赖校验与就绪
48
+
49
+ 所有 dependsOn 边,以及每个 fills / uses 指向安装者的等待边,合并成 Task 图。校验完整图的环,包括已完成 Task 的声明,错误返回实际环中的 Task 链。只检查显式 dependsOn 不足以判定合规。
50
+
51
+ 在拓扑顺序中模拟全部未撤销 Task 的完成。结构演算允许 blocked 临时阻因解除;不把 blocked 当永久死锁。cancelled 不完成前置,也不产生 Stub 阶段成果。仍不可达的 Task 或无法装填的 Stub 导致 unreachable_plan。
52
+
53
+ doing / done Task 的前置应已满足。生产者回退或撤销会重算 Stub;若破坏这些下游则返回 invalid_progress,不自动回退其他 Task。block / cancel 可记录异常,但由此产生的完成路径缺口应在继续调度前修订。
54
+
55
+ get-task 内部复用上述检查,不额外调用 Spec 定位。只返回 pending / rework 且 Task、Stub 前置均满足的 Task,按 Task ID 排列。blocked 单列人工阻因,doing、done、cancelled 不进入候选。Plan 为 blocked、done、cancelled 时 ready 为空。空候选不等于完成,也不代表文件修改可并行。
56
+
57
+ mark doing、rework、done 核对同一套 Task 与 Stub 前置,不能绕过阶段顺序。Task 新转为 doing 时,Plan 应为 pending、doing 或 rework;整体受阻或结束时先恢复 Plan,已有 doing 记录不级联改变。Plan done 要求全部 Task 为 done 或 cancelled,全部保留 Stub 为 filled。Task 变动不级联改变其他 Task 或 Plan;取消 Plan 不修改 Task 或删除交付。
58
+
59
+ ## 文件与项目定位
60
+
61
+ 业务命令从目标项目根运行。相对路径以进程当前目录为基准。Plan 的实际路径须在当前项目内,Git worktree 从各自的根读取 Plan 状态。
62
+
63
+ Task inspect 将同一项目根与 specs ID 交给 Project State 定位服务,读取该根的 Registry 与正文。单条失败保存在 data.specs[].error,不改变外层成功响应;调用方核对 path 或 error。默认与完整视图均保留每项定位结果。整体 inspect 不定位 Spec。Task 查询的 data.stubs 只包含 installs / fills / uses 引用的块;默认每项含 name、status,--full 另含 body。
64
+
65
+ 读命令不写文件。validate --sync 和状态命令先预检,再在 .plan.lock 的普通文件锁内重新读取,原子替换 plan.json。Task 与 Stub 一次提交。锁冲突返回 lock_busy,不自动合并;锁文件保留,进程退出后操作系统释放锁。预检失败不创建新锁文件。
66
+
67
+ ## 输出
68
+
69
+ 成功输出一行 UTF-8 JSON:`{"ok":true,"data":{...}}`,退出 0;参数、业务或 IO 失败退出 1。帮助与版本输出纯文本。
70
+
71
+ | 调用 | data |
72
+ | --- | --- |
73
+ | validate | valid 为 true,changed 表示是否写入;普通检查为 false |
74
+ | get-task | status 为 Plan 状态;ready 每项含 id、绝对 path;waiting 按 Task ID 列出阻因 |
75
+ | inspect PLAN | directory、status、按 Task ID 索引的 tasks;有值时保留 Plan 与 Task 的 note、reason,Task 的 workspace、非空 blockers,以及非空 stubs 的 name、status |
76
+ | inspect PLAN TASK | id、绝对 path、status;有值时保留 note、reason、workspace、非空 blockers、关联 stubs 的 name、status,以及非空 specs 的原定位结果或 error |
77
+ | inspect PLAN --full | 原完整状态、stubs、tasks、directory、summary;Task 记录含声明数组、绝对 path 与 blockers,保留空集合 |
78
+ | inspect PLAN TASK --full | id、完整当前记录、绝对 path、directory、body、contents、关联 Stub 的 name、status、body、specs 定位与 blockers,保留空集合 |
79
+ | 状态写入 | changed、directory、本次目标状态与说明;Task 另含 id;阶段变动时另含 stubChanges |
80
+
81
+ waiting 的前置阻因格式为 `{"type":"task或stub","id":"编号","required":"done或installed"}`;人工阻因为 `{"type":"manual","reason":"原因"}`。stubChanges 为 Stub ID 到新状态的映射,不附送完整任务表。
82
+
83
+ inspect 默认省略调度声明数组、空集合与重复路径。整体查询只保留 Plan 根目录,不重复 Task 路径或 summary 路径;Task 查询保留 task.md 的精确绝对 path,省略 directory、body、contents 和 Stub 正文。任务定义和正文从 `tasks/<Task ID>/task.md` 读取,Stub 正文从 `summary.md` 对应块读取。两种视图均不返回 ready;可开工项仍由 get-task 计算。
84
+
85
+ 协议失败返回 `{"ok":false,"error":{"code":"...","message":"...","issues":[...]}}`。issues 提供字段路径、Task、Stub 或依赖链;IO 失败仅有 code 与 message。调用方检查退出码与 ok,validate 另检查 data.valid。
86
+
87
+ 原先无 Stub 的精简状态只允许显式 --sync 补齐,并保留已有状态。更早的版本化状态或冻结文稿返回 unsupported_plan,应通过 initialize 归档重建。
88
+
89
+ plan.schema.json 的身份为 urn:harness:plan。[commands.json](commands.json) 是 6 个命令的清单。
@@ -0,0 +1,61 @@
1
+ # Plan Toolkit
2
+
3
+ `plan-toolkit` 读取 Plan 文稿,编译调度快照,维护 Plan、Task 与 Stub 的当前状态。
4
+
5
+ ## 编写与检查
6
+
7
+ 先编写 `summary.md` 和 `tasks/T01/task.md`。Task 声明 installs、fills、uses 中的 Stub 编号与名称;完整要求保存在 summary 的 Stub 块。完整格式通过 `to-plan` Skill 获取。
8
+
9
+ ```powershell
10
+ plan-toolkit validate docs/plans/P01 --sync
11
+ plan-toolkit validate docs/plans/P01
12
+ plan-toolkit get-task docs/plans/P01
13
+ plan-toolkit inspect docs/plans/P01 T01
14
+ plan-toolkit mark docs/plans/P01 doing
15
+ plan-toolkit mark docs/plans/P01 T01 doing
16
+ plan-toolkit mark docs/plans/P01 T01 done --note "框架已审核且下游可读取"
17
+ plan-toolkit block docs/plans/P01 T02 --reason "等待接口确定;从序列化适配继续"
18
+ plan-toolkit cancel docs/plans/P01 T03 --reason "范围已撤销"
19
+ ```
20
+
21
+ 从目标项目根运行上面的命令。`PLAN` 是项目内的明确目录,相对路径从项目根解析。`TASK` 来自 Task 目录编号,省略时状态命令修改 Plan 自身。可在任意目录用 `-h` 或 `--help` 查看帮助,用 `-v` 或 `--version` 查看工具包版本。
22
+
23
+ `validate --sync` 建立或更新 plan.json 的定义快照,并保留已有状态、note 和 reason。新增 Task 为 pending。同步会检查格式、名称、生产者、阶段顺序、Task / Stub 混合依赖环及完成路径。候选不合规时不替换原状态。
24
+
25
+ 成功时检查退出码为 0、`ok: true`、`data.valid: true`;`data.changed` 表示是否写入。普通 validate 只读,缺少状态或快照过期时失败。计划修订后再次显式同步,不手工维护 JSON 声明。
26
+
27
+ ## 获取当前工作
28
+
29
+ `get-task PLAN` 返回 `data.status`、`data.ready[]` 与 `data.waiting`。ready 每项含 Task id 与 task.md 的绝对 path。waiting 按 Task 编号列出 Task 前置、Stub 安装条件或人工阻因。空清单不代表 Plan 完成。
30
+
31
+ 候选 Task 为 pending 或 rework,dependsOn 均 done,uses 和 fills 的 Stub 均已 installed 或 filled。doing、blocked、done、cancelled Task 不重复派发。Plan 为 blocked、done 或 cancelled 时不提供候选。真实共享文件竞争与工作树整合仍由调度者判断。
32
+
33
+ `inspect PLAN` 默认返回精简状态:Plan 根目录、整体状态和按 Task ID 索引的状态表,并保留有值的说明、工作目录、阻因及 Stub 名称和阶段。`inspect PLAN TASK` 返回 Task 的绝对路径、状态、关联 Stub 名称和阶段,以及 Spec 入口。Task 定义与正文从该路径读取,Stub 正文从 summary 的对应块读取。没有 plan.json 时 inspect 可预览 pending 状态,不写文件;调度与状态变更应先完成同步。
34
+
35
+ inspect 的 `--full` 返回原完整视图,包含调度声明、重复路径和空集合;Task 查询还包含正文、目录文件与 Stub 正文。两种视图均不返回 ready,可开工项仍用 get-task 查询。完整字段由 [PROTOCOL.md](PROTOCOL.md) 维护。
36
+
37
+ Spec 按 ID 调用包内 state 定位服务,与 project-state locate 使用同一业务实现。Task 查询的 `data.specs[]` 可含单条 error,外层成功不代表全部 Spec 已定位。整体查询不定位 Spec。
38
+
39
+ ## 状态联动
40
+
41
+ Stub 状态为 `uninstalled → installed → filled`。同一 Stub 的安装与装填由不同 Task 承担。安装 Task done 后进入 installed;装填 Task done 后进入 filled。uses 只等待框架,等待完整行为使用 dependsOn 指向装填 Task。
42
+
43
+ mark 接受 pending、doing、rework、done。block 和 cancel 写入 blocked 或 cancelled,并要求非空 reason。每次动作替换目标当前说明,未提供的 note 或 reason 清除,重复相同动作返回 changed 为 false。Task 转为 doing、rework 或 done 时都会核对前置。
44
+
45
+ 状态写入返回本次目标状态,发生阶段变化时另返回 `data.stubChanges`,例如 `{"S01":"installed"}`。Task 与 Stub 在同一次原子替换中更新;不级联改变其他 Task 或 Plan。
46
+
47
+ 生产者返工或撤销后,Stub 会重新计算。若会破坏 doing / done 下游,则拒绝写入并列出受影响 Task。取消必要生产者会使 validate 和 get-task 报告计划不可完成,修订相应安排后同步。Plan done 要求全部 Task 为 done 或 cancelled,全部保留 Stub 为 filled。
48
+
49
+ 写命令使用普通文件锁与原子替换;失败不覆盖原文件。sync 不静默删除已开工 Task,不修改 doing / done Task 的调度声明,也不修复损坏的状态。完整字段、响应与错误见 [PROTOCOL.md](PROTOCOL.md)。
50
+
51
+ 原先无 Stub 的精简状态可通过显式 validate --sync 补齐快照并保留进展。更早的冻结文稿或版本化状态仍返回 unsupported_plan,应通过 initialize 归档并重建。
52
+
53
+ ## 验证
54
+
55
+ 从仓库根运行:
56
+
57
+ ```powershell
58
+ python -m unittest discover -s tests/runtime -p "test_plan_*.py" -v
59
+ python -m unittest discover -s tests/runtime -p "test_cli_help.py" -v
60
+ python -m unittest discover -s tests/runtime -p "test_atomic_files.py" -v
61
+ ```
@@ -0,0 +1,36 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "tool": "plan-toolkit",
4
+ "commands": [
5
+ {
6
+ "name": "validate",
7
+ "usage": "PLAN [--sync]",
8
+ "mutation": true
9
+ },
10
+ {
11
+ "name": "get-task",
12
+ "usage": "PLAN",
13
+ "mutation": false
14
+ },
15
+ {
16
+ "name": "inspect",
17
+ "usage": "PLAN [TASK] [--full]",
18
+ "mutation": false
19
+ },
20
+ {
21
+ "name": "mark",
22
+ "usage": "PLAN [TASK] STATE [--note TEXT]",
23
+ "mutation": true
24
+ },
25
+ {
26
+ "name": "block",
27
+ "usage": "PLAN [TASK] --reason TEXT",
28
+ "mutation": true
29
+ },
30
+ {
31
+ "name": "cancel",
32
+ "usage": "PLAN [TASK] --reason TEXT",
33
+ "mutation": true
34
+ }
35
+ ]
36
+ }