perttool 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,51 @@ This project records its notable changes here. The format is based on [Keep a Ch
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-26
+
+Contract 4 beta release. This version atomically publishes temporal and
+deadline-aware planning, exact unit migration, and Grammar 3. It intentionally
+changes public result identities and extends the CLI surface while retaining
+suffix-free `0.x.x` beta product maturity.
+
+### Added
+
+- Added Grammar 2 project `as_of`, milestone `deadline`, and task
+  `not_before`/`deadline` fields, plus Grammar 3 exact reduced Fraction
+  Durations alongside ordinary Decimals.
+- Added exact release-aware precedence and heuristic resource schedules,
+  deterministic calendar projection, and separate task, milestone, and
+  project deadline evidence in `Perttool.AnalysisResult.v3`.
+- Added preview-first `project migrate-unit` with complete Duration inventory,
+  exact Point/hour/day conversion, Decimal-or-Fraction output, coordinated
+  grammar upgrades, velocity disposition, no-op/repeat behavior, qualified
+  inverse results, and digest-locked safe writes through
+  `Perttool.UnitMigrationResult.v2`.
+
+### Changed
+
+- Activated CLI Contract 4 through one 28-command registry that drives
+  dispatch, option validation, text/JSON help, structured recovery, temporal
+  entity mutation, Guide, README, and installed-package behavior.
+- Replaced the public check, project, analysis, and next projections with
+  their accepted Contract 4 identities. `Perttool.NextResult.v4` preserves
+  Recommendation v1 ranking and adds fail-closed temporal start authority;
+  temporal eligibility gates the recommended set without substituting the
+  heuristic scheduler's runnable set.
+- Extended the isolated installed-package file-first workflow through Grammar
+  3 reads and writes, temporal/deadline analysis, complete NextResult v4,
+  forward/repeated/inverse exact migration, and public Core export checks.
+- Promoted the accepted `perttool@0.2.0` Contract 3 beta to npm `latest`
+  through a separate, explicitly authorized post-acceptance dist-tag
+  operation. Contract 4 publication itself keeps `latest` at `0.2.0`.
+
+### Fixed
+
+- Preserved every Contract 3 `task set --clear` value when adding temporal
+  task fields to the Contract 4 descriptor.
+- Preserved Recommendation set authority when its selected task differs from
+  the heuristic resource scheduler's first runnable task.
+
 ## [0.2.0] - 2026-07-25
 
 Contract 3 beta release. This version intentionally replaces the Contract 2
@@ -96,7 +141,8 @@ First public development preview. Intended to evaluate the DSL and CLI, read-onl
 - Not published to the npm registry; use the GitHub Release asset
 - Requires Node.js 24 or later
 
-[Unreleased]: https://github.com/mako10k/perttool/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/mako10k/perttool/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/mako10k/perttool/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/mako10k/perttool/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/mako10k/perttool/compare/v0.1.0-alpha.2...v0.1.0
 [0.1.0-alpha.2]: https://github.com/mako10k/perttool/compare/v0.1.0-alpha.1...v0.1.0-alpha.2

package/README.md

@@ -5,54 +5,57 @@ It validates an Activity-on-Arrow plan, calculates precedence and
 resource-constrained schedules, recommends the next task, and applies
 source-preserving changes through preview-first commands.
 
-The current Contract 3 version is `0.2.0`. Beta releases may contain breaking
-CLI or schema changes. Version `0.2.0` requires Node.js 22 or later. The prior
-`0.1.0` artifact uses CLI Contract 2 and declares Node.js 24.
+The current Contract 4 version is `0.3.0`. Beta releases may contain breaking
+CLI or schema changes. Version `0.3.0` requires Node.js 22 or later. Contract 3
+remains available by pinning `0.2.0`.
 
 ## Run without installing
 
-Use `npx` for an occasional invocation and select Contract 3 explicitly:
+Use `npx` for an occasional invocation and select Contract 4 explicitly:
 
 ```sh
-npx --yes --package=perttool@0.2.0 -- perttool --version
-npx --yes --package=perttool@0.2.0 -- perttool document check PLAN.pert
-npx --yes --package=perttool@0.2.0 -- perttool dag next PLAN.pert --format json
+npx --yes --package=perttool@0.3.0 -- perttool --version
+npx --yes --package=perttool@0.3.0 -- perttool document check PLAN.pert
+npx --yes --package=perttool@0.3.0 -- perttool dag next PLAN.pert --format json
+npx --yes --package=perttool@0.3.0 -- perttool project migrate-unit PLAN.pert --to-unit day --diff
 ```
 
 The equivalent explicit `npm exec` form is:
 
 ```sh
-npm exec --yes --package=perttool@0.2.0 -- perttool --version
-npm exec --yes --package=perttool@0.2.0 -- perttool document check PLAN.pert
-npm exec --yes --package=perttool@0.2.0 -- perttool dag analyze PLAN.pert
+npm exec --yes --package=perttool@0.3.0 -- perttool --version
+npm exec --yes --package=perttool@0.3.0 -- perttool document check PLAN.pert
+npm exec --yes --package=perttool@0.3.0 -- perttool dag analyze PLAN.pert
+npm exec --yes --package=perttool@0.3.0 -- perttool project migrate-unit PLAN.pert --to-unit day --diff
 ```
 
 `npx` and `npm exec` may download the selected package version into the npm
-cache. Pinning `0.1.0` selects the prior Contract 2 interface and therefore
-does not accept the commands in this README.
+cache. Pinning `0.2.0` selects Contract 3 and therefore does not accept the
+temporal and migration surface in this README.
 
 ## Install
 
 Install the CLI globally when it is used regularly:
 
 ```sh
-npm install --global perttool@0.2.0
+npm install --global perttool@0.3.0
 perttool --version
 ```
 
-npm `beta` resolves to Contract 3 `0.2.0`. npm `latest` remains on Contract 2
-`0.1.0` unless a later, separately authorized promotion occurs.
-`perttool@beta` is an alternative to the exact `0.2.0` pin.
+npm `beta` resolves to Contract 4 `0.3.0`. npm `latest` remains Contract 3
+`0.2.0`; publication does not promote it. Use `perttool@beta` as an alternative
+to the exact `0.3.0` pin.
 
 ## Plan files
 
 A `.pert` file is the source of truth and is intended to remain directly
-readable. This minimal plan has one one-day task:
+readable. This temporal plan has one one-day task:
 
 ```text
 project EXAMPLE:
-  version 1
+  version 2
   title "Example plan"
+  as_of 2026-07-26
   duration_unit day
   finish DONE
 
@@ -62,10 +65,13 @@ milestone NOW:
 
 milestone DONE:
   title "Done"
+  deadline 2026-07-28
 
 task WORK NOW -> DONE:
   title "Do the work"
   duration 1d
+  not_before 2026-07-26
+  deadline 2026-07-27
 ```
 
 Save it as `PLAN.pert`, then inspect it with:
@@ -80,7 +86,8 @@ perttool dag next PLAN.pert --format json
 Task duration can use deterministic `day`, `hour`, or relative `point` units.
 Point plans declare a project-wide velocity such as `20p/10d`. Analysis keeps
 the exact point result and reports the time conversion separately as a velocity
-forecast.
+forecast. Grammar version 3 also accepts an exact Fraction such as `1/3d`;
+versions 1 and 2 continue to accept Decimal duration tokens.
 
 ## Maintain a plan through the CLI
 
@@ -118,6 +125,8 @@ perttool project show PLAN.pert --format json
 # Apply the reviewed change atomically.
 perttool task set PLAN.pert WORK \
   --status active \
+  --not-before 2026-07-26 \
+  --deadline 2026-07-27 \
   --write \
   --expect-digest 'sha256:...'
 
@@ -147,6 +156,27 @@ perttool batch apply PLAN.pert \
   --expect-digest 'sha256:...'
 ```
 
+Use the dedicated migration route for exact whole-document conversion between
+Point and time units. Preview before writing; the result inventories every
+converted field and reports grammar upgrades and reversibility:
+
+```sh
+perttool project migrate-unit PLAN.pert --to-unit day --diff
+perttool project migrate-unit PLAN.pert \
+  --to-unit day \
+  --write \
+  --expect-digest 'sha256:...'
+
+# A time-to-Point conversion requires an explicit relationship when needed.
+perttool project migrate-unit PLAN.pert \
+  --to-unit point \
+  --replacement-velocity 20p/10d \
+  --diff
+```
+
+Migration is not a `batch apply` member. Re-read and reanalyze the written
+candidate before making a separate mutation.
+
 ## Command map
 
 | Goal | Command |
@@ -158,6 +188,7 @@ perttool batch apply PLAN.pert \
 | Initialize a project | `perttool project init ...` |
 | Read project metadata | `perttool project show <file>` |
 | Change project metadata | `perttool project set <file> ...` |
+| Migrate project units exactly | `perttool project migrate-unit <file> ...` |
 | Analyze schedules | `perttool dag analyze <file>` |
 | Select next work | `perttool dag next <file>` |
 | Remove completed history | `perttool dag advance <file>` |
@@ -182,20 +213,22 @@ perttool guide editing --level detail --format json
 ## LLM and automation use
 
 Use `--format json` for machine consumers. Check both
-`cli_contract_version == 3` and the result-specific `schema_version` before
-reading the rest of a result. A complete, known `Perttool.NextResult.v3`
-recommendation graph is the task-selection authority; do not infer authority
-from the text summary or from `ready` alone.
+`cli_contract_version == 4` and the result-specific `schema_version` before
+reading the rest of a result. A complete, known, non-truncated
+`Perttool.NextResult.v4` with temporal policy
+`recommendation_v1_plus_release_gate` is required. Start only task IDs in
+`temporal.authority.startable_recommended_task_ids`; do not infer start
+authority from the raw recommended set, the text summary, or `ready` alone.
 
 Mutation JSON returns the candidate text, unified diff, UTF-16 text edits,
 source digest, updated digest, diagnostics, and write result in one envelope.
-Unknown schema versions, incomplete recommendation traces, and `PTREC-*`
-diagnostics must fail closed.
+Unknown schema versions, incomplete recommendation traces, `PTREC-*`
+diagnostics, and future or unavailable temporal eligibility must fail closed.
 
 ## Documentation
 
-- [CLI Contract 3](docs/specs/cli-contract-3.md)
-- [Migration from CLI Contract 2](docs/process/cli-contract-3-migration.md)
+- [Temporal and Unit Interface Contract (CLI Contract 4)](docs/specs/temporal-unit-interface.md)
+- [CLI Contract 3 compatibility baseline](docs/specs/cli-contract-3.md)
 - [DSL grammar](docs/specs/dsl-grammar.md)
 - [Graph semantics](docs/specs/graph-semantics.md)
 - [Analysis semantics](docs/specs/analysis.md)

package/dist/analysis/temporal-deadline.d.ts

@@ -0,0 +1,59 @@
+import type { TargetCalendarDifference, TargetTemporalExactValue, TargetTemporalInputProjection } from "../application/target-temporal-input.js";
+import { type CalendarUnavailableCause } from "../model/calendar-arithmetic.js";
+import type { TargetCalendarValue } from "../model/target-calendar.js";
+import type { TargetGrammar3ValidatedDocument } from "../semantic/target-validator.js";
+import type { TemporalPrecedenceSchedule } from "./temporal-precedence.js";
+import type { TemporalResourceSchedule } from "./temporal-resource.js";
+export declare const DEADLINE_EVALUATION_IDENTITY: Readonly<{
+    id: "perttool.deadline-evaluation";
+    version: 1;
+}>;
+export type DeadlineCause = CalendarUnavailableCause | "complete_actual_time_unavailable" | "release_bound_unavailable" | "precedence_projection_unavailable" | "resource_projection_unavailable" | "margin_unit_unavailable";
+export interface DeadlineUnavailableCause {
+    readonly cause: DeadlineCause;
+    readonly underlyingCause: string | null;
+    readonly subjectKind: "task" | "milestone" | null;
+    readonly subjectId: string | null;
+    readonly taskId: string | null;
+}
+export interface DeadlineCurrentState {
+    readonly state: "not_due" | "due_now" | "overdue" | "not_applicable" | "unavailable";
+    readonly signedWindow: TargetCalendarDifference | null;
+    readonly baseUnitWindow: TargetTemporalExactValue | null;
+    readonly unavailableCauses: readonly DeadlineUnavailableCause[];
+}
+export interface DeadlineView {
+    readonly state: "not_applicable" | "unavailable" | "available";
+    readonly projectedCompletion: TargetCalendarValue | null;
+    readonly forecastRelation: "before_deadline" | "on_deadline" | "after_deadline" | null;
+    readonly signedMargin: TargetCalendarDifference | null;
+    readonly baseUnitMargin: TargetTemporalExactValue | null;
+    readonly remainingMargin: TargetTemporalExactValue | null;
+    readonly lateness: TargetTemporalExactValue | null;
+    readonly assessment: "lower_bound_on_time" | "lower_bound_late" | "heuristic_on_time" | "heuristic_late" | null;
+    readonly optimal: boolean | null;
+    readonly conditionalOnBlocksResolved: boolean;
+    readonly blockedTaskIds: readonly string[];
+    readonly unavailableCauses: readonly DeadlineUnavailableCause[];
+}
+export interface DeadlineEvaluation {
+    readonly subject: {
+        readonly kind: "task" | "milestone";
+        readonly id: string;
+        readonly roles: readonly ("task" | "milestone" | "project_finish")[];
+    };
+    readonly deadline: TargetCalendarValue;
+    readonly completionState: "incomplete" | "complete_actual_time_unavailable";
+    readonly current: DeadlineCurrentState;
+    readonly precedence: DeadlineView;
+    readonly resource: DeadlineView;
+    readonly combinedAssessment: "overdue" | "forecast_infeasible" | "at_risk" | "forecast_on_time" | "not_proven_late" | "not_applicable" | "unavailable";
+    readonly conditionalOnBlocksResolved: boolean;
+    readonly blockedTaskIds: readonly string[];
+    readonly destinationRelationship: {
+        readonly milestoneId: string;
+        readonly relation: "task_deadline_before_milestone" | "same_deadline" | "task_deadline_after_milestone" | "unavailable" | "deadline_absent";
+    } | null;
+}
+export declare function evaluateTemporalDeadlines(validated: TargetGrammar3ValidatedDocument, inputs: TargetTemporalInputProjection, precedenceSchedule: TemporalPrecedenceSchedule, resourceSchedule: TemporalResourceSchedule): readonly DeadlineEvaluation[];
+//# sourceMappingURL=temporal-deadline.d.ts.map

package/dist/analysis/temporal-deadline.d.ts.map

@@ -0,0 +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,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;AA8dD,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,+BAA+B,EAC1C,MAAM,EAAE,6BAA6B,EACrC,kBAAkB,EAAE,0BAA0B,EAC9C,gBAAgB,EAAE,wBAAwB,GACzC,SAAS,kBAAkB,EAAE,CA2G/B"}