perttool 0.4.0 → 0.5.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.
Files changed (223) hide show
  1. package/CHANGELOG.md +44 -1
  2. package/README.md +84 -34
  3. package/dist/actuals/lifecycle.d.ts +101 -0
  4. package/dist/actuals/lifecycle.d.ts.map +1 -0
  5. package/dist/actuals/lifecycle.js +329 -0
  6. package/dist/actuals/lifecycle.js.map +1 -0
  7. package/dist/actuals/source.d.ts +36 -0
  8. package/dist/actuals/source.d.ts.map +1 -0
  9. package/dist/actuals/source.js +119 -0
  10. package/dist/actuals/source.js.map +1 -0
  11. package/dist/analysis/temporal-deadline.d.ts +2 -2
  12. package/dist/analysis/temporal-deadline.d.ts.map +1 -1
  13. package/dist/analysis/temporal-deadline.js.map +1 -1
  14. package/dist/analysis/temporal-precedence.d.ts +2 -2
  15. package/dist/analysis/temporal-precedence.d.ts.map +1 -1
  16. package/dist/analysis/temporal-precedence.js +2 -0
  17. package/dist/analysis/temporal-precedence.js.map +1 -1
  18. package/dist/analysis/temporal-resource.d.ts +2 -2
  19. package/dist/analysis/temporal-resource.d.ts.map +1 -1
  20. package/dist/analysis/temporal-resource.js +2 -0
  21. package/dist/analysis/temporal-resource.js.map +1 -1
  22. package/dist/application/analyze.d.ts +1 -0
  23. package/dist/application/analyze.d.ts.map +1 -1
  24. package/dist/application/analyze.js +38 -29
  25. package/dist/application/analyze.js.map +1 -1
  26. package/dist/application/check.d.ts +3 -0
  27. package/dist/application/check.d.ts.map +1 -1
  28. package/dist/application/check.js +17 -1
  29. package/dist/application/check.js.map +1 -1
  30. package/dist/application/contract6-actuals.d.ts +24 -0
  31. package/dist/application/contract6-actuals.d.ts.map +1 -0
  32. package/dist/application/contract6-actuals.js +51 -0
  33. package/dist/application/contract6-actuals.js.map +1 -0
  34. package/dist/application/contract6-mutation.d.ts +18 -0
  35. package/dist/application/contract6-mutation.d.ts.map +1 -0
  36. package/dist/application/contract6-mutation.js +173 -0
  37. package/dist/application/contract6-mutation.js.map +1 -0
  38. package/dist/application/contract6-projection.d.ts +9 -0
  39. package/dist/application/contract6-projection.d.ts.map +1 -0
  40. package/dist/application/contract6-projection.js +105 -0
  41. package/dist/application/contract6-projection.js.map +1 -0
  42. package/dist/application/init.d.ts +1 -1
  43. package/dist/application/init.js +3 -3
  44. package/dist/application/project.js +2 -2
  45. package/dist/application/target-actuals-advance.d.ts +12 -0
  46. package/dist/application/target-actuals-advance.d.ts.map +1 -0
  47. package/dist/application/target-actuals-advance.js +113 -0
  48. package/dist/application/target-actuals-advance.js.map +1 -0
  49. package/dist/application/target-actuals-analysis.d.ts +76 -0
  50. package/dist/application/target-actuals-analysis.d.ts.map +1 -0
  51. package/dist/application/target-actuals-analysis.js +250 -0
  52. package/dist/application/target-actuals-analysis.js.map +1 -0
  53. package/dist/application/target-actuals-mutation.d.ts +28 -0
  54. package/dist/application/target-actuals-mutation.d.ts.map +1 -0
  55. package/dist/application/target-actuals-mutation.js +404 -0
  56. package/dist/application/target-actuals-mutation.js.map +1 -0
  57. package/dist/application/target-actuals-write.d.ts +7 -0
  58. package/dist/application/target-actuals-write.d.ts.map +1 -0
  59. package/dist/application/target-actuals-write.js +37 -0
  60. package/dist/application/target-actuals-write.js.map +1 -0
  61. package/dist/application/target-governance-init.d.ts +3 -3
  62. package/dist/application/target-governance-init.d.ts.map +1 -1
  63. package/dist/application/target-governance-init.js +20 -10
  64. package/dist/application/target-governance-init.js.map +1 -1
  65. package/dist/application/target-governance-project.d.ts +4 -4
  66. package/dist/application/target-governance-project.d.ts.map +1 -1
  67. package/dist/application/target-governance-project.js +4 -2
  68. package/dist/application/target-governance-project.js.map +1 -1
  69. package/dist/application/target-governance-write.d.ts +8 -0
  70. package/dist/application/target-governance-write.d.ts.map +1 -1
  71. package/dist/application/target-governance-write.js +1 -1
  72. package/dist/application/target-governance-write.js.map +1 -1
  73. package/dist/application/target-mutate.d.ts +3 -1
  74. package/dist/application/target-mutate.d.ts.map +1 -1
  75. package/dist/application/target-mutate.js +34 -2
  76. package/dist/application/target-mutate.js.map +1 -1
  77. package/dist/application/target-project-history.d.ts +18 -0
  78. package/dist/application/target-project-history.d.ts.map +1 -0
  79. package/dist/application/target-project-history.js +279 -0
  80. package/dist/application/target-project-history.js.map +1 -0
  81. package/dist/application/target-temporal-analysis.d.ts +7 -1
  82. package/dist/application/target-temporal-analysis.d.ts.map +1 -1
  83. package/dist/application/target-temporal-analysis.js +10 -8
  84. package/dist/application/target-temporal-analysis.js.map +1 -1
  85. package/dist/application/target-temporal-input.d.ts +6 -4
  86. package/dist/application/target-temporal-input.d.ts.map +1 -1
  87. package/dist/application/target-temporal-input.js +10 -1
  88. package/dist/application/target-temporal-input.js.map +1 -1
  89. package/dist/application/target-unit-migration-candidate.d.ts +2 -2
  90. package/dist/application/target-unit-migration-candidate.d.ts.map +1 -1
  91. package/dist/application/target-unit-migration-candidate.js +21 -10
  92. package/dist/application/target-unit-migration-candidate.js.map +1 -1
  93. package/dist/application/target-unit-migration-request.d.ts +4 -4
  94. package/dist/application/target-unit-migration-request.d.ts.map +1 -1
  95. package/dist/application/target-unit-migration-request.js +6 -4
  96. package/dist/application/target-unit-migration-request.js.map +1 -1
  97. package/dist/application/target-unit-migration-result.d.ts +5 -5
  98. package/dist/application/target-unit-migration-result.d.ts.map +1 -1
  99. package/dist/application/target-unit-migration-result.js +1 -1
  100. package/dist/application/target-unit-migration-result.js.map +1 -1
  101. package/dist/application/target-velocity-observation.d.ts +11 -0
  102. package/dist/application/target-velocity-observation.d.ts.map +1 -0
  103. package/dist/application/target-velocity-observation.js +201 -0
  104. package/dist/application/target-velocity-observation.js.map +1 -0
  105. package/dist/application/unit-migration.d.ts +2 -2
  106. package/dist/application/unit-migration.d.ts.map +1 -1
  107. package/dist/application/unit-migration.js +2 -2
  108. package/dist/cli.js +285 -45
  109. package/dist/cli.js.map +1 -1
  110. package/dist/command/actuals-discovery.d.ts +26 -0
  111. package/dist/command/actuals-discovery.d.ts.map +1 -0
  112. package/dist/command/actuals-discovery.js +271 -0
  113. package/dist/command/actuals-discovery.js.map +1 -0
  114. package/dist/command/actuals-usage.d.ts +22 -0
  115. package/dist/command/actuals-usage.d.ts.map +1 -0
  116. package/dist/command/actuals-usage.js +122 -0
  117. package/dist/command/actuals-usage.js.map +1 -0
  118. package/dist/formatter/source-formatter.d.ts +3 -3
  119. package/dist/formatter/source-formatter.d.ts.map +1 -1
  120. package/dist/formatter/source-formatter.js +53 -5
  121. package/dist/formatter/source-formatter.js.map +1 -1
  122. package/dist/formatter/target-source-formatter.d.ts +2 -1
  123. package/dist/formatter/target-source-formatter.d.ts.map +1 -1
  124. package/dist/formatter/target-source-formatter.js +18 -2
  125. package/dist/formatter/target-source-formatter.js.map +1 -1
  126. package/dist/governance/authority.d.ts +7 -3
  127. package/dist/governance/authority.d.ts.map +1 -1
  128. package/dist/governance/authority.js.map +1 -1
  129. package/dist/governance/source.d.ts +2 -2
  130. package/dist/governance/source.d.ts.map +1 -1
  131. package/dist/governance/source.js.map +1 -1
  132. package/dist/help/actuals-guide.d.ts +10 -0
  133. package/dist/help/actuals-guide.d.ts.map +1 -0
  134. package/dist/help/actuals-guide.js +23 -0
  135. package/dist/help/actuals-guide.js.map +1 -0
  136. package/dist/help/guide.d.ts +1 -1
  137. package/dist/help/guide.d.ts.map +1 -1
  138. package/dist/help/registry.d.ts.map +1 -1
  139. package/dist/help/registry.js +97 -7
  140. package/dist/help/registry.js.map +1 -1
  141. package/dist/history/git-probe.d.ts +52 -0
  142. package/dist/history/git-probe.d.ts.map +1 -0
  143. package/dist/history/git-probe.js +565 -0
  144. package/dist/history/git-probe.js.map +1 -0
  145. package/dist/history/project-history.d.ts +112 -0
  146. package/dist/history/project-history.d.ts.map +1 -0
  147. package/dist/history/project-history.js +786 -0
  148. package/dist/history/project-history.js.map +1 -0
  149. package/dist/history/velocity-observation.d.ts +69 -0
  150. package/dist/history/velocity-observation.d.ts.map +1 -0
  151. package/dist/history/velocity-observation.js +604 -0
  152. package/dist/history/velocity-observation.js.map +1 -0
  153. package/dist/index.d.ts +19 -10
  154. package/dist/index.d.ts.map +1 -1
  155. package/dist/index.js +9 -5
  156. package/dist/index.js.map +1 -1
  157. package/dist/io/target-safe-write.d.ts +4 -1
  158. package/dist/io/target-safe-write.d.ts.map +1 -1
  159. package/dist/io/target-safe-write.js +19 -1
  160. package/dist/io/target-safe-write.js.map +1 -1
  161. package/dist/migration/conversion.d.ts +1 -1
  162. package/dist/migration/conversion.d.ts.map +1 -1
  163. package/dist/migration/grammar-boundary.d.ts +1 -1
  164. package/dist/migration/grammar-boundary.d.ts.map +1 -1
  165. package/dist/migration/grammar-boundary.js +11 -3
  166. package/dist/migration/grammar-boundary.js.map +1 -1
  167. package/dist/migration/request.d.ts +5 -5
  168. package/dist/migration/request.d.ts.map +1 -1
  169. package/dist/migration/request.js +15 -2
  170. package/dist/migration/request.js.map +1 -1
  171. package/dist/model/calendar.d.ts +2 -0
  172. package/dist/model/calendar.d.ts.map +1 -1
  173. package/dist/model/calendar.js +19 -0
  174. package/dist/model/calendar.js.map +1 -1
  175. package/dist/model/declaration-fields.d.ts +8 -0
  176. package/dist/model/declaration-fields.d.ts.map +1 -1
  177. package/dist/model/declaration-fields.js +13 -0
  178. package/dist/model/declaration-fields.js.map +1 -1
  179. package/dist/model/exact-person-hours-source.d.ts +2 -0
  180. package/dist/model/exact-person-hours-source.d.ts.map +1 -0
  181. package/dist/model/exact-person-hours-source.js +10 -0
  182. package/dist/model/exact-person-hours-source.js.map +1 -0
  183. package/dist/model/syntax.d.ts +23 -8
  184. package/dist/model/syntax.d.ts.map +1 -1
  185. package/dist/model/syntax.js.map +1 -1
  186. package/dist/mutation/actuals.d.ts +17 -0
  187. package/dist/mutation/actuals.d.ts.map +1 -0
  188. package/dist/mutation/actuals.js +90 -0
  189. package/dist/mutation/actuals.js.map +1 -0
  190. package/dist/mutation/advance.d.ts +9 -3
  191. package/dist/mutation/advance.d.ts.map +1 -1
  192. package/dist/mutation/advance.js +41 -12
  193. package/dist/mutation/advance.js.map +1 -1
  194. package/dist/mutation/entity-editor.d.ts +2 -2
  195. package/dist/mutation/entity-editor.d.ts.map +1 -1
  196. package/dist/mutation/entity-editor.js.map +1 -1
  197. package/dist/mutation/project.d.ts +2 -0
  198. package/dist/mutation/project.d.ts.map +1 -1
  199. package/dist/mutation/project.js +13 -4
  200. package/dist/mutation/project.js.map +1 -1
  201. package/dist/mutation/source.d.ts +3 -3
  202. package/dist/mutation/source.d.ts.map +1 -1
  203. package/dist/mutation/source.js.map +1 -1
  204. package/dist/parser/document-parser.d.ts +8 -1
  205. package/dist/parser/document-parser.d.ts.map +1 -1
  206. package/dist/parser/document-parser.js +151 -23
  207. package/dist/parser/document-parser.js.map +1 -1
  208. package/dist/recommendation/override-types.d.ts +2 -2
  209. package/dist/recommendation/override.d.ts +2 -2
  210. package/dist/recommendation/override.d.ts.map +1 -1
  211. package/dist/recommendation/override.js +2 -2
  212. package/dist/recommendation/override.js.map +1 -1
  213. package/dist/semantic/target-validator.d.ts +13 -2
  214. package/dist/semantic/target-validator.d.ts.map +1 -1
  215. package/dist/semantic/target-validator.js +46 -2
  216. package/dist/semantic/target-validator.js.map +1 -1
  217. package/dist/semantic/validator.d.ts +4 -1
  218. package/dist/semantic/validator.d.ts.map +1 -1
  219. package/dist/semantic/validator.js +152 -6
  220. package/dist/semantic/validator.js.map +1 -1
  221. package/dist/version.d.ts +1 -1
  222. package/dist/version.js +1 -1
  223. package/package.json +3 -2
package/CHANGELOG.md CHANGED
@@ -4,6 +4,48 @@ This project records its notable changes here. The format is based on [Keep a Ch
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.5.0] - 2026-07-29
8
+
9
+ Contract 6 beta release. This version atomically publishes Grammar 5,
10
+ explicit task lifecycle evidence, read-only Git history and velocity
11
+ observation, and the English repository baseline. It intentionally changes
12
+ every CLI JSON envelope and several result identities while retaining
13
+ suffix-free `0.x.x` beta product maturity.
14
+
15
+ ### Added
16
+
17
+ - Activated Grammar 5 task-owned work events and preview-first
18
+ `task start|suspend|resume` plus eventful `task finish` with explicit event
19
+ time, exact active time, exact person effort, deterministic event identity,
20
+ governance, and safe-write controls.
21
+ - Added read-only first-parent `project history` and
22
+ `project observe-velocity`, including explicit-event reconstruction,
23
+ qualified Git-recorded transitions, exact task summaries, and separate
24
+ elapsed-hour, active-date, effort-productivity, and recorded-evidence
25
+ candidates.
26
+ - Added public actuals/history/observation Core exports, Contract 6 command
27
+ discovery and Guide topics, Grammar 5 examples, and isolated installed
28
+ lifecycle/history/observation checks.
29
+
30
+ ### Changed
31
+
32
+ - Activated CLI Contract 6 in the current source. Every JSON envelope now
33
+ reports `cli_contract_version=6`; check, analysis, next, mutation/advance,
34
+ and unit migration use result versions 3, 4, 5, 3, and 3 respectively.
35
+ - Added suspended-state analysis and `groups.suspended`, while retaining the
36
+ Recommendation version 1 ranking and
37
+ `recommendation_v1_plus_release_gate` start-authority policy.
38
+ - Extended exact unit migration through Grammar 5
39
+ `work_event.planned_value` without changing event time, active time, effort,
40
+ or declared velocity. The prior `0.4.0` artifact remains available as the
41
+ Grammar 4 and CLI Contract 5 compatibility pin.
42
+
43
+ ### Fixed
44
+
45
+ - Merged adjacent zero-length task-status and work-event insertions so a
46
+ lifecycle mutation can atomically start a task whose declaration ends at
47
+ end of file.
48
+
7
49
  ## [0.4.0] - 2026-07-28
8
50
 
9
51
  Contract 5 beta release. This version atomically publishes Grammar 4 and
@@ -174,7 +216,8 @@ First public development preview. Intended to evaluate the DSL and CLI, read-onl
174
216
  - Not published to the npm registry; use the GitHub Release asset
175
217
  - Requires Node.js 24 or later
176
218
 
177
- [Unreleased]: https://github.com/mako10k/perttool/compare/v0.4.0...HEAD
219
+ [Unreleased]: https://github.com/mako10k/perttool/compare/v0.5.0...HEAD
220
+ [0.5.0]: https://github.com/mako10k/perttool/compare/v0.4.0...v0.5.0
178
221
  [0.4.0]: https://github.com/mako10k/perttool/compare/v0.3.0...v0.4.0
179
222
  [0.3.0]: https://github.com/mako10k/perttool/compare/v0.2.0...v0.3.0
180
223
  [0.2.0]: https://github.com/mako10k/perttool/compare/v0.1.0...v0.2.0
package/README.md CHANGED
@@ -5,54 +5,56 @@ It validates an Activity-on-Arrow plan, calculates precedence and
5
5
  resource-constrained schedules, recommends the next task, and applies
6
6
  source-preserving changes through preview-first commands.
7
7
 
8
- The prepared `0.4.0` source implements Grammar 4 and CLI Contract 5. Its
9
- publication remains a separate operation; npm `beta` and `latest` still
10
- resolve to Contract 4 `0.3.0` until that operation is explicitly authorized.
11
- Beta releases may contain breaking CLI or schema changes. Version `0.4.0`
12
- requires Node.js 22 or later. Contract 4 and Contract 3 remain available by
13
- pinning `0.3.0` and `0.2.0`, respectively.
8
+ The prepared `0.5.0` source implements Grammar 5 and CLI Contract 6,
9
+ including explicit task work events, lifecycle commands, read-only Git
10
+ history, observed velocity, AnalysisResult v4, and NextResult v5. Publication
11
+ remains a gated operation; npm `beta` and `latest` still resolve to Contract 5
12
+ `0.4.0` until that operation completes. Beta releases may contain breaking
13
+ CLI or schema changes. Version `0.5.0` requires Node.js 22 or later. Contract
14
+ 5, Contract 4, and Contract 3 remain available by pinning `0.4.0`, `0.3.0`,
15
+ and `0.2.0`, respectively.
14
16
 
15
17
  ## Run without installing
16
18
 
17
- Use `npx` for an occasional invocation and select Contract 5 explicitly:
19
+ Use `npx` for an occasional invocation and select Contract 6 explicitly:
18
20
 
19
21
  ```sh
20
- npx --yes --package=perttool@0.4.0 -- perttool --version
21
- npx --yes --package=perttool@0.4.0 -- perttool document check PLAN.pert
22
- npx --yes --package=perttool@0.4.0 -- perttool dag next PLAN.pert --format json
23
- npx --yes --package=perttool@0.4.0 -- perttool project migrate-unit PLAN.pert --to-unit day --diff
22
+ npx --yes --package=perttool@0.5.0 -- perttool --version
23
+ npx --yes --package=perttool@0.5.0 -- perttool document check PLAN.pert
24
+ npx --yes --package=perttool@0.5.0 -- perttool dag next PLAN.pert --format json
25
+ npx --yes --package=perttool@0.5.0 -- perttool project history PLAN.pert --format json
24
26
  ```
25
27
 
26
28
  The equivalent explicit `npm exec` form is:
27
29
 
28
30
  ```sh
29
- npm exec --yes --package=perttool@0.4.0 -- perttool --version
30
- npm exec --yes --package=perttool@0.4.0 -- perttool document check PLAN.pert
31
- npm exec --yes --package=perttool@0.4.0 -- perttool dag analyze PLAN.pert
32
- npm exec --yes --package=perttool@0.4.0 -- perttool project migrate-unit PLAN.pert --to-unit day --diff
31
+ npm exec --yes --package=perttool@0.5.0 -- perttool --version
32
+ npm exec --yes --package=perttool@0.5.0 -- perttool document check PLAN.pert
33
+ npm exec --yes --package=perttool@0.5.0 -- perttool dag analyze PLAN.pert
34
+ npm exec --yes --package=perttool@0.5.0 -- perttool project history PLAN.pert --format json
33
35
  ```
34
36
 
35
37
  `npx` and `npm exec` may download the selected package version into the npm
36
- cache. The `0.4.0` registry commands become available only after the
37
- separately authorized publication. Pinning `0.3.0` selects Contract 4 and
38
- therefore does not accept the governance surface in this README; pinning
39
- `0.2.0` selects Contract 3 and also omits the temporal and migration surface.
38
+ cache. The `0.5.0` registry commands become available only after the gated
39
+ publication. Pinning `0.4.0` selects Contract 5 and therefore omits Grammar 5
40
+ lifecycle and history; `0.3.0` selects Contract 4, and `0.2.0` selects
41
+ Contract 3.
40
42
 
41
43
  ## Install
42
44
 
43
45
  Install the CLI globally when it is used regularly:
44
46
 
45
47
  ```sh
46
- npm install --global perttool@0.4.0
48
+ npm install --global perttool@0.5.0
47
49
  perttool --version
48
50
  ```
49
51
 
50
- The prepared release will move npm `beta` to Contract 5 `0.4.0` while leaving
51
- `latest` on Contract 4 `0.3.0`. Before publication, both tags still resolve
52
- to `0.3.0`, so use a locally packed `0.4.0` artifact for candidate testing.
53
- After publication, `perttool@beta` follows Contract 5. Contract 4 and
54
- Contract 3 remain available as exact pins `perttool@0.3.0` and
55
- `perttool@0.2.0`.
52
+ The prepared release will move npm `beta` to Contract 6 `0.5.0` while leaving
53
+ `latest` on Contract 5 `0.4.0`. Before publication, both tags still resolve
54
+ to `0.4.0`, so use a locally packed `0.5.0` artifact for candidate testing.
55
+ After publication, `perttool@beta` follows Contract 6. Contract 5, Contract 4,
56
+ and Contract 3 remain available as exact pins `perttool@0.4.0`,
57
+ `perttool@0.3.0`, and `perttool@0.2.0`.
56
58
 
57
59
  ## Plan files
58
60
 
@@ -95,7 +97,8 @@ Task duration can use deterministic `day`, `hour`, or relative `point` units.
95
97
  Point plans declare a project-wide velocity such as `20p/10d`. Analysis keeps
96
98
  the exact point result and reports the time conversion separately as a velocity
97
99
  forecast. Grammar version 3 also accepts an exact Fraction such as `1/3d`;
98
- versions 1 and 2 continue to accept Decimal duration tokens.
100
+ versions 1 and 2 continue to accept Decimal duration tokens. Grammar version 5
101
+ adds explicit task-owned work events and the `suspended` lifecycle state.
99
102
 
100
103
  ## Maintain a plan through the CLI
101
104
 
@@ -202,7 +205,7 @@ perttool gate add PLAN.pert APPROVAL NOW DONE \
202
205
  --expect-digest 'sha256:...'
203
206
  ```
204
207
 
205
- Generated Contract 5 projects carry this maintenance warning:
208
+ Generated Contract 6 source projects carry this maintenance warning:
206
209
 
207
210
  ```pert
208
211
  # Existing .pert plans should normally be maintained through perttool commands; direct DSL editing bypasses goal/DAG owner-confirmation checks.
@@ -233,6 +236,45 @@ perttool project migrate-unit PLAN.pert \
233
236
  Migration is not a `batch apply` member. Re-read and reanalyze the written
234
237
  candidate before making a separate mutation.
235
238
 
239
+ ### Task actuals and Git history
240
+
241
+ Grammar 5 records each lifecycle transition as a task state change and a
242
+ task-owned work event in one preview-first candidate. Event time is always an
243
+ explicit caller input; perttool does not substitute the system clock or Git
244
+ commit time.
245
+
246
+ ```sh
247
+ perttool task start PLAN.pert WORK \
248
+ --at 2026-07-29T09:00:00+09:00 --diff
249
+ perttool task suspend PLAN.pert WORK \
250
+ --at 2026-07-29T11:00:00+09:00 --reason "review" --diff
251
+ perttool task resume PLAN.pert WORK \
252
+ --at 2026-07-29T12:00:00+09:00 --diff
253
+ perttool task finish PLAN.pert WORK \
254
+ --at 2026-07-29T15:00:00+09:00 \
255
+ --active-time 5 --effort 6 --diff
256
+ ```
257
+
258
+ Use the ordinary governance, `--write`, and `--expect-digest` controls after
259
+ reviewing each candidate. `--active-time` is hours and `--effort` is
260
+ person-hours; suffix-free CLI values are normalized to `h` and `ph`.
261
+
262
+ History is a read-only first-parent Git reconstruction. It distinguishes
263
+ explicit actual event time from Git-recorded transition time and never changes
264
+ Git or declared project velocity:
265
+
266
+ ```sh
267
+ perttool project history PLAN.pert --task WORK --format json
268
+ perttool project observe-velocity PLAN.pert \
269
+ --task WORK --evidence declared --format json
270
+ ```
271
+
272
+ Observed candidates are evidence, not automatic project metadata changes.
273
+ Adoption, if desired, is a separate reviewed `project set --velocity` write.
274
+ See the [Contract 5-to-6 migration
275
+ guide](docs/process/cli-contract-6-migration.md) for schema and compatibility
276
+ details.
277
+
236
278
  ## Command map
237
279
 
238
280
  | Goal | Command |
@@ -243,13 +285,15 @@ candidate before making a separate mutation.
243
285
  | Canonically format it | `perttool document format <file>` |
244
286
  | Initialize a project | `perttool project init ...` |
245
287
  | Read project metadata | `perttool project show <file>` |
288
+ | Reconstruct task actuals | `perttool project history <file> ...` |
289
+ | Observe project performance | `perttool project observe-velocity <file> ...` |
246
290
  | Change project metadata | `perttool project set <file> ...` |
247
291
  | Migrate project units exactly | `perttool project migrate-unit <file> ...` |
248
292
  | Analyze schedules | `perttool dag analyze <file>` |
249
293
  | Select next work | `perttool dag next <file>` |
250
294
  | Remove completed history | `perttool dag advance <file>` |
251
295
  | Export or import Mermaid | `perttool dag render`, `perttool dag import` |
252
- | Maintain tasks | `perttool task add|set|remove|finish` |
296
+ | Maintain tasks | `perttool task add|set|remove|start|suspend|resume|finish` |
253
297
  | Maintain gates | `perttool gate add|set|remove` |
254
298
  | Maintain milestones | `perttool milestone add|set|remove` |
255
299
  | Maintain resources | `perttool resource add|set|remove` |
@@ -268,14 +312,18 @@ perttool guide editing --level detail --format json
268
312
 
269
313
  ## LLM and automation use
270
314
 
271
- Use `--format json` for machine consumers. Contract 5 consumers must check
272
- `cli_contract_version == 5`; consumers pinned to `0.3.0` must continue to
273
- require Contract 4. In both cases, check the result-specific `schema_version`
274
- before reading the rest of a result.
275
- A complete, known, non-truncated `Perttool.NextResult.v4` with temporal policy
315
+ Use `--format json` for machine consumers. Prepared `0.5.0` consumers must
316
+ check `cli_contract_version == 6`; consumers of published `0.4.0` must
317
+ continue to require Contract 5, and consumers pinned to `0.3.0` must require
318
+ Contract 4.
319
+ In every case, check the result-specific `schema_version` before reading the
320
+ rest of a result.
321
+ A complete, known, non-truncated `Perttool.NextResult.v5` with temporal policy
276
322
  `recommendation_v1_plus_release_gate` is required. Start only task IDs in
277
323
  `temporal.authority.startable_recommended_task_ids`; do not infer start
278
324
  authority from the raw recommended set, the text summary, or `ready` alone.
325
+ Suspended tasks are reported separately and require an explicit `task resume`;
326
+ they are not new-start recommendations.
279
327
 
280
328
  Mutation JSON returns the candidate text, unified diff, UTF-16 text edits,
281
329
  source digest, updated digest, diagnostics, and write result in one envelope.
@@ -286,6 +334,8 @@ diagnostics, and future or unavailable temporal eligibility must fail closed.
286
334
 
287
335
  - [Temporal and Unit Interface Contract (CLI Contract 4)](docs/specs/temporal-unit-interface.md)
288
336
  - [Owner-Aware Governance Interface Contract (CLI Contract 5)](docs/specs/governance-interface.md)
337
+ - [Project Actuals and Git History Contract (CLI Contract 6)](docs/specs/project-actuals.md)
338
+ - [Contract 5-to-6 migration](docs/process/cli-contract-6-migration.md)
289
339
  - [Contract 4-to-5 migration](docs/process/cli-contract-5-migration.md)
290
340
  - [Issue #4 governance implementation acceptance](docs/process/governance-acceptance.md)
291
341
  - [CLI Contract 3 compatibility baseline](docs/specs/cli-contract-3.md)
@@ -0,0 +1,101 @@
1
+ import type { Diagnostic, SourceSpan } from "../model/diagnostics.js";
2
+ import { type Rational } from "../model/rational.js";
3
+ import type { DeclarationNode, TargetDeclarationKind, WorkEventKind } from "../model/syntax.js";
4
+ import { type ActualWorkEvent } from "./source.js";
5
+ import type { TargetGrammar5ValidatedDocument } from "../semantic/target-validator.js";
6
+ export type TaskLifecycleState = "planned" | "active" | "blocked" | "suspended" | "done";
7
+ export type ActualsCoverage = "complete" | "open" | "finish_only" | "unrecorded" | "unavailable";
8
+ export interface LifecycleEventInput {
9
+ readonly id?: string;
10
+ readonly occurredAt: string;
11
+ readonly reason?: string;
12
+ readonly activeTime?: string;
13
+ readonly effort?: string;
14
+ }
15
+ export interface FinishActualsMutation {
16
+ readonly kind: "task.finish.actual";
17
+ readonly taskId: string;
18
+ readonly event: LifecycleEventInput;
19
+ }
20
+ export interface StartActualsMutation {
21
+ readonly kind: "task.start";
22
+ readonly taskId: string;
23
+ readonly event: LifecycleEventInput;
24
+ }
25
+ export interface SuspendActualsMutation {
26
+ readonly kind: "task.suspend";
27
+ readonly taskId: string;
28
+ readonly event: LifecycleEventInput;
29
+ }
30
+ export interface ResumeActualsMutation {
31
+ readonly kind: "task.resume";
32
+ readonly taskId: string;
33
+ readonly event: LifecycleEventInput;
34
+ }
35
+ export type LifecycleMutation = StartActualsMutation | SuspendActualsMutation | ResumeActualsMutation | FinishActualsMutation;
36
+ export type LifecycleMutationKind = LifecycleMutation["kind"];
37
+ interface NormalizedLifecycleEventBase {
38
+ readonly id: string;
39
+ readonly occurredAt: string;
40
+ }
41
+ export type NormalizedLifecycleMutationRequest = {
42
+ readonly kind: "task.start";
43
+ readonly taskId: string;
44
+ readonly event: NormalizedLifecycleEventBase;
45
+ } | {
46
+ readonly kind: "task.suspend";
47
+ readonly taskId: string;
48
+ readonly event: NormalizedLifecycleEventBase & {
49
+ readonly reason: string | null;
50
+ };
51
+ } | {
52
+ readonly kind: "task.resume";
53
+ readonly taskId: string;
54
+ readonly event: NormalizedLifecycleEventBase;
55
+ } | {
56
+ readonly kind: "task.finish.actual";
57
+ readonly taskId: string;
58
+ readonly event: NormalizedLifecycleEventBase & {
59
+ readonly activeTime: string | null;
60
+ readonly effort: string | null;
61
+ };
62
+ };
63
+ export type NormalizedFinishActualsRequest = Extract<NormalizedLifecycleMutationRequest, {
64
+ readonly kind: "task.finish.actual";
65
+ }>;
66
+ export type NormalizedStartActualsRequest = Extract<NormalizedLifecycleMutationRequest, {
67
+ readonly kind: "task.start";
68
+ }>;
69
+ export type NormalizedSuspendActualsRequest = Extract<NormalizedLifecycleMutationRequest, {
70
+ readonly kind: "task.suspend";
71
+ }>;
72
+ export type NormalizedResumeActualsRequest = Extract<NormalizedLifecycleMutationRequest, {
73
+ readonly kind: "task.resume";
74
+ }>;
75
+ export interface LifecycleMutationRequestNormalization {
76
+ readonly ok: boolean;
77
+ readonly request: NormalizedLifecycleMutationRequest | null;
78
+ readonly diagnostics: readonly Diagnostic[];
79
+ }
80
+ export interface FinishActualsRequestNormalization {
81
+ readonly ok: boolean;
82
+ readonly request: NormalizedFinishActualsRequest | null;
83
+ readonly diagnostics: readonly Diagnostic[];
84
+ }
85
+ export interface LifecycleReduction {
86
+ readonly ok: boolean;
87
+ readonly coverage: ActualsCoverage;
88
+ readonly state: "active" | "suspended" | "done" | null;
89
+ readonly derivedActiveTime: Rational | null;
90
+ readonly diagnostics: readonly Diagnostic[];
91
+ }
92
+ export declare function actualsDiagnostic(code: "PTACT-104" | "PTACT-105" | "PTACT-106" | "PTACT-107" | "PTACT-108", message: string, cause: string, entityId: string | null, span?: SourceSpan, data?: Readonly<Record<string, unknown>>): Diagnostic;
93
+ export declare function deriveWorkEventId(taskId: string, kind: WorkEventKind, canonicalOccurredAt: string): string;
94
+ export declare function normalizeLifecycleMutationRequest(input: unknown): LifecycleMutationRequestNormalization;
95
+ export declare function normalizeFinishActualsRequest(input: unknown): FinishActualsRequestNormalization;
96
+ export declare function reduceTaskLifecycle(events: readonly ActualWorkEvent[]): LifecycleReduction;
97
+ export declare function taskStatus(task: DeclarationNode<TargetDeclarationKind>): TaskLifecycleState;
98
+ export declare function taskStatusSpan(task: DeclarationNode<TargetDeclarationKind>): SourceSpan;
99
+ export declare function validateStoredLifecycleState(validated: TargetGrammar5ValidatedDocument): readonly Diagnostic[];
100
+ export {};
101
+ //# sourceMappingURL=lifecycle.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/actuals/lifecycle.ts"],"names":[],"mappings":"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"}