perttool 0.4.0 → 0.5.1

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 (246) hide show
  1. package/CHANGELOG.md +63 -1
  2. package/README.md +107 -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 +309 -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 +328 -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 +56 -0
  142. package/dist/history/git-probe.d.ts.map +1 -0
  143. package/dist/history/git-probe.js +574 -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 +21 -10
  154. package/dist/index.d.ts.map +1 -1
  155. package/dist/index.js +10 -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/schema/registry.d.ts +36 -0
  214. package/dist/schema/registry.d.ts.map +1 -0
  215. package/dist/schema/registry.js +156 -0
  216. package/dist/schema/registry.js.map +1 -0
  217. package/dist/semantic/target-validator.d.ts +13 -2
  218. package/dist/semantic/target-validator.d.ts.map +1 -1
  219. package/dist/semantic/target-validator.js +46 -2
  220. package/dist/semantic/target-validator.js.map +1 -1
  221. package/dist/semantic/validator.d.ts +4 -1
  222. package/dist/semantic/validator.d.ts.map +1 -1
  223. package/dist/semantic/validator.js +152 -6
  224. package/dist/semantic/validator.js.map +1 -1
  225. package/dist/version.d.ts +1 -1
  226. package/dist/version.js +1 -1
  227. package/package.json +7 -3
  228. package/schemas/Perttool.AgentGuidanceResult.v1.schema.json +152 -0
  229. package/schemas/Perttool.AnalysisResult.v4.schema.json +124 -0
  230. package/schemas/Perttool.CheckResult.v3.schema.json +159 -0
  231. package/schemas/Perttool.CliError.v1.schema.json +83 -0
  232. package/schemas/Perttool.CommandHelpResult.v1.schema.json +165 -0
  233. package/schemas/Perttool.Common.v1.schema.json +508 -0
  234. package/schemas/Perttool.ExportResult.v1.schema.json +96 -0
  235. package/schemas/Perttool.FormatResult.v1.schema.json +82 -0
  236. package/schemas/Perttool.GuideResult.v1.schema.json +104 -0
  237. package/schemas/Perttool.ImportResult.v1.schema.json +111 -0
  238. package/schemas/Perttool.InitResult.v1.schema.json +70 -0
  239. package/schemas/Perttool.MutationResult.v3.schema.json +143 -0
  240. package/schemas/Perttool.NextResult.v5.schema.json +139 -0
  241. package/schemas/Perttool.OverrideDecision.v1.schema.json +170 -0
  242. package/schemas/Perttool.ProjectHistoryResult.v1.schema.json +139 -0
  243. package/schemas/Perttool.ProjectResult.v3.schema.json +144 -0
  244. package/schemas/Perttool.SchemaResult.v1.schema.json +84 -0
  245. package/schemas/Perttool.UnitMigrationResult.v3.schema.json +205 -0
  246. package/schemas/Perttool.VelocityObservationResult.v1.schema.json +102 -0
package/CHANGELOG.md CHANGED
@@ -4,6 +4,66 @@ 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.1] - 2026-07-30
8
+
9
+ Compatible CLI Contract 6 and Grammar 5 beta patch. This version adds
10
+ machine-readable result artifacts and corrects Git 2.54 UTC commit-time
11
+ handling without changing existing result identities or payload meanings.
12
+
13
+ ### Added
14
+
15
+ - Added bundled Draft 2020-12 artifacts for every active Contract 6 command
16
+ result and public `Perttool.OverrideDecision.v1`, with a closed public
17
+ catalog, `perttool schema`, package-root lookup APIs, and isolated package
18
+ validation.
19
+
20
+ ### Fixed
21
+
22
+ - Accepted the strict ISO `Z` UTC form emitted by Git 2.54 for `%cI` commit
23
+ metadata while retaining fixed-offset validation.
24
+
25
+ ## [0.5.0] - 2026-07-29
26
+
27
+ Contract 6 beta release. This version atomically publishes Grammar 5,
28
+ explicit task lifecycle evidence, read-only Git history and velocity
29
+ observation, and the English repository baseline. It intentionally changes
30
+ every CLI JSON envelope and several result identities while retaining
31
+ suffix-free `0.x.x` beta product maturity.
32
+
33
+ ### Added
34
+
35
+ - Activated Grammar 5 task-owned work events and preview-first
36
+ `task start|suspend|resume` plus eventful `task finish` with explicit event
37
+ time, exact active time, exact person effort, deterministic event identity,
38
+ governance, and safe-write controls.
39
+ - Added read-only first-parent `project history` and
40
+ `project observe-velocity`, including explicit-event reconstruction,
41
+ qualified Git-recorded transitions, exact task summaries, and separate
42
+ elapsed-hour, active-date, effort-productivity, and recorded-evidence
43
+ candidates.
44
+ - Added public actuals/history/observation Core exports, Contract 6 command
45
+ discovery and Guide topics, Grammar 5 examples, and isolated installed
46
+ lifecycle/history/observation checks.
47
+
48
+ ### Changed
49
+
50
+ - Activated CLI Contract 6 in the current source. Every JSON envelope now
51
+ reports `cli_contract_version=6`; check, analysis, next, mutation/advance,
52
+ and unit migration use result versions 3, 4, 5, 3, and 3 respectively.
53
+ - Added suspended-state analysis and `groups.suspended`, while retaining the
54
+ Recommendation version 1 ranking and
55
+ `recommendation_v1_plus_release_gate` start-authority policy.
56
+ - Extended exact unit migration through Grammar 5
57
+ `work_event.planned_value` without changing event time, active time, effort,
58
+ or declared velocity. The prior `0.4.0` artifact remains available as the
59
+ Grammar 4 and CLI Contract 5 compatibility pin.
60
+
61
+ ### Fixed
62
+
63
+ - Merged adjacent zero-length task-status and work-event insertions so a
64
+ lifecycle mutation can atomically start a task whose declaration ends at
65
+ end of file.
66
+
7
67
  ## [0.4.0] - 2026-07-28
8
68
 
9
69
  Contract 5 beta release. This version atomically publishes Grammar 4 and
@@ -174,7 +234,9 @@ First public development preview. Intended to evaluate the DSL and CLI, read-onl
174
234
  - Not published to the npm registry; use the GitHub Release asset
175
235
  - Requires Node.js 24 or later
176
236
 
177
- [Unreleased]: https://github.com/mako10k/perttool/compare/v0.4.0...HEAD
237
+ [Unreleased]: https://github.com/mako10k/perttool/compare/v0.5.1...HEAD
238
+ [0.5.1]: https://github.com/mako10k/perttool/compare/v0.5.0...v0.5.1
239
+ [0.5.0]: https://github.com/mako10k/perttool/compare/v0.4.0...v0.5.0
178
240
  [0.4.0]: https://github.com/mako10k/perttool/compare/v0.3.0...v0.4.0
179
241
  [0.3.0]: https://github.com/mako10k/perttool/compare/v0.2.0...v0.3.0
180
242
  [0.2.0]: https://github.com/mako10k/perttool/compare/v0.1.0...v0.2.0
package/README.md CHANGED
@@ -5,54 +5,55 @@ 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
+ Version `0.5.1` beta 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. It adds
11
+ Draft 2020-12 artifacts for every active Contract 6 result and the public
12
+ OverrideDecision result, plus Git 2.54 UTC compatibility. npm `beta` resolves
13
+ to `0.5.1`, while `latest` remains on Contract 5 `0.4.0`. Beta releases may
14
+ contain breaking CLI or schema changes. Version `0.5.1` requires Node.js 22
15
+ or later. The compatible pre-schema Contract 6 artifact remains available by
16
+ pinning `0.5.0`; Contract 5, Contract 4, and Contract 3 remain available by
17
+ pinning `0.4.0`, `0.3.0`, and `0.2.0`, respectively.
14
18
 
15
19
  ## Run without installing
16
20
 
17
- Use `npx` for an occasional invocation and select Contract 5 explicitly:
21
+ Use `npx` for an occasional invocation and select Contract 6 explicitly:
18
22
 
19
23
  ```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
24
+ npx --yes --package=perttool@0.5.1 -- perttool --version
25
+ npx --yes --package=perttool@0.5.1 -- perttool document check PLAN.pert
26
+ npx --yes --package=perttool@0.5.1 -- perttool dag next PLAN.pert --format json
27
+ npx --yes --package=perttool@0.5.1 -- perttool project history PLAN.pert --format json
24
28
  ```
25
29
 
26
30
  The equivalent explicit `npm exec` form is:
27
31
 
28
32
  ```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
33
+ npm exec --yes --package=perttool@0.5.1 -- perttool --version
34
+ npm exec --yes --package=perttool@0.5.1 -- perttool document check PLAN.pert
35
+ npm exec --yes --package=perttool@0.5.1 -- perttool dag analyze PLAN.pert
36
+ npm exec --yes --package=perttool@0.5.1 -- perttool project history PLAN.pert --format json
33
37
  ```
34
38
 
35
39
  `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.
40
+ cache. Pinning `0.4.0` selects Contract 5 and therefore omits Grammar 5
41
+ lifecycle and history; `0.3.0` selects Contract 4, and `0.2.0` selects
42
+ Contract 3.
40
43
 
41
44
  ## Install
42
45
 
43
46
  Install the CLI globally when it is used regularly:
44
47
 
45
48
  ```sh
46
- npm install --global perttool@0.4.0
49
+ npm install --global perttool@0.5.1
47
50
  perttool --version
48
51
  ```
49
52
 
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`.
53
+ npm `beta` resolves to Contract 6 `0.5.1`, while `latest` remains on
54
+ Contract 5 `0.4.0`. The prior Contract 6 artifact remains available as
55
+ `perttool@0.5.0`; Contract 5, Contract 4, and Contract 3 remain available as
56
+ exact pins `perttool@0.4.0`, `perttool@0.3.0`, and `perttool@0.2.0`.
56
57
 
57
58
  ## Plan files
58
59
 
@@ -95,7 +96,8 @@ Task duration can use deterministic `day`, `hour`, or relative `point` units.
95
96
  Point plans declare a project-wide velocity such as `20p/10d`. Analysis keeps
96
97
  the exact point result and reports the time conversion separately as a velocity
97
98
  forecast. Grammar version 3 also accepts an exact Fraction such as `1/3d`;
98
- versions 1 and 2 continue to accept Decimal duration tokens.
99
+ versions 1 and 2 continue to accept Decimal duration tokens. Grammar version 5
100
+ adds explicit task-owned work events and the `suspended` lifecycle state.
99
101
 
100
102
  ## Maintain a plan through the CLI
101
103
 
@@ -202,7 +204,7 @@ perttool gate add PLAN.pert APPROVAL NOW DONE \
202
204
  --expect-digest 'sha256:...'
203
205
  ```
204
206
 
205
- Generated Contract 5 projects carry this maintenance warning:
207
+ Generated Contract 6 source projects carry this maintenance warning:
206
208
 
207
209
  ```pert
208
210
  # Existing .pert plans should normally be maintained through perttool commands; direct DSL editing bypasses goal/DAG owner-confirmation checks.
@@ -233,23 +235,65 @@ perttool project migrate-unit PLAN.pert \
233
235
  Migration is not a `batch apply` member. Re-read and reanalyze the written
234
236
  candidate before making a separate mutation.
235
237
 
238
+ ### Task actuals and Git history
239
+
240
+ Grammar 5 records each lifecycle transition as a task state change and a
241
+ task-owned work event in one preview-first candidate. Event time is always an
242
+ explicit caller input; perttool does not substitute the system clock or Git
243
+ commit time.
244
+
245
+ ```sh
246
+ perttool task start PLAN.pert WORK \
247
+ --at 2026-07-29T09:00:00+09:00 --diff
248
+ perttool task suspend PLAN.pert WORK \
249
+ --at 2026-07-29T11:00:00+09:00 --reason "review" --diff
250
+ perttool task resume PLAN.pert WORK \
251
+ --at 2026-07-29T12:00:00+09:00 --diff
252
+ perttool task finish PLAN.pert WORK \
253
+ --at 2026-07-29T15:00:00+09:00 \
254
+ --active-time 5 --effort 6 --diff
255
+ ```
256
+
257
+ Use the ordinary governance, `--write`, and `--expect-digest` controls after
258
+ reviewing each candidate. `--active-time` is hours and `--effort` is
259
+ person-hours; suffix-free CLI values are normalized to `h` and `ph`.
260
+
261
+ History is a read-only first-parent Git reconstruction. It distinguishes
262
+ explicit actual event time from Git-recorded transition time and never changes
263
+ Git or declared project velocity:
264
+
265
+ ```sh
266
+ perttool project history PLAN.pert --task WORK --format json
267
+ perttool project observe-velocity PLAN.pert \
268
+ --task WORK --evidence declared --format json
269
+ ```
270
+
271
+ Observed candidates are evidence, not automatic project metadata changes.
272
+ Adoption, if desired, is a separate reviewed `project set --velocity` write.
273
+ See the [Contract 5-to-6 migration
274
+ guide](docs/process/cli-contract-6-migration.md) for schema and compatibility
275
+ details.
276
+
236
277
  ## Command map
237
278
 
238
279
  | Goal | Command |
239
280
  | --- | --- |
240
281
  | Discover commands | `perttool help [resource [action]]` |
282
+ | Discover or read JSON Schemas | `perttool schema [schema-id]` |
241
283
  | Read domain guidance | `perttool guide [topic [subtopic]]` |
242
284
  | Validate a document | `perttool document check <file>` |
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` |
@@ -263,19 +307,44 @@ domain concepts. Both run without a document:
263
307
  ```sh
264
308
  perttool task set --help
265
309
  perttool help dag next --format json
310
+ perttool schema --format json
311
+ perttool schema Perttool.NextResult.v5 --format json
266
312
  perttool guide editing --level detail --format json
267
313
  ```
268
314
 
315
+ ### JSON Schema artifacts
316
+
317
+ `perttool schema --format json` returns the complete result-schema catalog.
318
+ Supplying a schema identity returns its Draft 2020-12 artifact in the
319
+ `schema` field of `Perttool.SchemaResult.v1`:
320
+
321
+ ```sh
322
+ perttool schema Perttool.CheckResult.v3 --format json
323
+ ```
324
+
325
+ Packed installations also expose each artifact at
326
+ `perttool/schemas/<schema-id>.schema.json`; relative references resolve
327
+ against the bundled `Perttool.Common.v1.schema.json`. The stable `$id` is an
328
+ identifier only: validation does not require network access. Consumers must
329
+ select compatibility from each result's `schema_version`, not from
330
+ `tool_version`. See the
331
+ [JSON Schema Artifact Contract](docs/specs/json-schema.md) for the complete
332
+ 18-result inventory and versioning rules.
333
+
269
334
  ## LLM and automation use
270
335
 
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
336
+ Use `--format json` for machine consumers. `0.5.1` and `0.5.0` consumers must
337
+ check `cli_contract_version == 6`; consumers pinned to `0.4.0` must continue
338
+ to require Contract 5, and consumers pinned to `0.3.0` must require Contract
339
+ 4. Bundled machine-readable result artifacts require `0.5.1`.
340
+ In every case, check the result-specific `schema_version` before reading the
341
+ rest of a result.
342
+ A complete, known, non-truncated `Perttool.NextResult.v5` with temporal policy
276
343
  `recommendation_v1_plus_release_gate` is required. Start only task IDs in
277
344
  `temporal.authority.startable_recommended_task_ids`; do not infer start
278
345
  authority from the raw recommended set, the text summary, or `ready` alone.
346
+ Suspended tasks are reported separately and require an explicit `task resume`;
347
+ they are not new-start recommendations.
279
348
 
280
349
  Mutation JSON returns the candidate text, unified diff, UTF-16 text edits,
281
350
  source digest, updated digest, diagnostics, and write result in one envelope.
@@ -286,6 +355,10 @@ diagnostics, and future or unavailable temporal eligibility must fail closed.
286
355
 
287
356
  - [Temporal and Unit Interface Contract (CLI Contract 4)](docs/specs/temporal-unit-interface.md)
288
357
  - [Owner-Aware Governance Interface Contract (CLI Contract 5)](docs/specs/governance-interface.md)
358
+ - [Project Actuals and Git History Contract (CLI Contract 6)](docs/specs/project-actuals.md)
359
+ - [JSON Schema Artifact Contract](docs/specs/json-schema.md)
360
+ - [JSON Schema source acceptance](docs/process/json-schema-acceptance.md)
361
+ - [Contract 5-to-6 migration](docs/process/cli-contract-6-migration.md)
289
362
  - [Contract 4-to-5 migration](docs/process/cli-contract-5-migration.md)
290
363
  - [Issue #4 governance implementation acceptance](docs/process/governance-acceptance.md)
291
364
  - [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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"}