perttool 0.2.0 → 0.4.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 (259) hide show
  1. package/CHANGELOG.md +81 -1
  2. package/README.md +121 -28
  3. package/dist/analysis/temporal-deadline.d.ts +59 -0
  4. package/dist/analysis/temporal-deadline.d.ts.map +1 -0
  5. package/dist/analysis/temporal-deadline.js +387 -0
  6. package/dist/analysis/temporal-deadline.js.map +1 -0
  7. package/dist/analysis/temporal-precedence.d.ts +45 -0
  8. package/dist/analysis/temporal-precedence.d.ts.map +1 -0
  9. package/dist/analysis/temporal-precedence.js +123 -0
  10. package/dist/analysis/temporal-precedence.js.map +1 -0
  11. package/dist/analysis/temporal-resource.d.ts +66 -0
  12. package/dist/analysis/temporal-resource.d.ts.map +1 -0
  13. package/dist/analysis/temporal-resource.js +292 -0
  14. package/dist/analysis/temporal-resource.js.map +1 -0
  15. package/dist/application/check.d.ts +16 -0
  16. package/dist/application/check.d.ts.map +1 -1
  17. package/dist/application/check.js +51 -0
  18. package/dist/application/check.js.map +1 -1
  19. package/dist/application/contract4.d.ts +17 -0
  20. package/dist/application/contract4.d.ts.map +1 -0
  21. package/dist/application/contract4.js +27 -0
  22. package/dist/application/contract4.js.map +1 -0
  23. package/dist/application/contract5-governance.d.ts +8 -0
  24. package/dist/application/contract5-governance.d.ts.map +1 -0
  25. package/dist/application/contract5-governance.js +12 -0
  26. package/dist/application/contract5-governance.js.map +1 -0
  27. package/dist/application/init.d.ts +3 -11
  28. package/dist/application/init.d.ts.map +1 -1
  29. package/dist/application/init.js +16 -129
  30. package/dist/application/init.js.map +1 -1
  31. package/dist/application/mutate.d.ts +19 -0
  32. package/dist/application/mutate.d.ts.map +1 -1
  33. package/dist/application/mutate.js +34 -16
  34. package/dist/application/mutate.js.map +1 -1
  35. package/dist/application/next.d.ts +2 -0
  36. package/dist/application/next.d.ts.map +1 -1
  37. package/dist/application/next.js +7 -1
  38. package/dist/application/next.js.map +1 -1
  39. package/dist/application/project.d.ts +4 -22
  40. package/dist/application/project.d.ts.map +1 -1
  41. package/dist/application/project.js +3 -51
  42. package/dist/application/project.js.map +1 -1
  43. package/dist/application/target-check.d.ts +34 -0
  44. package/dist/application/target-check.d.ts.map +1 -0
  45. package/dist/application/target-check.js +90 -0
  46. package/dist/application/target-check.js.map +1 -0
  47. package/dist/application/target-governance-init.d.ts +36 -0
  48. package/dist/application/target-governance-init.d.ts.map +1 -0
  49. package/dist/application/target-governance-init.js +185 -0
  50. package/dist/application/target-governance-init.js.map +1 -0
  51. package/dist/application/target-governance-mutation.d.ts +20 -0
  52. package/dist/application/target-governance-mutation.d.ts.map +1 -0
  53. package/dist/application/target-governance-mutation.js +175 -0
  54. package/dist/application/target-governance-mutation.js.map +1 -0
  55. package/dist/application/target-governance-project.d.ts +34 -0
  56. package/dist/application/target-governance-project.d.ts.map +1 -0
  57. package/dist/application/target-governance-project.js +80 -0
  58. package/dist/application/target-governance-project.js.map +1 -0
  59. package/dist/application/target-governance-projection.d.ts +18 -0
  60. package/dist/application/target-governance-projection.d.ts.map +1 -0
  61. package/dist/application/target-governance-projection.js +248 -0
  62. package/dist/application/target-governance-projection.js.map +1 -0
  63. package/dist/application/target-governance-write.d.ts +17 -0
  64. package/dist/application/target-governance-write.d.ts.map +1 -0
  65. package/dist/application/target-governance-write.js +55 -0
  66. package/dist/application/target-governance-write.js.map +1 -0
  67. package/dist/application/target-grammar-boundary.d.ts +22 -0
  68. package/dist/application/target-grammar-boundary.d.ts.map +1 -0
  69. package/dist/application/target-grammar-boundary.js +91 -0
  70. package/dist/application/target-grammar-boundary.js.map +1 -0
  71. package/dist/application/target-mutate.d.ts +10 -0
  72. package/dist/application/target-mutate.d.ts.map +1 -0
  73. package/dist/application/target-mutate.js +81 -0
  74. package/dist/application/target-mutate.js.map +1 -0
  75. package/dist/application/target-project.d.ts +28 -0
  76. package/dist/application/target-project.d.ts.map +1 -0
  77. package/dist/application/target-project.js +60 -0
  78. package/dist/application/target-project.js.map +1 -0
  79. package/dist/application/target-temporal-analysis.d.ts +140 -0
  80. package/dist/application/target-temporal-analysis.d.ts.map +1 -0
  81. package/dist/application/target-temporal-analysis.js +414 -0
  82. package/dist/application/target-temporal-analysis.js.map +1 -0
  83. package/dist/application/target-temporal-input.d.ts +86 -0
  84. package/dist/application/target-temporal-input.d.ts.map +1 -0
  85. package/dist/application/target-temporal-input.js +240 -0
  86. package/dist/application/target-temporal-input.js.map +1 -0
  87. package/dist/application/target-unit-migration-candidate.d.ts +60 -0
  88. package/dist/application/target-unit-migration-candidate.d.ts.map +1 -0
  89. package/dist/application/target-unit-migration-candidate.js +294 -0
  90. package/dist/application/target-unit-migration-candidate.js.map +1 -0
  91. package/dist/application/target-unit-migration-request.d.ts +35 -0
  92. package/dist/application/target-unit-migration-request.d.ts.map +1 -0
  93. package/dist/application/target-unit-migration-request.js +70 -0
  94. package/dist/application/target-unit-migration-request.js.map +1 -0
  95. package/dist/application/target-unit-migration-result.d.ts +66 -0
  96. package/dist/application/target-unit-migration-result.d.ts.map +1 -0
  97. package/dist/application/target-unit-migration-result.js +86 -0
  98. package/dist/application/target-unit-migration-result.js.map +1 -0
  99. package/dist/application/unit-migration.d.ts +16 -0
  100. package/dist/application/unit-migration.d.ts.map +1 -0
  101. package/dist/application/unit-migration.js +11 -0
  102. package/dist/application/unit-migration.js.map +1 -0
  103. package/dist/cli.js +383 -132
  104. package/dist/cli.js.map +1 -1
  105. package/dist/command/discovery.d.ts +3 -3
  106. package/dist/command/discovery.d.ts.map +1 -1
  107. package/dist/command/discovery.js +149 -22
  108. package/dist/command/discovery.js.map +1 -1
  109. package/dist/command/registry.d.ts +8 -2
  110. package/dist/command/registry.d.ts.map +1 -1
  111. package/dist/command/registry.js +14 -1
  112. package/dist/command/registry.js.map +1 -1
  113. package/dist/command/target-governance-discovery.d.ts +31 -0
  114. package/dist/command/target-governance-discovery.d.ts.map +1 -0
  115. package/dist/command/target-governance-discovery.js +390 -0
  116. package/dist/command/target-governance-discovery.js.map +1 -0
  117. package/dist/command/target-governance-usage.d.ts +22 -0
  118. package/dist/command/target-governance-usage.d.ts.map +1 -0
  119. package/dist/command/target-governance-usage.js +116 -0
  120. package/dist/command/target-governance-usage.js.map +1 -0
  121. package/dist/command/usage.d.ts +2 -0
  122. package/dist/command/usage.d.ts.map +1 -1
  123. package/dist/command/usage.js +44 -26
  124. package/dist/command/usage.js.map +1 -1
  125. package/dist/conversion/mermaid-import.d.ts.map +1 -1
  126. package/dist/conversion/mermaid-import.js +3 -2
  127. package/dist/conversion/mermaid-import.js.map +1 -1
  128. package/dist/conversion/mermaid.d.ts.map +1 -1
  129. package/dist/conversion/mermaid.js +27 -0
  130. package/dist/conversion/mermaid.js.map +1 -1
  131. package/dist/formatter/source-formatter.d.ts +12 -0
  132. package/dist/formatter/source-formatter.d.ts.map +1 -1
  133. package/dist/formatter/source-formatter.js +59 -6
  134. package/dist/formatter/source-formatter.js.map +1 -1
  135. package/dist/formatter/target-source-formatter.d.ts +9 -0
  136. package/dist/formatter/target-source-formatter.d.ts.map +1 -0
  137. package/dist/formatter/target-source-formatter.js +52 -0
  138. package/dist/formatter/target-source-formatter.js.map +1 -0
  139. package/dist/governance/authority.d.ts +21 -0
  140. package/dist/governance/authority.d.ts.map +1 -0
  141. package/dist/governance/authority.js +206 -0
  142. package/dist/governance/authority.js.map +1 -0
  143. package/dist/governance/guidance.d.ts +2 -0
  144. package/dist/governance/guidance.d.ts.map +1 -0
  145. package/dist/governance/guidance.js +2 -0
  146. package/dist/governance/guidance.js.map +1 -0
  147. package/dist/governance/source.d.ts +37 -0
  148. package/dist/governance/source.d.ts.map +1 -0
  149. package/dist/governance/source.js +103 -0
  150. package/dist/governance/source.js.map +1 -0
  151. package/dist/governance/types.d.ts +41 -0
  152. package/dist/governance/types.d.ts.map +1 -0
  153. package/dist/governance/types.js +2 -0
  154. package/dist/governance/types.js.map +1 -0
  155. package/dist/help/guide.d.ts +8 -5
  156. package/dist/help/guide.d.ts.map +1 -1
  157. package/dist/help/guide.js +1 -1
  158. package/dist/help/guide.js.map +1 -1
  159. package/dist/help/registry.d.ts.map +1 -1
  160. package/dist/help/registry.js +124 -13
  161. package/dist/help/registry.js.map +1 -1
  162. package/dist/help/target-governance-guide.d.ts +10 -0
  163. package/dist/help/target-governance-guide.d.ts.map +1 -0
  164. package/dist/help/target-governance-guide.js +57 -0
  165. package/dist/help/target-governance-guide.js.map +1 -0
  166. package/dist/index.d.ts +25 -17
  167. package/dist/index.d.ts.map +1 -1
  168. package/dist/index.js +8 -8
  169. package/dist/index.js.map +1 -1
  170. package/dist/io/safe-write.d.ts +11 -0
  171. package/dist/io/safe-write.d.ts.map +1 -1
  172. package/dist/io/safe-write.js +40 -10
  173. package/dist/io/safe-write.js.map +1 -1
  174. package/dist/io/target-safe-write.d.ts +10 -0
  175. package/dist/io/target-safe-write.d.ts.map +1 -0
  176. package/dist/io/target-safe-write.js +51 -0
  177. package/dist/io/target-safe-write.js.map +1 -0
  178. package/dist/migration/conversion.d.ts +40 -0
  179. package/dist/migration/conversion.d.ts.map +1 -0
  180. package/dist/migration/conversion.js +106 -0
  181. package/dist/migration/conversion.js.map +1 -0
  182. package/dist/migration/grammar-boundary.d.ts +20 -0
  183. package/dist/migration/grammar-boundary.d.ts.map +1 -0
  184. package/dist/migration/grammar-boundary.js +95 -0
  185. package/dist/migration/grammar-boundary.js.map +1 -0
  186. package/dist/migration/request.d.ts +79 -0
  187. package/dist/migration/request.d.ts.map +1 -0
  188. package/dist/migration/request.js +308 -0
  189. package/dist/migration/request.js.map +1 -0
  190. package/dist/model/calendar-arithmetic.d.ts +46 -0
  191. package/dist/model/calendar-arithmetic.d.ts.map +1 -0
  192. package/dist/model/calendar-arithmetic.js +236 -0
  193. package/dist/model/calendar-arithmetic.js.map +1 -0
  194. package/dist/model/calendar.d.ts +22 -0
  195. package/dist/model/calendar.d.ts.map +1 -0
  196. package/dist/model/calendar.js +83 -0
  197. package/dist/model/calendar.js.map +1 -0
  198. package/dist/model/declaration-fields.d.ts +22 -0
  199. package/dist/model/declaration-fields.d.ts.map +1 -0
  200. package/dist/model/declaration-fields.js +72 -0
  201. package/dist/model/declaration-fields.js.map +1 -0
  202. package/dist/model/exact-duration-source.d.ts +10 -0
  203. package/dist/model/exact-duration-source.d.ts.map +1 -0
  204. package/dist/model/exact-duration-source.js +69 -0
  205. package/dist/model/exact-duration-source.js.map +1 -0
  206. package/dist/model/rational.d.ts +2 -2
  207. package/dist/model/rational.d.ts.map +1 -1
  208. package/dist/model/rational.js +3 -1
  209. package/dist/model/rational.js.map +1 -1
  210. package/dist/model/syntax.d.ts +9 -2
  211. package/dist/model/syntax.d.ts.map +1 -1
  212. package/dist/model/syntax.js +20 -4
  213. package/dist/model/syntax.js.map +1 -1
  214. package/dist/model/target-calendar.d.ts +25 -0
  215. package/dist/model/target-calendar.d.ts.map +1 -0
  216. package/dist/model/target-calendar.js +56 -0
  217. package/dist/model/target-calendar.js.map +1 -0
  218. package/dist/mutation/advance.d.ts +11 -0
  219. package/dist/mutation/advance.d.ts.map +1 -1
  220. package/dist/mutation/advance.js +37 -7
  221. package/dist/mutation/advance.js.map +1 -1
  222. package/dist/mutation/milestone.d.ts +10 -1
  223. package/dist/mutation/milestone.d.ts.map +1 -1
  224. package/dist/mutation/milestone.js +77 -21
  225. package/dist/mutation/milestone.js.map +1 -1
  226. package/dist/mutation/project.d.ts +11 -1
  227. package/dist/mutation/project.d.ts.map +1 -1
  228. package/dist/mutation/project.js +117 -11
  229. package/dist/mutation/project.js.map +1 -1
  230. package/dist/mutation/target-types.d.ts +59 -0
  231. package/dist/mutation/target-types.d.ts.map +1 -0
  232. package/dist/mutation/target-types.js +2 -0
  233. package/dist/mutation/target-types.js.map +1 -0
  234. package/dist/mutation/task.d.ts +12 -1
  235. package/dist/mutation/task.d.ts.map +1 -1
  236. package/dist/mutation/task.js +108 -49
  237. package/dist/mutation/task.js.map +1 -1
  238. package/dist/mutation/types.d.ts +16 -3
  239. package/dist/mutation/types.d.ts.map +1 -1
  240. package/dist/parser/document-parser.d.ts +21 -0
  241. package/dist/parser/document-parser.d.ts.map +1 -1
  242. package/dist/parser/document-parser.js +197 -38
  243. package/dist/parser/document-parser.js.map +1 -1
  244. package/dist/recommendation/override-types.d.ts +2 -2
  245. package/dist/recommendation/override.d.ts +2 -2
  246. package/dist/recommendation/override.d.ts.map +1 -1
  247. package/dist/recommendation/override.js +49 -12
  248. package/dist/recommendation/override.js.map +1 -1
  249. package/dist/semantic/target-validator.d.ts +46 -0
  250. package/dist/semantic/target-validator.d.ts.map +1 -0
  251. package/dist/semantic/target-validator.js +130 -0
  252. package/dist/semantic/target-validator.js.map +1 -0
  253. package/dist/semantic/validator.d.ts +3 -0
  254. package/dist/semantic/validator.d.ts.map +1 -1
  255. package/dist/semantic/validator.js +78 -5
  256. package/dist/semantic/validator.js.map +1 -1
  257. package/dist/version.d.ts +1 -1
  258. package/dist/version.js +1 -1
  259. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,84 @@ This project records its notable changes here. The format is based on [Keep a Ch
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.4.0] - 2026-07-28
8
+
9
+ Contract 5 beta release. This version atomically publishes Grammar 4 and
10
+ owner-aware goal and DAG mutation governance. It intentionally changes every
11
+ CLI JSON envelope and the project and mutation result identities while
12
+ retaining suffix-free `0.x.x` beta product maturity.
13
+
14
+ ### Added
15
+
16
+ - Added declared and effective goal/DAG owners and delegates, digest-bound
17
+ pre-change governance snapshots, deterministic actual-change
18
+ classification, normalized caller assertions, and stable pre-change
19
+ authority decisions.
20
+ - Added owner-aware persistent direct, batch, and advance operations,
21
+ `Perttool.GovernanceDecision.v1`, PTGOV diagnostics, generated direct-edit
22
+ guidance, and the Contract 5 editing Guide.
23
+
24
+ ### Changed
25
+
26
+ - Changed every CLI JSON envelope to `cli_contract_version=5`, project
27
+ metadata to `Perttool.ProjectResult.v3`, and mutation and advance results to
28
+ `Perttool.MutationResult.v2` with an embedded governance decision.
29
+ - Persistent goal or DAG changes now require `--actor`. An effective owner or
30
+ delegate has direct authority; another actor must supply repeatable
31
+ `--accepted-by-owner` caller assertions for every affected effective owner.
32
+ - Retained Grammar 1/2/3 compatibility through effective default owner
33
+ `user`, the complete Contract 4 temporal/deadline/unit-migration surface,
34
+ and NextResult v4 normal start authority.
35
+ - Accepted the `perttool@0.3.0` Contract 4 beta and promoted it to npm
36
+ `latest` through a separate, explicitly authorized post-acceptance dist-tag
37
+ operation. npm `beta` and `latest` now resolve to `0.3.0`; product maturity
38
+ remains beta.
39
+
40
+ ## [0.3.0] - 2026-07-26
41
+
42
+ Contract 4 beta release. This version atomically publishes temporal and
43
+ deadline-aware planning, exact unit migration, and Grammar 3. It intentionally
44
+ changes public result identities and extends the CLI surface while retaining
45
+ suffix-free `0.x.x` beta product maturity.
46
+
47
+ ### Added
48
+
49
+ - Added Grammar 2 project `as_of`, milestone `deadline`, and task
50
+ `not_before`/`deadline` fields, plus Grammar 3 exact reduced Fraction
51
+ Durations alongside ordinary Decimals.
52
+ - Added exact release-aware precedence and heuristic resource schedules,
53
+ deterministic calendar projection, and separate task, milestone, and
54
+ project deadline evidence in `Perttool.AnalysisResult.v3`.
55
+ - Added preview-first `project migrate-unit` with complete Duration inventory,
56
+ exact Point/hour/day conversion, Decimal-or-Fraction output, coordinated
57
+ grammar upgrades, velocity disposition, no-op/repeat behavior, qualified
58
+ inverse results, and digest-locked safe writes through
59
+ `Perttool.UnitMigrationResult.v2`.
60
+
61
+ ### Changed
62
+
63
+ - Activated CLI Contract 4 through one 28-command registry that drives
64
+ dispatch, option validation, text/JSON help, structured recovery, temporal
65
+ entity mutation, Guide, README, and installed-package behavior.
66
+ - Replaced the public check, project, analysis, and next projections with
67
+ their accepted Contract 4 identities. `Perttool.NextResult.v4` preserves
68
+ Recommendation v1 ranking and adds fail-closed temporal start authority;
69
+ temporal eligibility gates the recommended set without substituting the
70
+ heuristic scheduler's runnable set.
71
+ - Extended the isolated installed-package file-first workflow through Grammar
72
+ 3 reads and writes, temporal/deadline analysis, complete NextResult v4,
73
+ forward/repeated/inverse exact migration, and public Core export checks.
74
+ - Promoted the accepted `perttool@0.2.0` Contract 3 beta to npm `latest`
75
+ through a separate, explicitly authorized post-acceptance dist-tag
76
+ operation. Contract 4 publication itself keeps `latest` at `0.2.0`.
77
+
78
+ ### Fixed
79
+
80
+ - Preserved every Contract 3 `task set --clear` value when adding temporal
81
+ task fields to the Contract 4 descriptor.
82
+ - Preserved Recommendation set authority when its selected task differs from
83
+ the heuristic resource scheduler's first runnable task.
84
+
7
85
  ## [0.2.0] - 2026-07-25
8
86
 
9
87
  Contract 3 beta release. This version intentionally replaces the Contract 2
@@ -96,7 +174,9 @@ First public development preview. Intended to evaluate the DSL and CLI, read-onl
96
174
  - Not published to the npm registry; use the GitHub Release asset
97
175
  - Requires Node.js 24 or later
98
176
 
99
- [Unreleased]: https://github.com/mako10k/perttool/compare/v0.2.0...HEAD
177
+ [Unreleased]: https://github.com/mako10k/perttool/compare/v0.4.0...HEAD
178
+ [0.4.0]: https://github.com/mako10k/perttool/compare/v0.3.0...v0.4.0
179
+ [0.3.0]: https://github.com/mako10k/perttool/compare/v0.2.0...v0.3.0
100
180
  [0.2.0]: https://github.com/mako10k/perttool/compare/v0.1.0...v0.2.0
101
181
  [0.1.0]: https://github.com/mako10k/perttool/compare/v0.1.0-alpha.2...v0.1.0
102
182
  [0.1.0-alpha.2]: https://github.com/mako10k/perttool/compare/v0.1.0-alpha.1...v0.1.0-alpha.2
package/README.md CHANGED
@@ -5,54 +5,65 @@ 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 current Contract 3 version is `0.2.0`. Beta releases may contain breaking
9
- CLI or schema changes. Version `0.2.0` requires Node.js 22 or later. The prior
10
- `0.1.0` artifact uses CLI Contract 2 and declares Node.js 24.
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.
11
14
 
12
15
  ## Run without installing
13
16
 
14
- Use `npx` for an occasional invocation and select Contract 3 explicitly:
17
+ Use `npx` for an occasional invocation and select Contract 5 explicitly:
15
18
 
16
19
  ```sh
17
- npx --yes --package=perttool@0.2.0 -- perttool --version
18
- npx --yes --package=perttool@0.2.0 -- perttool document check PLAN.pert
19
- npx --yes --package=perttool@0.2.0 -- perttool dag next PLAN.pert --format json
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
20
24
  ```
21
25
 
22
26
  The equivalent explicit `npm exec` form is:
23
27
 
24
28
  ```sh
25
- npm exec --yes --package=perttool@0.2.0 -- perttool --version
26
- npm exec --yes --package=perttool@0.2.0 -- perttool document check PLAN.pert
27
- npm exec --yes --package=perttool@0.2.0 -- perttool dag analyze PLAN.pert
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
28
33
  ```
29
34
 
30
35
  `npx` and `npm exec` may download the selected package version into the npm
31
- cache. Pinning `0.1.0` selects the prior Contract 2 interface and therefore
32
- does not accept the commands in this README.
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.
33
40
 
34
41
  ## Install
35
42
 
36
43
  Install the CLI globally when it is used regularly:
37
44
 
38
45
  ```sh
39
- npm install --global perttool@0.2.0
46
+ npm install --global perttool@0.4.0
40
47
  perttool --version
41
48
  ```
42
49
 
43
- npm `beta` resolves to Contract 3 `0.2.0`. npm `latest` remains on Contract 2
44
- `0.1.0` unless a later, separately authorized promotion occurs.
45
- `perttool@beta` is an alternative to the exact `0.2.0` pin.
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`.
46
56
 
47
57
  ## Plan files
48
58
 
49
59
  A `.pert` file is the source of truth and is intended to remain directly
50
- readable. This minimal plan has one one-day task:
60
+ readable. This temporal plan has one one-day task:
51
61
 
52
62
  ```text
53
63
  project EXAMPLE:
54
- version 1
64
+ version 2
55
65
  title "Example plan"
66
+ as_of 2026-07-26
56
67
  duration_unit day
57
68
  finish DONE
58
69
 
@@ -62,10 +73,13 @@ milestone NOW:
62
73
 
63
74
  milestone DONE:
64
75
  title "Done"
76
+ deadline 2026-07-28
65
77
 
66
78
  task WORK NOW -> DONE:
67
79
  title "Do the work"
68
80
  duration 1d
81
+ not_before 2026-07-26
82
+ deadline 2026-07-27
69
83
  ```
70
84
 
71
85
  Save it as `PLAN.pert`, then inspect it with:
@@ -80,7 +94,8 @@ perttool dag next PLAN.pert --format json
80
94
  Task duration can use deterministic `day`, `hour`, or relative `point` units.
81
95
  Point plans declare a project-wide velocity such as `20p/10d`. Analysis keeps
82
96
  the exact point result and reports the time conversion separately as a velocity
83
- forecast.
97
+ forecast. Grammar version 3 also accepts an exact Fraction such as `1/3d`;
98
+ versions 1 and 2 continue to accept Decimal duration tokens.
84
99
 
85
100
  ## Maintain a plan through the CLI
86
101
 
@@ -118,6 +133,8 @@ perttool project show PLAN.pert --format json
118
133
  # Apply the reviewed change atomically.
119
134
  perttool task set PLAN.pert WORK \
120
135
  --status active \
136
+ --not-before 2026-07-26 \
137
+ --deadline 2026-07-27 \
121
138
  --write \
122
139
  --expect-digest 'sha256:...'
123
140
 
@@ -147,6 +164,75 @@ perttool batch apply PLAN.pert \
147
164
  --expect-digest 'sha256:...'
148
165
  ```
149
166
 
167
+ ### Owner-aware governance
168
+
169
+ Moving from `0.3.0` Contract 4 to `0.4.0` Contract 5 changes every JSON
170
+ envelope to `cli_contract_version=5`. Project metadata changes from
171
+ `Perttool.ProjectResult.v2` to `Perttool.ProjectResult.v3`; mutation and
172
+ advance change from `Perttool.MutationResult.v1` to
173
+ `Perttool.MutationResult.v2` and include a
174
+ `Perttool.GovernanceDecision.v1`. Consumers must reject unknown identities
175
+ rather than treating the new fields as optional.
176
+
177
+ Grammar 4 adds declared goal/DAG owners and delegates. Persistent goal or DAG
178
+ changes require `--actor`; an effective owner or delegate has direct
179
+ authority, while another actor supplies repeatable `--accepted-by-owner`
180
+ caller assertions for every affected effective owner. The digest-bound
181
+ pre-change document determines owners and delegates, and an atomic batch must
182
+ satisfy every affected scope. These assertions are not authentication,
183
+ verified identity, signatures, or a durable approval audit.
184
+
185
+ Contract 5 previews may still omit actor and owner confirmation. A Contract 4
186
+ runtime fails closed on Grammar 4 and governance options; there is no
187
+ `--cli-contract 4` switch, compatibility alias, or environment toggle. Pin
188
+ `perttool@0.3.0` when a consumer is not ready to migrate. See the
189
+ [Contract 4-to-5 migration guide](docs/process/cli-contract-5-migration.md)
190
+ for the complete boundary.
191
+
192
+ For example, preview and then persist a DAG change as its effective owner:
193
+
194
+ ```sh
195
+ perttool gate add PLAN.pert APPROVAL NOW DONE \
196
+ --reason "Approval required" \
197
+ --diff
198
+ perttool gate add PLAN.pert APPROVAL NOW DONE \
199
+ --reason "Approval required" \
200
+ --actor user \
201
+ --write \
202
+ --expect-digest 'sha256:...'
203
+ ```
204
+
205
+ Generated Contract 5 projects carry this maintenance warning:
206
+
207
+ ```pert
208
+ # Existing .pert plans should normally be maintained through perttool commands; direct DSL editing bypasses goal/DAG owner-confirmation checks.
209
+ ```
210
+
211
+ The warning is guidance, not technical prevention. A text editor, shell
212
+ command, or other program can bypass the tool-mediated check; Git and human
213
+ review remain external controls.
214
+
215
+ Use the dedicated migration route for exact whole-document conversion between
216
+ Point and time units. Preview before writing; the result inventories every
217
+ converted field and reports grammar upgrades and reversibility:
218
+
219
+ ```sh
220
+ perttool project migrate-unit PLAN.pert --to-unit day --diff
221
+ perttool project migrate-unit PLAN.pert \
222
+ --to-unit day \
223
+ --write \
224
+ --expect-digest 'sha256:...'
225
+
226
+ # A time-to-Point conversion requires an explicit relationship when needed.
227
+ perttool project migrate-unit PLAN.pert \
228
+ --to-unit point \
229
+ --replacement-velocity 20p/10d \
230
+ --diff
231
+ ```
232
+
233
+ Migration is not a `batch apply` member. Re-read and reanalyze the written
234
+ candidate before making a separate mutation.
235
+
150
236
  ## Command map
151
237
 
152
238
  | Goal | Command |
@@ -158,6 +244,7 @@ perttool batch apply PLAN.pert \
158
244
  | Initialize a project | `perttool project init ...` |
159
245
  | Read project metadata | `perttool project show <file>` |
160
246
  | Change project metadata | `perttool project set <file> ...` |
247
+ | Migrate project units exactly | `perttool project migrate-unit <file> ...` |
161
248
  | Analyze schedules | `perttool dag analyze <file>` |
162
249
  | Select next work | `perttool dag next <file>` |
163
250
  | Remove completed history | `perttool dag advance <file>` |
@@ -181,21 +268,27 @@ perttool guide editing --level detail --format json
181
268
 
182
269
  ## LLM and automation use
183
270
 
184
- Use `--format json` for machine consumers. Check both
185
- `cli_contract_version == 3` and the result-specific `schema_version` before
186
- reading the rest of a result. A complete, known `Perttool.NextResult.v3`
187
- recommendation graph is the task-selection authority; do not infer authority
188
- from the text summary or from `ready` alone.
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
276
+ `recommendation_v1_plus_release_gate` is required. Start only task IDs in
277
+ `temporal.authority.startable_recommended_task_ids`; do not infer start
278
+ authority from the raw recommended set, the text summary, or `ready` alone.
189
279
 
190
280
  Mutation JSON returns the candidate text, unified diff, UTF-16 text edits,
191
281
  source digest, updated digest, diagnostics, and write result in one envelope.
192
- Unknown schema versions, incomplete recommendation traces, and `PTREC-*`
193
- diagnostics must fail closed.
282
+ Unknown schema versions, incomplete recommendation traces, `PTREC-*`
283
+ diagnostics, and future or unavailable temporal eligibility must fail closed.
194
284
 
195
285
  ## Documentation
196
286
 
197
- - [CLI Contract 3](docs/specs/cli-contract-3.md)
198
- - [Migration from CLI Contract 2](docs/process/cli-contract-3-migration.md)
287
+ - [Temporal and Unit Interface Contract (CLI Contract 4)](docs/specs/temporal-unit-interface.md)
288
+ - [Owner-Aware Governance Interface Contract (CLI Contract 5)](docs/specs/governance-interface.md)
289
+ - [Contract 4-to-5 migration](docs/process/cli-contract-5-migration.md)
290
+ - [Issue #4 governance implementation acceptance](docs/process/governance-acceptance.md)
291
+ - [CLI Contract 3 compatibility baseline](docs/specs/cli-contract-3.md)
199
292
  - [DSL grammar](docs/specs/dsl-grammar.md)
200
293
  - [Graph semantics](docs/specs/graph-semantics.md)
201
294
  - [Analysis semantics](docs/specs/analysis.md)
@@ -0,0 +1,59 @@
1
+ import type { TargetCalendarDifference, TargetTemporalExactValue, TargetTemporalInputProjection } from "../application/target-temporal-input.js";
2
+ import { type CalendarUnavailableCause } from "../model/calendar-arithmetic.js";
3
+ import type { TargetCalendarValue } from "../model/target-calendar.js";
4
+ import type { TargetGrammar3ValidatedDocument, TargetGrammar4ValidatedDocument } from "../semantic/target-validator.js";
5
+ import type { TemporalPrecedenceSchedule } from "./temporal-precedence.js";
6
+ import type { TemporalResourceSchedule } from "./temporal-resource.js";
7
+ export declare const DEADLINE_EVALUATION_IDENTITY: Readonly<{
8
+ id: "perttool.deadline-evaluation";
9
+ version: 1;
10
+ }>;
11
+ export type DeadlineCause = CalendarUnavailableCause | "complete_actual_time_unavailable" | "release_bound_unavailable" | "precedence_projection_unavailable" | "resource_projection_unavailable" | "margin_unit_unavailable";
12
+ export interface DeadlineUnavailableCause {
13
+ readonly cause: DeadlineCause;
14
+ readonly underlyingCause: string | null;
15
+ readonly subjectKind: "task" | "milestone" | null;
16
+ readonly subjectId: string | null;
17
+ readonly taskId: string | null;
18
+ }
19
+ export interface DeadlineCurrentState {
20
+ readonly state: "not_due" | "due_now" | "overdue" | "not_applicable" | "unavailable";
21
+ readonly signedWindow: TargetCalendarDifference | null;
22
+ readonly baseUnitWindow: TargetTemporalExactValue | null;
23
+ readonly unavailableCauses: readonly DeadlineUnavailableCause[];
24
+ }
25
+ export interface DeadlineView {
26
+ readonly state: "not_applicable" | "unavailable" | "available";
27
+ readonly projectedCompletion: TargetCalendarValue | null;
28
+ readonly forecastRelation: "before_deadline" | "on_deadline" | "after_deadline" | null;
29
+ readonly signedMargin: TargetCalendarDifference | null;
30
+ readonly baseUnitMargin: TargetTemporalExactValue | null;
31
+ readonly remainingMargin: TargetTemporalExactValue | null;
32
+ readonly lateness: TargetTemporalExactValue | null;
33
+ readonly assessment: "lower_bound_on_time" | "lower_bound_late" | "heuristic_on_time" | "heuristic_late" | null;
34
+ readonly optimal: boolean | null;
35
+ readonly conditionalOnBlocksResolved: boolean;
36
+ readonly blockedTaskIds: readonly string[];
37
+ readonly unavailableCauses: readonly DeadlineUnavailableCause[];
38
+ }
39
+ export interface DeadlineEvaluation {
40
+ readonly subject: {
41
+ readonly kind: "task" | "milestone";
42
+ readonly id: string;
43
+ readonly roles: readonly ("task" | "milestone" | "project_finish")[];
44
+ };
45
+ readonly deadline: TargetCalendarValue;
46
+ readonly completionState: "incomplete" | "complete_actual_time_unavailable";
47
+ readonly current: DeadlineCurrentState;
48
+ readonly precedence: DeadlineView;
49
+ readonly resource: DeadlineView;
50
+ readonly combinedAssessment: "overdue" | "forecast_infeasible" | "at_risk" | "forecast_on_time" | "not_proven_late" | "not_applicable" | "unavailable";
51
+ readonly conditionalOnBlocksResolved: boolean;
52
+ readonly blockedTaskIds: readonly string[];
53
+ readonly destinationRelationship: {
54
+ readonly milestoneId: string;
55
+ readonly relation: "task_deadline_before_milestone" | "same_deadline" | "task_deadline_after_milestone" | "unavailable" | "deadline_absent";
56
+ } | null;
57
+ }
58
+ export declare function evaluateTemporalDeadlines(validated: TargetGrammar3ValidatedDocument | TargetGrammar4ValidatedDocument, inputs: TargetTemporalInputProjection, precedenceSchedule: TemporalPrecedenceSchedule, resourceSchedule: TemporalResourceSchedule): readonly DeadlineEvaluation[];
59
+ //# sourceMappingURL=temporal-deadline.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"temporal-deadline.d.ts","sourceRoot":"","sources":["../../src/analysis/temporal-deadline.ts"],"names":[],"mappings":"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"}