perttool 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,70 +1,149 @@
 # Changelog
 
-このプロジェクトの主な変更を記録する。形式は[Keep a Changelog](https://keepachangelog.com/ja/1.1.0/)を参考にし、versionは[Semantic Versioning](https://semver.org/lang/ja/)に従う。
+This project records its notable changes here. The format is based on [Keep a Changelog](https://keepachangelog.com/ja/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/lang/ja/).
 
 ## [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
+command names and JSON envelope while retaining suffix-free `0.x.x` beta
+product maturity.
+
+### Changed
+
+- Activated CLI Contract 3 as one breaking source-level cutover: `document
+  check|format`, `guide`, and `batch apply` replace the Contract 2 `dsl` and
+  `mutation` spellings; every CLI JSON envelope now identifies contract 3;
+  command dispatch, validation, and text/JSON help share the active typed
+  registry; and obsolete spellings fail with structured usage recovery.
+- Accepted the complete file-first Contract 3 workflow from an isolated
+  installed tarball, covering initialization, direct file inspection, every
+  project/task/gate/milestone/resource field, analysis, recommendation,
+  completion, advance, and final validation without manual `.pert` rewriting.
+- Selected suffix-free beta `0.2.0` as the first Contract 3 package target and
+  added a gated release plan that separates local preparation from explicitly
+  authorized Git, GitHub, and npm distribution; package, lockfile, and CLI
+  identity are prepared as `0.2.0`.
+- Promoted the accepted `perttool@0.1.0` beta to npm `latest` through an explicit post-release dist-tag operation. This changes the default install target without changing beta product maturity.
+- Lowered the source and next-release runtime baseline from Node.js 24 to maintained Node.js 22, with CI coverage for Node.js 22 and 24.
+- Reworked the root README as a user guide with `npx` and `npm exec` examples, and moved repository setup and verification to `docs/development.md`.
+- Recorded the complete English-surface inventory, Unicode allowlist, CLI/LLM surface review, and the structured-help, project-init, and gate-mutation backlog.
+
+### Added
+
+- Public `help` command discovery, separate `guide` domain topics,
+  preview-first `project init`, and direct source-preserving
+  `gate add|set|remove` commands.
+
 ## [0.1.0] - 2026-07-23
 
 First beta release. This suffix-free `0.x.x` series remains prerelease product maturity, permits intentional alpha incompatibility, and publishes through the npm `beta` dist-tag without moving `latest`.
 
 ### Added
 
-- Codex、GitHub Copilot、Claude Code、Grok Build、Antigravityのoffline profileを同じCoreからindex/quick/detailのtext/JSONへ公開するread-only `agent help`
-- velocityを含むproject metadata一式をtext/JSONで取得する`project show`と、preview-firstで局所更新する`project set`、atomic batch用`project.set`
-- 最初のbeta後の独立backlogとして、LSP server、コードハイライト/LSP clientを持つVSIX、MCP serverを明文化
+- Read-only `agent help`, which exposes offline profiles for Codex, GitHub Copilot, Claude Code, Grok Build, and Antigravity from the same Core as index/quick/detail text/JSON
+- `project show`, which retrieves complete project metadata including velocity as text/JSON; preview-first `project set` for localized updates; and `project.set` for atomic batches
+- An explicit independent post-first-beta backlog for an LSP server, a VSIX with syntax highlighting/LSP client, and an MCP server
 
 ### Changed
 
-- 最初のbetaをsuffixなし`0.1.0`、以後の`0.x.x`をbetaと定義し、alphaからのstrict compatibilityと追加soakをbeta gateから外した
-- Issue #2のread-only AI Agent Guidance Registryをbeta受け入れ条件とmacro/detail計画へ追加した
+- Defined the first beta as suffix-free `0.1.0` and subsequent `0.x.x` releases as beta, removing strict compatibility from alpha and additional soak time from the beta gate
+- Added the read-only AI Agent Guidance Registry from Issue #2 to beta acceptance criteria and macro/detail plans
 - Adopted English as the canonical repository language without i18n and added a phased, post-beta migration plan for legacy Japanese surfaces
 
 ## [0.1.0-alpha.2] - 2026-07-23
 
-2回目の公開開発プレビュー。安全な編集・進行操作、Mermaid相互変換、説明可能なtask recommendationを追加し、同じartifactをGitHub Releaseとnpmの`alpha` tagへ配布する。
+Second public development preview. Adds safe editing and advance operations, Mermaid round trips, and explainable task recommendations, and distributes the same artifact to GitHub Releases and npm's `alpha` tag.
 
 ### Added
 
-- `dsl format`とtask/milestone/resource/batch mutationのatomic `--write`、exclusive `--out`、`--expect-digest`
-- `Perttool.MermaidProfile.v1`のsemantic record、integrity digest、fail-closed import設計契約と規範artifact
-- `exportMermaid` Coreと`dag render --to mermaid`のlossless/plain profile、解析annotation、strict loss、exclusive `--out`
-- `importMermaid` Coreと`dag import --from mermaid`のfail-closed profile復元、plain loss report、strict loss、exclusive `--out`
-- canonical keep/remove set、partial join、idempotenceを保証するpure `planAdvance` Coreとpreview-first `dag advance` CLI
-- exact typed fact、comparison、decision trace、canonical descriptionを持つcomplete recommendation graphとpublic `NextResultV3` Core型
-- 5つのself-use planでv3 contract、byte determinism、operational互換、structured why-notを検査するrecommendation shadow gateとgolden
-- feasible replacement、`PTOVR-101`から`PTOVR-106`、caller-asserted human reason、normal trace reference、deterministic `Perttool.OverrideDecision.v1`を返すread-only `validateOverride` Core
-- completeかつknownな`NextResult.v3`をnormal AI task selection authorityへ採用する共有指示、help、unknown-version safe stop dry-run
-- npm publish normalizationを検査するpackage preflight、同一tarballをfail-closedでpublishするmaintainer script、`alpha` dist-tag固定
+- `dsl format`; atomic `--write` for task/milestone/resource/batch mutation; exclusive `--out`; and `--expect-digest`
+- Semantic records, integrity digests, fail-closed import design contracts, and normative artifacts for `Perttool.MermaidProfile.v1`
+- `exportMermaid` Core and lossless/plain profiles, analysis annotations, strict loss, and exclusive `--out` for `dag render --to mermaid`
+- `importMermaid` Core and fail-closed profile restoration, plain loss reports, strict loss, and exclusive `--out` for `dag import --from mermaid`
+- Pure `planAdvance` Core guaranteeing canonical keep/remove sets, partial joins, and idempotence, plus preview-first `dag advance` CLI
+- Complete recommendation graph with exact typed facts, comparisons, decision traces, and canonical descriptions, plus the public `NextResultV3` Core type
+- Recommendation shadow gate and golden tests that inspect the v3 contract, byte determinism, operational compatibility, and structured why-not across five self-use plans
+- Read-only `validateOverride` Core returning feasible replacements, `PTOVR-101` through `PTOVR-106`, caller-asserted human reasons, normal-trace references, and deterministic `Perttool.OverrideDecision.v1`
+- Shared instructions, help, and unknown-version safe-stop dry run that adopt complete, known `NextResult.v3` as the normal AI task-selection authority
+- Package preflight that checks npm publish normalization, a maintainer script that fail-closed publishes the identical tarball, and fixed `alpha` dist-tag
 
 ### Changed
 
-- pre-release breaking changeとして`dag next`のdefault JSONを`Perttool.NextResult.v2`から`Perttool.NextResult.v3`へ変更し、Core、CLI JSON/text、help、packageをatomicに公開
-- npmがCLI entrypointを除去しないよう`bin.perttool`をcanonicalな`dist/cli.js`へ修正
+- Changed the default `dag next` JSON from `Perttool.NextResult.v2` to `Perttool.NextResult.v3` as a pre-release breaking change, publishing Core, CLI JSON/text, help, and package atomically
+- Corrected `bin.perttool` to canonical `dist/cli.js` so npm does not remove the CLI entry point
 
 ## [0.1.0-alpha.1] - 2026-07-21
 
-最初の公開開発プレビュー。DSLとCLIの評価、read-onlyな計画検査・分析・次task選択を目的とする。stable MVPではなく、互換性のない変更が入る可能性がある。
+First public development preview. Intended to evaluate the DSL and CLI, read-only plan checking and analysis, and next-task selection. It is not a stable MVP and may include incompatible changes.
 
 ### Added
 
-- Activity-on-Arrow DSLのparser、semantic/graph validation、複数error recovery
-- exact Rationalを使うPERT/CPM precedence分析とcritical path列挙
-- renewable resource capacityを扱う決定的`parallel-sgs` heuristic schedule
-- `active`、`ready`、`runnable_now`、`blocked_now`、`upcoming`の機械的判定
-- Point見積りとproject-wide velocityによるday/hour forecast
-- text/JSON CLI、構造化help、stable diagnostic codeとsource span
-- `npm link`およびGitHub Release tarballによるCLI導入
+- Activity-on-Arrow DSL parser, semantic/graph validation, and multiple-error recovery
+- PERT/CPM precedence analysis and critical-path enumeration using exact Rational values
+- Deterministic `parallel-sgs` heuristic schedule handling renewable resource capacity
+- Mechanical determination of `active`, `ready`, `runnable_now`, `blocked_now`, and `upcoming`
+- Day/hour forecasts from point estimates and project-wide velocity
+- Text/JSON CLI, structured help, stable diagnostic codes, and source spans
+- CLI installation through `npm link` and GitHub Release tarballs
 
 ### Known limitations
 
-- `dsl format`、task/milestone/resource mutation、`dag advance`は未実装
-- Mermaid import/exportは未実装
-- Resource scheduleは`optimal=false`のheuristicであり、厳密最適解ではない
-- npm registryには未公開。GitHub Release assetを使用する
-- Node.js 24以上が必要
+- `dsl format`, task/milestone/resource mutation, and `dag advance` are unimplemented
+- Mermaid import/export is unimplemented
+- The resource schedule is a heuristic with `optimal=false`, not an exact optimum
+- 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.1.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
 [0.1.0-alpha.1]: https://github.com/mako10k/perttool/releases/tag/v0.1.0-alpha.1

package/README.md

@@ -1,150 +1,245 @@
 # perttool
 
-PERT 線図を、Git 管理しやすい文書として記述・検査・分析するためのタスク管理CLI。
-
-現在のcheckoutでは、`dsl check`、`dsl format`、`dsl help`、read-only `agent help`、`project show`、`project set`、`dag analyze`、`dag next`、`dag advance`、`dag render --to mermaid`、`dag import --from mermaid`、source-preservingなproject/task/milestone/resource/batch mutation、atomic `--write`、exclusive `--out`、`--expect-digest`を実装済みです。`project show`はvelocityを含むproject metadata一式、`dag next`はcompleteなrecommendation graphを持つ`Perttool.NextResult.v3`、`agent help`は5 providerのoffline profileをindex/quick/detailのtext/JSONで返します。いずれもpublic Core型とCLIを同じ判断へ接続します。Node.js 24以上が必要で、pre-release中は互換性のない変更が入る可能性があります。
-
-`0.1.0` is the first beta release. Suffix-free `0.x.x` versions are the beta series, and strict compatibility with the alpha series is not guaranteed. This release includes the read-only AI Agent Guidance Registry from Issue #2.
-
-- [要件定義](docs/requirements.md)
-- [基本設計](docs/basic-design.md)
-- [DSL 文法仕様](docs/specs/dsl-grammar.md)
-- [Graph Semantics 仕様](docs/specs/graph-semantics.md)
-- [Analysis 仕様](docs/specs/analysis.md)
-- [Mutation Semantics 仕様](docs/specs/mutation.md)
-- [Mermaid Profile 仕様](docs/specs/mermaid-profile.md)
-- [Recommendation Semantics 仕様](docs/specs/recommendation.md)
-- [Recommendation Ranking Policy 仕様](docs/specs/recommendation-ranking.md)
-- [Recommendation Reason Taxonomy 仕様](docs/specs/recommendation-reasons.md)
-- [Recommendation Structured Explanation 仕様](docs/specs/recommendation-explanation.md)
-- [Recommendation Interface Contract 仕様](docs/specs/recommendation-interface.md)
-- [Recommendation Human Override Contract 仕様](docs/specs/recommendation-override.md)
-- [Recommendation 規範例](docs/examples/recommendation.md)
-- [AI Agent Guidance Registry 仕様](docs/specs/agent-guidance.md)
-- [AI Agent Guidance Registry 規範例](docs/examples/agent-guidance.md)
-- [Mermaid Profile 規範例](docs/examples/mermaid-profile.md)
-- [Recommendation 実装・自己利用migration](docs/process/recommendation-migration.md)
-- [NextResult.v3 consumer migration guide](docs/process/next-v3-consumer-migration.md)
-- [Recommendation 設計受け入れレビュー](docs/process/recommendation-design-review.md)
-- [MVP release readiness監査](docs/process/mvp-release-readiness.md)
-- [Beta versioning ADR](docs/adr/0003-beta-versioning.md)
-- [Beta release手順](docs/process/beta-release.md)
-- [English repository baseline ADR](docs/adr/0004-english-repository-baseline.md)
-- [CLI Interface 仕様](docs/specs/interfaces.md)
-- [Architecture Decision Records](docs/adr/0001-activity-on-arrow.md)
-- [DSL サンプル](docs/examples/README.md)
-- [自己利用計画](docs/process/self-use.md)
-- [MVPからbetaへのmacro計画](plans/mvp.pert)
-- [現在の文法作業計画](plans/grammar.pert)
-- [AI工程制御設計計画](plans/control-plane.pert)
-- [操作系M1-M4実装計画](plans/operations.pert)
-- [Recommendation実装計画](plans/recommendation.pert)
-- [AI Agent Guidance実装計画](plans/agent-guidance.pert)
-- [English baseline migration plan](plans/english-baseline.pert)
-- [AI 開発ガイド](docs/process/ai-development.md)
-
-基本方針は次のとおりです。
-
-- Activity-on-Arrow とし、タスクを DAG のエッジ、マイルストーンをノードとして扱う
-- 独自 DSL 文書をプロジェクト状態の正本とする
-- PERT/CPM 計算と「次のタスク」の判定を機械的かつ決定的に行う
-- 相対見積り`p`を基準に保持し、明示したproject-wide velocityで`d`または`h`の予測へexact換算する
-- 共有resourceのcapacityから排他実行と並列実行可能数を扱う
-- Mermaid との相互変換、CLI、構造化ヘルプ、AI向けJSON操作導線を同じ共通コア上に提供する
-- MVPはCLIをprimary interfaceとし、LSP server、コードハイライト/LSP clientを持つVSIX、MCP serverは最初のbeta後の独立backlogとして追加する
-- 現行文書は現在と未来を表し、過去は Git 履歴で追跡する
-- parser・check・analyze・next が安定した時点で、文法作業の計画から自己利用を開始する
+`perttool` is a local CLI for keeping PERT/CPM plans in reviewable text files.
+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.
 
-## Install
+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
 
-Install the current beta from the npm `beta` dist-tag. Maintainers must follow the [beta release procedure](docs/process/beta-release.md) and publish the exact release tarball without moving `latest`.
+Use `npx` for an occasional invocation and select Contract 4 explicitly:
 
 ```sh
-npm install --global perttool@beta
-perttool --version
+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
 ```
 
-ローカルcheckoutを開発中のNode.jsユーザー環境へlinkする場合:
+The equivalent explicit `npm exec` form is:
 
 ```sh
-git clone https://github.com/mako10k/perttool.git
-cd perttool
-npm ci
-npm link
+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.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.3.0
 perttool --version
 ```
 
-`prepare` lifecycleが`dist/`をbuildしてから、`perttool` binaryを現在のnpm global prefixへsymlinkします。System領域へsudoでinstallせず、NVMなどuser-ownedのnpm prefixを使用してください。解除はcheckoutで`npm unlink --global perttool`を実行します。
+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 temporal plan has one one-day task:
 
-## Development
+```text
+project EXAMPLE:
+  version 2
+  title "Example plan"
+  as_of 2026-07-26
+  duration_unit day
+  finish DONE
 
-Setupとrepository check:
+milestone NOW:
+  title "Current frontier"
+  state reached
+
+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:
 
 ```sh
-npm ci
-npm run check
+perttool document check PLAN.pert
+perttool project show PLAN.pert
+perttool dag analyze PLAN.pert
+perttool dag next PLAN.pert --format json
 ```
 
-実CLI processを使うE2Eシナリオだけを実行する場合:
+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. 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
+
+Read the file for its complete human-facing state. Use CLI maintenance commands
+so that each candidate is parsed and semantically checked before it can be
+written. To bootstrap a plan without hand-authoring syntax, preview the
+smallest valid document and then create a new file exclusively:
 
 ```sh
-npm run test:e2e
+perttool project init EXAMPLE \
+  --title "Example plan" \
+  --duration-unit day \
+  --initial-milestone NOW \
+  --initial-milestone-title "Current frontier" \
+  --finish NOW
+
+perttool project init EXAMPLE \
+  --title "Example plan" \
+  --duration-unit day \
+  --initial-milestone NOW \
+  --initial-milestone-title "Current frontier" \
+  --finish NOW \
+  --out PLAN.pert
 ```
 
-## CLI examples
+For an existing plan:
 
 ```sh
-perttool --help
-perttool dsl check docs/examples/parallel.pert
-perttool dsl check PLAN.pert --max-diagnostics 20 --format json
-perttool dsl format PLAN.pert --check
-perttool dsl format PLAN.pert --diff
-perttool dsl format PLAN.pert --write --expect-digest "$EXPECTED_DIGEST"
-perttool dsl help syntax estimate --level detail --format json
-perttool dsl help syntax velocity --level detail --format json
-perttool agent help
-perttool agent help codex enforcement --level detail --format json
+# Preview a source-preserving change.
+perttool task set PLAN.pert WORK --status active --diff
+
+# Obtain the current digest for optimistic locking.
 perttool project show PLAN.pert --format json
-perttool project set PLAN.pert --velocity 20p/1d --diff
-perttool project set PLAN.pert --velocity 20p/1d --write --expect-digest "$EXPECTED_DIGEST"
-perttool dag analyze docs/examples/point-velocity.pert --format json
-perttool dag analyze docs/examples/parallel.pert
-perttool dag analyze docs/examples/parallel.pert --capacity DEVELOPERS=3 --capacity TEST_ENV=2 --format json
-perttool dag next docs/examples/parallel.pert
-perttool dag next docs/examples/parallel.pert --capacity DEVELOPERS=3 --format json
-perttool dag advance docs/examples/advance-partial-before.pert --diff
-perttool dag advance PLAN.pert --write --expect-digest "$EXPECTED_DIGEST"
-perttool dag render docs/examples/parallel.pert --to mermaid --analysis both
-perttool dag render docs/examples/parallel.pert --to mermaid --analysis resource --capacity TEST_ENV=2 --out parallel.mmd
-perttool dag import parallel.mmd --from mermaid
-perttool dag import parallel.mmd --from mermaid --strict-loss --out parallel.pert
-perttool task set docs/examples/minimal.pert WORK --status active --diff
-perttool task set PLAN.pert WORK --status active --write --expect-digest "$EXPECTED_DIGEST"
-perttool resource set docs/examples/parallel.pert TEST_ENV --capacity 2 --format json
-perttool mutation apply docs/examples/minimal.pert --request changes.json --diff
-perttool mutation apply PLAN.pert --request changes.json --out UPDATED.pert
-```
 
-`dag analyze`はexact RationalによるPERT/CPMと、renewable resource capacityを守る決定的な`parallel-sgs` scheduleを別resultとして返します。`duration_unit point`では`velocity 20p/10d`のように宣言し、基準のPoint値とday/hourの`velocity_forecast`を分離して返します。Resource scheduleは実行可能なheuristicであり、最適解とは表示しません。
+# 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:...'
+
+# Finish a task, inspect the new frontier, then remove completed history.
+perttool task finish PLAN.pert WORK --diff
+perttool dag next PLAN.pert --format json
+perttool dag advance PLAN.pert --diff
+```
 
-`project show`はproject ID、version、title、description、as_of、duration_unit、velocity、finish、critical_epsilon、target_durationを固定順のtextまたは`Perttool.ProjectResult.v1` JSONで返します。`project set`は同じfieldをsource-preservingに変更し、optional fieldは`--clear`できます。既定は検査済みcandidateのpreviewで、永続化は他のediting commandと同じsafe-write optionを明示した場合だけです。Project-wide単位とtask durationを同時変更する場合は、`mutation apply`のatomic batchへ`project.set`と関連entity mutationを含めます。
+All formatter and mutation commands preview by default. `--write` replaces the
+input through the safe-write path, while `--out` exclusively creates a new
+file. Gate maintenance uses the same controls:
 
-`dag next`は依存関係上の`ready`、既存schedulerが選ぶ`runnable_now`、工程authorityであるroot `recommendation`を分離します。JSONは全ready taskのtier、exact typed fact、comparison、decision trace、canonical descriptionをcomplete graphとして返し、textは4 tierの`complete=false` summaryとJSON導線を返します。開始できないready taskには不足resourceと占有task、upcoming taskには未充足依存の説明も従来どおり保持します。Consumerは[移行ガイド](docs/process/next-v3-consumer-migration.md)に従い、`schema_version`を最初に検査します。
+```sh
+perttool gate add PLAN.pert APPROVAL NOW DONE \
+  --reason "Approval required" \
+  --diff
+```
 
-Known and complete `NextResult.v3` is the normal AI task-selection authority after the original five-plan shadow and the MIG-07 safe-stop dry run. The self-use gate now checks seven plans, including agent guidance and the explicitly blocked post-beta English-baseline migration. Select a workstream from the macro recommendation before analyzing its detail plan, and stop on unknown versions, incomplete traces, `PTREC-*`, or deferred/discouraged selections.
+Use `batch apply` when several changes must become valid atomically:
 
-Public libraryの`validateOverride`はcompleteな`NextResultV3`と明示的なhuman requestから、normal recommendationを変更せずdeterministicな`Perttool.OverrideDecision.v1`を生成します。これはread-only validationであり、task state、file、Git、networkを変更しません。Override applyとaudit writeのCLIは未実装です。
+```sh
+perttool batch apply PLAN.pert --request changes.json --diff
+perttool batch apply PLAN.pert \
+  --request changes.json \
+  --write \
+  --expect-digest 'sha256:...'
+```
 
-`dag advance`はeffective reachedより過去のtask/gate/milestoneだけを除去し、未到達joinに必要なdone taskとsatisfied gateを保持します。既定はcandidate previewで、削除entityとfrontier/readyの前後比較をtext/JSONへ含めます。`--write`、`--out`、`--expect-digest`は他のediting commandと同じsafe-write経路を使います。
+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:
 
-`dag render --to mermaid`は既定でlosslessな`Perttool.MermaidProfile.v1`をstdoutへ生成します。`--analysis`でprecedence/resource解析値をprojectionへ注記でき、`--out`は既存targetを上書きしません。`--profile plain`はsemantic metadataを持たないため`PTCNV-206`を返し、`--strict-loss`でartifactを拒否できます。
+```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
+```
 
-`dag import --from mermaid`はperttool profileのcanonical JSON、record順、metadata/projection digest、semantic model、projection対応をfail-closedで検査し、canonical DSLをpreviewします。Plain Mermaidはstable generated IDとloss reportを返す限定best-effortで、`--strict-loss`はlossy candidateと`--out`を拒否します。
+Migration is not a `batch apply` member. Re-read and reanalyze the written
+candidate before making a separate mutation.
+
+## Command map
+
+| Goal | Command |
+| --- | --- |
+| Discover commands | `perttool help [resource [action]]` |
+| Read domain guidance | `perttool guide [topic [subtopic]]` |
+| Validate a document | `perttool document check <file>` |
+| Canonically format it | `perttool document format <file>` |
+| 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>` |
+| Export or import Mermaid | `perttool dag render`, `perttool dag import` |
+| Maintain tasks | `perttool task add|set|remove|finish` |
+| Maintain gates | `perttool gate add|set|remove` |
+| Maintain milestones | `perttool milestone add|set|remove` |
+| Maintain resources | `perttool resource add|set|remove` |
+| Apply an atomic batch | `perttool batch apply` |
+| Read coding-agent guidance | `perttool agent help` |
+
+Run `perttool --help` for the text command catalog. `help` is the complete
+command contract for humans and machine consumers, while `guide` explains
+domain concepts. Both run without a document:
 
-`dsl format`とMutation commandは既定では検査済みcandidateをpreviewし、`--diff`ではunified diffを返します。`dsl format --check`は変更が必要なときだけexit 1です。Preview確認後は`--write`でinitial digestを再照合してatomic replaceし、`--expect-digest`でcaller lockを追加できます。`--out`は既存targetを上書きせず新規documentを作成します。`--format json`ではcandidate、diff、UTF-16 TextEdit、digest、write結果を同じresultへ含めます。
+```sh
+perttool task set --help
+perttool help dag next --format json
+perttool guide editing --level detail --format json
+```
 
-現在は[MVPからbetaへのmacro計画](plans/mvp.pert)をroadmapとするStage 3のpreview-first自己利用を行っています。MVP public alphaに続き、Issue #2のread-only AI Agent Guidance Registry v1も[受け入れました](docs/process/agent-guidance-acceptance.md)。5 provider baseline、公開contract、version付きoffline profile、validator、query、index/quick/detail projection、deterministic JSON/text、structured command help、`agent help` CLI、package-installed Core/CLI parity、security境界を全checkで検証し、固有実測Velocityを全22p/1 active dayの`22p/1d`へ補正しました。利用者の明示指示で先行した`PROJECT_METADATA_CLI`を含む操作系実測Velocityは29p/2 active dayの`29p/2d`です。Macroの唯一のready、`runnable_now`、recommended taskは`BETA_RELEASE_E2E`で、残存makespanは1dです。Issue #3、LSP server、VSIX、MCP serverはbeta blockerに含めません。
+## LLM and automation use
+
+Use `--format json` for machine consumers. Check both
+`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, `PTREC-*`
+diagnostics, and future or unavailable temporal eligibility must fail closed.
+
+## Documentation
+
+- [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)
+- [Mutation semantics](docs/specs/mutation.md)
+- [Recommendation semantics](docs/specs/recommendation.md)
+- [Examples](docs/examples/README.md)
+- [Developer guide](docs/development.md)
+- [Product backlog](docs/backlog.md)
 
 ## Security and license
 
-脆弱性は[Security Policy](SECURITY.md)に従って非公開で報告してください。本ソフトウェアは[MIT License](LICENSE)で公開します。変更履歴と既知の制約は[CHANGELOG](CHANGELOG.md)を参照してください。
+Report vulnerabilities privately according to [SECURITY.md](SECURITY.md).
+perttool is released under the [MIT License](LICENSE). See
+[CHANGELOG.md](CHANGELOG.md) for release changes and known limitations.

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":"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"}