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.
- package/CHANGELOG.md +44 -1
- package/README.md +84 -34
- package/dist/actuals/lifecycle.d.ts +101 -0
- package/dist/actuals/lifecycle.d.ts.map +1 -0
- package/dist/actuals/lifecycle.js +329 -0
- package/dist/actuals/lifecycle.js.map +1 -0
- package/dist/actuals/source.d.ts +36 -0
- package/dist/actuals/source.d.ts.map +1 -0
- package/dist/actuals/source.js +119 -0
- package/dist/actuals/source.js.map +1 -0
- package/dist/analysis/temporal-deadline.d.ts +2 -2
- package/dist/analysis/temporal-deadline.d.ts.map +1 -1
- package/dist/analysis/temporal-deadline.js.map +1 -1
- package/dist/analysis/temporal-precedence.d.ts +2 -2
- package/dist/analysis/temporal-precedence.d.ts.map +1 -1
- package/dist/analysis/temporal-precedence.js +2 -0
- package/dist/analysis/temporal-precedence.js.map +1 -1
- package/dist/analysis/temporal-resource.d.ts +2 -2
- package/dist/analysis/temporal-resource.d.ts.map +1 -1
- package/dist/analysis/temporal-resource.js +2 -0
- package/dist/analysis/temporal-resource.js.map +1 -1
- package/dist/application/analyze.d.ts +1 -0
- package/dist/application/analyze.d.ts.map +1 -1
- package/dist/application/analyze.js +38 -29
- package/dist/application/analyze.js.map +1 -1
- package/dist/application/check.d.ts +3 -0
- package/dist/application/check.d.ts.map +1 -1
- package/dist/application/check.js +17 -1
- package/dist/application/check.js.map +1 -1
- package/dist/application/contract6-actuals.d.ts +24 -0
- package/dist/application/contract6-actuals.d.ts.map +1 -0
- package/dist/application/contract6-actuals.js +51 -0
- package/dist/application/contract6-actuals.js.map +1 -0
- package/dist/application/contract6-mutation.d.ts +18 -0
- package/dist/application/contract6-mutation.d.ts.map +1 -0
- package/dist/application/contract6-mutation.js +173 -0
- package/dist/application/contract6-mutation.js.map +1 -0
- package/dist/application/contract6-projection.d.ts +9 -0
- package/dist/application/contract6-projection.d.ts.map +1 -0
- package/dist/application/contract6-projection.js +105 -0
- package/dist/application/contract6-projection.js.map +1 -0
- package/dist/application/init.d.ts +1 -1
- package/dist/application/init.js +3 -3
- package/dist/application/project.js +2 -2
- package/dist/application/target-actuals-advance.d.ts +12 -0
- package/dist/application/target-actuals-advance.d.ts.map +1 -0
- package/dist/application/target-actuals-advance.js +113 -0
- package/dist/application/target-actuals-advance.js.map +1 -0
- package/dist/application/target-actuals-analysis.d.ts +76 -0
- package/dist/application/target-actuals-analysis.d.ts.map +1 -0
- package/dist/application/target-actuals-analysis.js +250 -0
- package/dist/application/target-actuals-analysis.js.map +1 -0
- package/dist/application/target-actuals-mutation.d.ts +28 -0
- package/dist/application/target-actuals-mutation.d.ts.map +1 -0
- package/dist/application/target-actuals-mutation.js +404 -0
- package/dist/application/target-actuals-mutation.js.map +1 -0
- package/dist/application/target-actuals-write.d.ts +7 -0
- package/dist/application/target-actuals-write.d.ts.map +1 -0
- package/dist/application/target-actuals-write.js +37 -0
- package/dist/application/target-actuals-write.js.map +1 -0
- package/dist/application/target-governance-init.d.ts +3 -3
- package/dist/application/target-governance-init.d.ts.map +1 -1
- package/dist/application/target-governance-init.js +20 -10
- package/dist/application/target-governance-init.js.map +1 -1
- package/dist/application/target-governance-project.d.ts +4 -4
- package/dist/application/target-governance-project.d.ts.map +1 -1
- package/dist/application/target-governance-project.js +4 -2
- package/dist/application/target-governance-project.js.map +1 -1
- package/dist/application/target-governance-write.d.ts +8 -0
- package/dist/application/target-governance-write.d.ts.map +1 -1
- package/dist/application/target-governance-write.js +1 -1
- package/dist/application/target-governance-write.js.map +1 -1
- package/dist/application/target-mutate.d.ts +3 -1
- package/dist/application/target-mutate.d.ts.map +1 -1
- package/dist/application/target-mutate.js +34 -2
- package/dist/application/target-mutate.js.map +1 -1
- package/dist/application/target-project-history.d.ts +18 -0
- package/dist/application/target-project-history.d.ts.map +1 -0
- package/dist/application/target-project-history.js +279 -0
- package/dist/application/target-project-history.js.map +1 -0
- package/dist/application/target-temporal-analysis.d.ts +7 -1
- package/dist/application/target-temporal-analysis.d.ts.map +1 -1
- package/dist/application/target-temporal-analysis.js +10 -8
- package/dist/application/target-temporal-analysis.js.map +1 -1
- package/dist/application/target-temporal-input.d.ts +6 -4
- package/dist/application/target-temporal-input.d.ts.map +1 -1
- package/dist/application/target-temporal-input.js +10 -1
- package/dist/application/target-temporal-input.js.map +1 -1
- package/dist/application/target-unit-migration-candidate.d.ts +2 -2
- package/dist/application/target-unit-migration-candidate.d.ts.map +1 -1
- package/dist/application/target-unit-migration-candidate.js +21 -10
- package/dist/application/target-unit-migration-candidate.js.map +1 -1
- package/dist/application/target-unit-migration-request.d.ts +4 -4
- package/dist/application/target-unit-migration-request.d.ts.map +1 -1
- package/dist/application/target-unit-migration-request.js +6 -4
- package/dist/application/target-unit-migration-request.js.map +1 -1
- package/dist/application/target-unit-migration-result.d.ts +5 -5
- package/dist/application/target-unit-migration-result.d.ts.map +1 -1
- package/dist/application/target-unit-migration-result.js +1 -1
- package/dist/application/target-unit-migration-result.js.map +1 -1
- package/dist/application/target-velocity-observation.d.ts +11 -0
- package/dist/application/target-velocity-observation.d.ts.map +1 -0
- package/dist/application/target-velocity-observation.js +201 -0
- package/dist/application/target-velocity-observation.js.map +1 -0
- package/dist/application/unit-migration.d.ts +2 -2
- package/dist/application/unit-migration.d.ts.map +1 -1
- package/dist/application/unit-migration.js +2 -2
- package/dist/cli.js +285 -45
- package/dist/cli.js.map +1 -1
- package/dist/command/actuals-discovery.d.ts +26 -0
- package/dist/command/actuals-discovery.d.ts.map +1 -0
- package/dist/command/actuals-discovery.js +271 -0
- package/dist/command/actuals-discovery.js.map +1 -0
- package/dist/command/actuals-usage.d.ts +22 -0
- package/dist/command/actuals-usage.d.ts.map +1 -0
- package/dist/command/actuals-usage.js +122 -0
- package/dist/command/actuals-usage.js.map +1 -0
- package/dist/formatter/source-formatter.d.ts +3 -3
- package/dist/formatter/source-formatter.d.ts.map +1 -1
- package/dist/formatter/source-formatter.js +53 -5
- package/dist/formatter/source-formatter.js.map +1 -1
- package/dist/formatter/target-source-formatter.d.ts +2 -1
- package/dist/formatter/target-source-formatter.d.ts.map +1 -1
- package/dist/formatter/target-source-formatter.js +18 -2
- package/dist/formatter/target-source-formatter.js.map +1 -1
- package/dist/governance/authority.d.ts +7 -3
- package/dist/governance/authority.d.ts.map +1 -1
- package/dist/governance/authority.js.map +1 -1
- package/dist/governance/source.d.ts +2 -2
- package/dist/governance/source.d.ts.map +1 -1
- package/dist/governance/source.js.map +1 -1
- package/dist/help/actuals-guide.d.ts +10 -0
- package/dist/help/actuals-guide.d.ts.map +1 -0
- package/dist/help/actuals-guide.js +23 -0
- package/dist/help/actuals-guide.js.map +1 -0
- package/dist/help/guide.d.ts +1 -1
- package/dist/help/guide.d.ts.map +1 -1
- package/dist/help/registry.d.ts.map +1 -1
- package/dist/help/registry.js +97 -7
- package/dist/help/registry.js.map +1 -1
- package/dist/history/git-probe.d.ts +52 -0
- package/dist/history/git-probe.d.ts.map +1 -0
- package/dist/history/git-probe.js +565 -0
- package/dist/history/git-probe.js.map +1 -0
- package/dist/history/project-history.d.ts +112 -0
- package/dist/history/project-history.d.ts.map +1 -0
- package/dist/history/project-history.js +786 -0
- package/dist/history/project-history.js.map +1 -0
- package/dist/history/velocity-observation.d.ts +69 -0
- package/dist/history/velocity-observation.d.ts.map +1 -0
- package/dist/history/velocity-observation.js +604 -0
- package/dist/history/velocity-observation.js.map +1 -0
- package/dist/index.d.ts +19 -10
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +9 -5
- package/dist/index.js.map +1 -1
- package/dist/io/target-safe-write.d.ts +4 -1
- package/dist/io/target-safe-write.d.ts.map +1 -1
- package/dist/io/target-safe-write.js +19 -1
- package/dist/io/target-safe-write.js.map +1 -1
- package/dist/migration/conversion.d.ts +1 -1
- package/dist/migration/conversion.d.ts.map +1 -1
- package/dist/migration/grammar-boundary.d.ts +1 -1
- package/dist/migration/grammar-boundary.d.ts.map +1 -1
- package/dist/migration/grammar-boundary.js +11 -3
- package/dist/migration/grammar-boundary.js.map +1 -1
- package/dist/migration/request.d.ts +5 -5
- package/dist/migration/request.d.ts.map +1 -1
- package/dist/migration/request.js +15 -2
- package/dist/migration/request.js.map +1 -1
- package/dist/model/calendar.d.ts +2 -0
- package/dist/model/calendar.d.ts.map +1 -1
- package/dist/model/calendar.js +19 -0
- package/dist/model/calendar.js.map +1 -1
- package/dist/model/declaration-fields.d.ts +8 -0
- package/dist/model/declaration-fields.d.ts.map +1 -1
- package/dist/model/declaration-fields.js +13 -0
- package/dist/model/declaration-fields.js.map +1 -1
- package/dist/model/exact-person-hours-source.d.ts +2 -0
- package/dist/model/exact-person-hours-source.d.ts.map +1 -0
- package/dist/model/exact-person-hours-source.js +10 -0
- package/dist/model/exact-person-hours-source.js.map +1 -0
- package/dist/model/syntax.d.ts +23 -8
- package/dist/model/syntax.d.ts.map +1 -1
- package/dist/model/syntax.js.map +1 -1
- package/dist/mutation/actuals.d.ts +17 -0
- package/dist/mutation/actuals.d.ts.map +1 -0
- package/dist/mutation/actuals.js +90 -0
- package/dist/mutation/actuals.js.map +1 -0
- package/dist/mutation/advance.d.ts +9 -3
- package/dist/mutation/advance.d.ts.map +1 -1
- package/dist/mutation/advance.js +41 -12
- package/dist/mutation/advance.js.map +1 -1
- package/dist/mutation/entity-editor.d.ts +2 -2
- package/dist/mutation/entity-editor.d.ts.map +1 -1
- package/dist/mutation/entity-editor.js.map +1 -1
- package/dist/mutation/project.d.ts +2 -0
- package/dist/mutation/project.d.ts.map +1 -1
- package/dist/mutation/project.js +13 -4
- package/dist/mutation/project.js.map +1 -1
- package/dist/mutation/source.d.ts +3 -3
- package/dist/mutation/source.d.ts.map +1 -1
- package/dist/mutation/source.js.map +1 -1
- package/dist/parser/document-parser.d.ts +8 -1
- package/dist/parser/document-parser.d.ts.map +1 -1
- package/dist/parser/document-parser.js +151 -23
- package/dist/parser/document-parser.js.map +1 -1
- package/dist/recommendation/override-types.d.ts +2 -2
- package/dist/recommendation/override.d.ts +2 -2
- package/dist/recommendation/override.d.ts.map +1 -1
- package/dist/recommendation/override.js +2 -2
- package/dist/recommendation/override.js.map +1 -1
- package/dist/semantic/target-validator.d.ts +13 -2
- package/dist/semantic/target-validator.d.ts.map +1 -1
- package/dist/semantic/target-validator.js +46 -2
- package/dist/semantic/target-validator.js.map +1 -1
- package/dist/semantic/validator.d.ts +4 -1
- package/dist/semantic/validator.d.ts.map +1 -1
- package/dist/semantic/validator.js +152 -6
- package/dist/semantic/validator.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- 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.
|
|
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.
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
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
|
|
19
|
+
Use `npx` for an occasional invocation and select Contract 6 explicitly:
|
|
18
20
|
|
|
19
21
|
```sh
|
|
20
|
-
npx --yes --package=perttool@0.
|
|
21
|
-
npx --yes --package=perttool@0.
|
|
22
|
-
npx --yes --package=perttool@0.
|
|
23
|
-
npx --yes --package=perttool@0.
|
|
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.
|
|
30
|
-
npm exec --yes --package=perttool@0.
|
|
31
|
-
npm exec --yes --package=perttool@0.
|
|
32
|
-
npm exec --yes --package=perttool@0.
|
|
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.
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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.
|
|
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
|
|
51
|
-
`latest` on Contract
|
|
52
|
-
to `0.
|
|
53
|
-
After publication, `perttool@beta` follows Contract
|
|
54
|
-
Contract 3 remain available as exact pins `perttool@0.
|
|
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
|
|
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.
|
|
272
|
-
`cli_contract_version ==
|
|
273
|
-
require Contract
|
|
274
|
-
|
|
275
|
-
|
|
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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"}
|