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.
- package/CHANGELOG.md +81 -1
- package/README.md +121 -28
- package/dist/analysis/temporal-deadline.d.ts +59 -0
- package/dist/analysis/temporal-deadline.d.ts.map +1 -0
- package/dist/analysis/temporal-deadline.js +387 -0
- package/dist/analysis/temporal-deadline.js.map +1 -0
- package/dist/analysis/temporal-precedence.d.ts +45 -0
- package/dist/analysis/temporal-precedence.d.ts.map +1 -0
- package/dist/analysis/temporal-precedence.js +123 -0
- package/dist/analysis/temporal-precedence.js.map +1 -0
- package/dist/analysis/temporal-resource.d.ts +66 -0
- package/dist/analysis/temporal-resource.d.ts.map +1 -0
- package/dist/analysis/temporal-resource.js +292 -0
- package/dist/analysis/temporal-resource.js.map +1 -0
- package/dist/application/check.d.ts +16 -0
- package/dist/application/check.d.ts.map +1 -1
- package/dist/application/check.js +51 -0
- package/dist/application/check.js.map +1 -1
- package/dist/application/contract4.d.ts +17 -0
- package/dist/application/contract4.d.ts.map +1 -0
- package/dist/application/contract4.js +27 -0
- package/dist/application/contract4.js.map +1 -0
- package/dist/application/contract5-governance.d.ts +8 -0
- package/dist/application/contract5-governance.d.ts.map +1 -0
- package/dist/application/contract5-governance.js +12 -0
- package/dist/application/contract5-governance.js.map +1 -0
- package/dist/application/init.d.ts +3 -11
- package/dist/application/init.d.ts.map +1 -1
- package/dist/application/init.js +16 -129
- package/dist/application/init.js.map +1 -1
- package/dist/application/mutate.d.ts +19 -0
- package/dist/application/mutate.d.ts.map +1 -1
- package/dist/application/mutate.js +34 -16
- package/dist/application/mutate.js.map +1 -1
- package/dist/application/next.d.ts +2 -0
- package/dist/application/next.d.ts.map +1 -1
- package/dist/application/next.js +7 -1
- package/dist/application/next.js.map +1 -1
- package/dist/application/project.d.ts +4 -22
- package/dist/application/project.d.ts.map +1 -1
- package/dist/application/project.js +3 -51
- package/dist/application/project.js.map +1 -1
- package/dist/application/target-check.d.ts +34 -0
- package/dist/application/target-check.d.ts.map +1 -0
- package/dist/application/target-check.js +90 -0
- package/dist/application/target-check.js.map +1 -0
- package/dist/application/target-governance-init.d.ts +36 -0
- package/dist/application/target-governance-init.d.ts.map +1 -0
- package/dist/application/target-governance-init.js +185 -0
- package/dist/application/target-governance-init.js.map +1 -0
- package/dist/application/target-governance-mutation.d.ts +20 -0
- package/dist/application/target-governance-mutation.d.ts.map +1 -0
- package/dist/application/target-governance-mutation.js +175 -0
- package/dist/application/target-governance-mutation.js.map +1 -0
- package/dist/application/target-governance-project.d.ts +34 -0
- package/dist/application/target-governance-project.d.ts.map +1 -0
- package/dist/application/target-governance-project.js +80 -0
- package/dist/application/target-governance-project.js.map +1 -0
- package/dist/application/target-governance-projection.d.ts +18 -0
- package/dist/application/target-governance-projection.d.ts.map +1 -0
- package/dist/application/target-governance-projection.js +248 -0
- package/dist/application/target-governance-projection.js.map +1 -0
- package/dist/application/target-governance-write.d.ts +17 -0
- package/dist/application/target-governance-write.d.ts.map +1 -0
- package/dist/application/target-governance-write.js +55 -0
- package/dist/application/target-governance-write.js.map +1 -0
- package/dist/application/target-grammar-boundary.d.ts +22 -0
- package/dist/application/target-grammar-boundary.d.ts.map +1 -0
- package/dist/application/target-grammar-boundary.js +91 -0
- package/dist/application/target-grammar-boundary.js.map +1 -0
- package/dist/application/target-mutate.d.ts +10 -0
- package/dist/application/target-mutate.d.ts.map +1 -0
- package/dist/application/target-mutate.js +81 -0
- package/dist/application/target-mutate.js.map +1 -0
- package/dist/application/target-project.d.ts +28 -0
- package/dist/application/target-project.d.ts.map +1 -0
- package/dist/application/target-project.js +60 -0
- package/dist/application/target-project.js.map +1 -0
- package/dist/application/target-temporal-analysis.d.ts +140 -0
- package/dist/application/target-temporal-analysis.d.ts.map +1 -0
- package/dist/application/target-temporal-analysis.js +414 -0
- package/dist/application/target-temporal-analysis.js.map +1 -0
- package/dist/application/target-temporal-input.d.ts +86 -0
- package/dist/application/target-temporal-input.d.ts.map +1 -0
- package/dist/application/target-temporal-input.js +240 -0
- package/dist/application/target-temporal-input.js.map +1 -0
- package/dist/application/target-unit-migration-candidate.d.ts +60 -0
- package/dist/application/target-unit-migration-candidate.d.ts.map +1 -0
- package/dist/application/target-unit-migration-candidate.js +294 -0
- package/dist/application/target-unit-migration-candidate.js.map +1 -0
- package/dist/application/target-unit-migration-request.d.ts +35 -0
- package/dist/application/target-unit-migration-request.d.ts.map +1 -0
- package/dist/application/target-unit-migration-request.js +70 -0
- package/dist/application/target-unit-migration-request.js.map +1 -0
- package/dist/application/target-unit-migration-result.d.ts +66 -0
- package/dist/application/target-unit-migration-result.d.ts.map +1 -0
- package/dist/application/target-unit-migration-result.js +86 -0
- package/dist/application/target-unit-migration-result.js.map +1 -0
- package/dist/application/unit-migration.d.ts +16 -0
- package/dist/application/unit-migration.d.ts.map +1 -0
- package/dist/application/unit-migration.js +11 -0
- package/dist/application/unit-migration.js.map +1 -0
- package/dist/cli.js +383 -132
- package/dist/cli.js.map +1 -1
- package/dist/command/discovery.d.ts +3 -3
- package/dist/command/discovery.d.ts.map +1 -1
- package/dist/command/discovery.js +149 -22
- package/dist/command/discovery.js.map +1 -1
- package/dist/command/registry.d.ts +8 -2
- package/dist/command/registry.d.ts.map +1 -1
- package/dist/command/registry.js +14 -1
- package/dist/command/registry.js.map +1 -1
- package/dist/command/target-governance-discovery.d.ts +31 -0
- package/dist/command/target-governance-discovery.d.ts.map +1 -0
- package/dist/command/target-governance-discovery.js +390 -0
- package/dist/command/target-governance-discovery.js.map +1 -0
- package/dist/command/target-governance-usage.d.ts +22 -0
- package/dist/command/target-governance-usage.d.ts.map +1 -0
- package/dist/command/target-governance-usage.js +116 -0
- package/dist/command/target-governance-usage.js.map +1 -0
- package/dist/command/usage.d.ts +2 -0
- package/dist/command/usage.d.ts.map +1 -1
- package/dist/command/usage.js +44 -26
- package/dist/command/usage.js.map +1 -1
- package/dist/conversion/mermaid-import.d.ts.map +1 -1
- package/dist/conversion/mermaid-import.js +3 -2
- package/dist/conversion/mermaid-import.js.map +1 -1
- package/dist/conversion/mermaid.d.ts.map +1 -1
- package/dist/conversion/mermaid.js +27 -0
- package/dist/conversion/mermaid.js.map +1 -1
- package/dist/formatter/source-formatter.d.ts +12 -0
- package/dist/formatter/source-formatter.d.ts.map +1 -1
- package/dist/formatter/source-formatter.js +59 -6
- package/dist/formatter/source-formatter.js.map +1 -1
- package/dist/formatter/target-source-formatter.d.ts +9 -0
- package/dist/formatter/target-source-formatter.d.ts.map +1 -0
- package/dist/formatter/target-source-formatter.js +52 -0
- package/dist/formatter/target-source-formatter.js.map +1 -0
- package/dist/governance/authority.d.ts +21 -0
- package/dist/governance/authority.d.ts.map +1 -0
- package/dist/governance/authority.js +206 -0
- package/dist/governance/authority.js.map +1 -0
- package/dist/governance/guidance.d.ts +2 -0
- package/dist/governance/guidance.d.ts.map +1 -0
- package/dist/governance/guidance.js +2 -0
- package/dist/governance/guidance.js.map +1 -0
- package/dist/governance/source.d.ts +37 -0
- package/dist/governance/source.d.ts.map +1 -0
- package/dist/governance/source.js +103 -0
- package/dist/governance/source.js.map +1 -0
- package/dist/governance/types.d.ts +41 -0
- package/dist/governance/types.d.ts.map +1 -0
- package/dist/governance/types.js +2 -0
- package/dist/governance/types.js.map +1 -0
- package/dist/help/guide.d.ts +8 -5
- package/dist/help/guide.d.ts.map +1 -1
- package/dist/help/guide.js +1 -1
- package/dist/help/guide.js.map +1 -1
- package/dist/help/registry.d.ts.map +1 -1
- package/dist/help/registry.js +124 -13
- package/dist/help/registry.js.map +1 -1
- package/dist/help/target-governance-guide.d.ts +10 -0
- package/dist/help/target-governance-guide.d.ts.map +1 -0
- package/dist/help/target-governance-guide.js +57 -0
- package/dist/help/target-governance-guide.js.map +1 -0
- package/dist/index.d.ts +25 -17
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +8 -8
- package/dist/index.js.map +1 -1
- package/dist/io/safe-write.d.ts +11 -0
- package/dist/io/safe-write.d.ts.map +1 -1
- package/dist/io/safe-write.js +40 -10
- package/dist/io/safe-write.js.map +1 -1
- package/dist/io/target-safe-write.d.ts +10 -0
- package/dist/io/target-safe-write.d.ts.map +1 -0
- package/dist/io/target-safe-write.js +51 -0
- package/dist/io/target-safe-write.js.map +1 -0
- package/dist/migration/conversion.d.ts +40 -0
- package/dist/migration/conversion.d.ts.map +1 -0
- package/dist/migration/conversion.js +106 -0
- package/dist/migration/conversion.js.map +1 -0
- package/dist/migration/grammar-boundary.d.ts +20 -0
- package/dist/migration/grammar-boundary.d.ts.map +1 -0
- package/dist/migration/grammar-boundary.js +95 -0
- package/dist/migration/grammar-boundary.js.map +1 -0
- package/dist/migration/request.d.ts +79 -0
- package/dist/migration/request.d.ts.map +1 -0
- package/dist/migration/request.js +308 -0
- package/dist/migration/request.js.map +1 -0
- package/dist/model/calendar-arithmetic.d.ts +46 -0
- package/dist/model/calendar-arithmetic.d.ts.map +1 -0
- package/dist/model/calendar-arithmetic.js +236 -0
- package/dist/model/calendar-arithmetic.js.map +1 -0
- package/dist/model/calendar.d.ts +22 -0
- package/dist/model/calendar.d.ts.map +1 -0
- package/dist/model/calendar.js +83 -0
- package/dist/model/calendar.js.map +1 -0
- package/dist/model/declaration-fields.d.ts +22 -0
- package/dist/model/declaration-fields.d.ts.map +1 -0
- package/dist/model/declaration-fields.js +72 -0
- package/dist/model/declaration-fields.js.map +1 -0
- package/dist/model/exact-duration-source.d.ts +10 -0
- package/dist/model/exact-duration-source.d.ts.map +1 -0
- package/dist/model/exact-duration-source.js +69 -0
- package/dist/model/exact-duration-source.js.map +1 -0
- package/dist/model/rational.d.ts +2 -2
- package/dist/model/rational.d.ts.map +1 -1
- package/dist/model/rational.js +3 -1
- package/dist/model/rational.js.map +1 -1
- package/dist/model/syntax.d.ts +9 -2
- package/dist/model/syntax.d.ts.map +1 -1
- package/dist/model/syntax.js +20 -4
- package/dist/model/syntax.js.map +1 -1
- package/dist/model/target-calendar.d.ts +25 -0
- package/dist/model/target-calendar.d.ts.map +1 -0
- package/dist/model/target-calendar.js +56 -0
- package/dist/model/target-calendar.js.map +1 -0
- package/dist/mutation/advance.d.ts +11 -0
- package/dist/mutation/advance.d.ts.map +1 -1
- package/dist/mutation/advance.js +37 -7
- package/dist/mutation/advance.js.map +1 -1
- package/dist/mutation/milestone.d.ts +10 -1
- package/dist/mutation/milestone.d.ts.map +1 -1
- package/dist/mutation/milestone.js +77 -21
- package/dist/mutation/milestone.js.map +1 -1
- package/dist/mutation/project.d.ts +11 -1
- package/dist/mutation/project.d.ts.map +1 -1
- package/dist/mutation/project.js +117 -11
- package/dist/mutation/project.js.map +1 -1
- package/dist/mutation/target-types.d.ts +59 -0
- package/dist/mutation/target-types.d.ts.map +1 -0
- package/dist/mutation/target-types.js +2 -0
- package/dist/mutation/target-types.js.map +1 -0
- package/dist/mutation/task.d.ts +12 -1
- package/dist/mutation/task.d.ts.map +1 -1
- package/dist/mutation/task.js +108 -49
- package/dist/mutation/task.js.map +1 -1
- package/dist/mutation/types.d.ts +16 -3
- package/dist/mutation/types.d.ts.map +1 -1
- package/dist/parser/document-parser.d.ts +21 -0
- package/dist/parser/document-parser.d.ts.map +1 -1
- package/dist/parser/document-parser.js +197 -38
- 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 +49 -12
- package/dist/recommendation/override.js.map +1 -1
- package/dist/semantic/target-validator.d.ts +46 -0
- package/dist/semantic/target-validator.d.ts.map +1 -0
- package/dist/semantic/target-validator.js +130 -0
- package/dist/semantic/target-validator.js.map +1 -0
- package/dist/semantic/validator.d.ts +3 -0
- package/dist/semantic/validator.d.ts.map +1 -1
- package/dist/semantic/validator.js +78 -5
- package/dist/semantic/validator.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- 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.
|
|
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
|
|
9
|
-
|
|
10
|
-
`0.
|
|
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
|
|
17
|
+
Use `npx` for an occasional invocation and select Contract 5 explicitly:
|
|
15
18
|
|
|
16
19
|
```sh
|
|
17
|
-
npx --yes --package=perttool@0.
|
|
18
|
-
npx --yes --package=perttool@0.
|
|
19
|
-
npx --yes --package=perttool@0.
|
|
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.
|
|
26
|
-
npm exec --yes --package=perttool@0.
|
|
27
|
-
npm exec --yes --package=perttool@0.
|
|
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.
|
|
32
|
-
|
|
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.
|
|
46
|
+
npm install --global perttool@0.4.0
|
|
40
47
|
perttool --version
|
|
41
48
|
```
|
|
42
49
|
|
|
43
|
-
npm `beta`
|
|
44
|
-
`0.
|
|
45
|
-
`
|
|
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
|
|
60
|
+
readable. This temporal plan has one one-day task:
|
|
51
61
|
|
|
52
62
|
```text
|
|
53
63
|
project EXAMPLE:
|
|
54
|
-
version
|
|
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.
|
|
185
|
-
`cli_contract_version ==
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
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,
|
|
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
|
|
198
|
-
- [
|
|
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":"AAAA,OAAO,KAAK,EACV,wBAAwB,EAGxB,wBAAwB,EACxB,6BAA6B,EAC9B,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,iCAAiC,CAAC;AAazC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,OAAO,KAAK,EACV,+BAA+B,EAC/B,+BAA+B,EAChC,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,0BAA0B,EAC3B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,wBAAwB,EACzB,MAAM,wBAAwB,CAAC;AAEhC,eAAO,MAAM,4BAA4B;QACnC,8BAA8B;aACzB,CAAC;EACV,CAAC;AAEH,MAAM,MAAM,aAAa,GACrB,wBAAwB,GACxB,kCAAkC,GAClC,2BAA2B,GAC3B,mCAAmC,GACnC,iCAAiC,GACjC,yBAAyB,CAAC;AAE9B,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EACV,SAAS,GACT,SAAS,GACT,SAAS,GACT,gBAAgB,GAChB,aAAa,CAAC;IAClB,QAAQ,CAAC,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACvD,QAAQ,CAAC,cAAc,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACzD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACjE;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,GAAG,WAAW,CAAC;IAC/D,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACzD,QAAQ,CAAC,gBAAgB,EACrB,iBAAiB,GACjB,aAAa,GACb,gBAAgB,GAChB,IAAI,CAAC;IACT,QAAQ,CAAC,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACvD,QAAQ,CAAC,cAAc,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACzD,QAAQ,CAAC,eAAe,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAC1D,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,UAAU,EACf,qBAAqB,GACrB,kBAAkB,GAClB,mBAAmB,GACnB,gBAAgB,GAChB,IAAI,CAAC;IACT,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,2BAA2B,EAAE,OAAO,CAAC;IAC9C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACjE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;QACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,GAAG,WAAW,GAAG,gBAAgB,CAAC,EAAE,CAAC;KACtE,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,eAAe,EACpB,YAAY,GACZ,kCAAkC,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,kBAAkB,EACvB,SAAS,GACT,qBAAqB,GACrB,SAAS,GACT,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,GAChB,aAAa,CAAC;IAClB,QAAQ,CAAC,2BAA2B,EAAE,OAAO,CAAC;IAC9C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,uBAAuB,EAAE;QAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,QAAQ,EACb,gCAAgC,GAChC,eAAe,GACf,+BAA+B,GAC/B,aAAa,GACb,iBAAiB,CAAC;KACvB,GAAG,IAAI,CAAC;CACV;AAgeD,wBAAgB,yBAAyB,CACvC,SAAS,EACL,+BAA+B,GAC/B,+BAA+B,EACnC,MAAM,EAAE,6BAA6B,EACrC,kBAAkB,EAAE,0BAA0B,EAC9C,gBAAgB,EAAE,wBAAwB,GACzC,SAAS,kBAAkB,EAAE,CA2G/B"}
|