perttool 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -4,6 +4,42 @@ This project records its notable changes here. The format is based on [Keep a Ch
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-07-30
+
+Compatible CLI Contract 6 and Grammar 5 beta patch. This version completes
+the bundled result schemas and adds selectable full and reference-based
+outline projections without changing existing result identities or runtime
+payload meanings.
+
+### Added
+
+- Added full and reference-based outline views to `perttool schema`, including
+  separate lookup of one bundled `$ref` detail without changing default
+  complete-artifact output.
+
+### Fixed
+
+- Replaced underspecified nested JSON Schema object placeholders with complete
+  closed record definitions and added nested unknown-field rejection coverage.
+
+## [0.5.1] - 2026-07-30
+
+Compatible CLI Contract 6 and Grammar 5 beta patch. This version adds
+machine-readable result artifacts and corrects Git 2.54 UTC commit-time
+handling without changing existing result identities or payload meanings.
+
+### Added
+
+- Added bundled Draft 2020-12 artifacts for every active Contract 6 command
+  result and public `Perttool.OverrideDecision.v1`, with a closed public
+  catalog, `perttool schema`, package-root lookup APIs, and isolated package
+  validation.
+
+### Fixed
+
+- Accepted the strict ISO `Z` UTC form emitted by Git 2.54 for `%cI` commit
+  metadata while retaining fixed-offset validation.
+
 ## [0.5.0] - 2026-07-29
 
 Contract 6 beta release. This version atomically publishes Grammar 5,
@@ -216,7 +252,9 @@ 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.5.0...HEAD
+[Unreleased]: https://github.com/mako10k/perttool/compare/v0.5.2...HEAD
+[0.5.2]: https://github.com/mako10k/perttool/compare/v0.5.1...v0.5.2
+[0.5.1]: https://github.com/mako10k/perttool/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/mako10k/perttool/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/mako10k/perttool/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/mako10k/perttool/compare/v0.2.0...v0.3.0

package/README.md

@@ -5,38 +5,40 @@ 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 prepared `0.5.0` source implements Grammar 5 and CLI Contract 6,
+Version `0.5.2` beta implements Grammar 5 and CLI Contract 6,
 including explicit task work events, lifecycle commands, read-only Git
-history, observed velocity, AnalysisResult v4, and NextResult v5. Publication
-remains a gated operation; npm `beta` and `latest` still resolve to Contract 5
-`0.4.0` until that operation completes. Beta releases may contain breaking
-CLI or schema changes. Version `0.5.0` requires Node.js 22 or later. Contract
-5, Contract 4, and Contract 3 remain available by pinning `0.4.0`, `0.3.0`,
-and `0.2.0`, respectively.
+history, observed velocity, AnalysisResult v4, and NextResult v5. It adds
+complete Draft 2020-12 artifacts for every active Contract 6 result and the
+public OverrideDecision result, selectable full and outline schema views,
+and Git 2.54 UTC compatibility. npm `beta` resolves to `0.5.2`; `latest`
+remains on the separately accepted `0.5.1`. Beta releases may contain
+breaking CLI or schema changes. Version `0.5.2` requires Node.js 22 or later.
+The first machine-schema Contract 6 artifact remains available by pinning
+`0.5.1`; Contract 5, Contract 4, and Contract 3 remain available by pinning
+`0.4.0`, `0.3.0`, and `0.2.0`, respectively.
 
 ## Run without installing
 
 Use `npx` for an occasional invocation and select Contract 6 explicitly:
 
 ```sh
-npx --yes --package=perttool@0.5.0 -- perttool --version
-npx --yes --package=perttool@0.5.0 -- perttool document check PLAN.pert
-npx --yes --package=perttool@0.5.0 -- perttool dag next PLAN.pert --format json
-npx --yes --package=perttool@0.5.0 -- perttool project history PLAN.pert --format json
+npx --yes --package=perttool@0.5.2 -- perttool --version
+npx --yes --package=perttool@0.5.2 -- perttool document check PLAN.pert
+npx --yes --package=perttool@0.5.2 -- perttool dag next PLAN.pert --format json
+npx --yes --package=perttool@0.5.2 -- perttool project history PLAN.pert --format json
 ```
 
 The equivalent explicit `npm exec` form is:
 
 ```sh
-npm exec --yes --package=perttool@0.5.0 -- perttool --version
-npm exec --yes --package=perttool@0.5.0 -- perttool document check PLAN.pert
-npm exec --yes --package=perttool@0.5.0 -- perttool dag analyze PLAN.pert
-npm exec --yes --package=perttool@0.5.0 -- perttool project history PLAN.pert --format json
+npm exec --yes --package=perttool@0.5.2 -- perttool --version
+npm exec --yes --package=perttool@0.5.2 -- perttool document check PLAN.pert
+npm exec --yes --package=perttool@0.5.2 -- perttool dag analyze PLAN.pert
+npm exec --yes --package=perttool@0.5.2 -- perttool project history PLAN.pert --format json
 ```
 
 `npx` and `npm exec` may download the selected package version into the npm
-cache. The `0.5.0` registry commands become available only after the gated
-publication. Pinning `0.4.0` selects Contract 5 and therefore omits Grammar 5
+cache. Pinning `0.4.0` selects Contract 5 and therefore omits Grammar 5
 lifecycle and history; `0.3.0` selects Contract 4, and `0.2.0` selects
 Contract 3.
 
@@ -45,16 +47,15 @@ Contract 3.
 Install the CLI globally when it is used regularly:
 
 ```sh
-npm install --global perttool@0.5.0
+npm install --global perttool
 perttool --version
 ```
 
-The prepared release will move npm `beta` to Contract 6 `0.5.0` while leaving
-`latest` on Contract 5 `0.4.0`. Before publication, both tags still resolve
-to `0.4.0`, so use a locally packed `0.5.0` artifact for candidate testing.
-After publication, `perttool@beta` follows Contract 6. Contract 5, Contract 4,
-and Contract 3 remain available as exact pins `perttool@0.4.0`,
-`perttool@0.3.0`, and `perttool@0.2.0`.
+npm `beta` resolves to Contract 6 `0.5.2`; `latest` remains on accepted
+Contract 6 `0.5.1`. The pre-schema Contract 6 artifact remains available as
+`perttool@0.5.0`; Contract 5,
+Contract 4, and Contract 3 remain available as exact pins
+`perttool@0.4.0`, `perttool@0.3.0`, and `perttool@0.2.0`.
 
 ## Plan files
 
@@ -280,6 +281,7 @@ details.
 | Goal | Command |
 | --- | --- |
 | Discover commands | `perttool help [resource [action]]` |
+| Discover or read JSON Schemas | `perttool schema [schema-id]` |
 | Read domain guidance | `perttool guide [topic [subtopic]]` |
 | Validate a document | `perttool document check <file>` |
 | Canonically format it | `perttool document format <file>` |
@@ -307,15 +309,49 @@ domain concepts. Both run without a document:
 ```sh
 perttool task set --help
 perttool help dag next --format json
+perttool schema --format json
+perttool schema Perttool.NextResult.v5 --format json
+perttool schema Perttool.NextResult.v5 --view outline --format json
 perttool guide editing --level detail --format json
 ```
 
+### JSON Schema artifacts
+
+`perttool schema --format json` returns the complete result-schema catalog.
+Supplying a schema identity returns its Draft 2020-12 artifact in the
+`schema` field of `Perttool.SchemaResult.v1`:
+
+```sh
+perttool schema Perttool.CheckResult.v3 --format json
+```
+
+The default and `--view full` return the complete artifact. For a shorter
+outer shape, `--view outline` replaces complex nested records with absolute
+references to the complete bundled artifact. Pass one local, relative, or
+copied absolute reference back with `--ref` to display that internal layer:
+
+```sh
+perttool schema Perttool.NextResult.v5 --view outline --format json
+perttool schema Perttool.NextResult.v5 --view outline \
+  --ref '#/$defs/recommendation' --format json
+```
+
+Packed installations also expose each artifact at
+`perttool/schemas/<schema-id>.schema.json`; relative references resolve
+against the bundled `Perttool.Common.v1.schema.json`. The stable `$id` is an
+identifier only: validation does not require network access. Consumers must
+select compatibility from each result's `schema_version`, not from
+`tool_version`. See the
+[JSON Schema Artifact Contract](docs/specs/json-schema.md) for the complete
+18-result inventory and versioning rules.
+
 ## LLM and automation use
 
-Use `--format json` for machine consumers. Prepared `0.5.0` consumers must
-check `cli_contract_version == 6`; consumers of published `0.4.0` must
-continue to require Contract 5, and consumers pinned to `0.3.0` must require
-Contract 4.
+Use `--format json` for machine consumers. `0.5.2`, `0.5.1`, and `0.5.0`
+consumers must check `cli_contract_version == 6`; consumers pinned to `0.4.0`
+must continue to require Contract 5, and consumers pinned to `0.3.0` must
+require Contract 4. Bundled machine-readable result artifacts require
+`0.5.1`; complete nested records and outline/detail views require `0.5.2`.
 In every case, check the result-specific `schema_version` before reading the
 rest of a result.
 A complete, known, non-truncated `Perttool.NextResult.v5` with temporal policy
@@ -335,6 +371,8 @@ diagnostics, and future or unavailable temporal eligibility must fail closed.
 - [Temporal and Unit Interface Contract (CLI Contract 4)](docs/specs/temporal-unit-interface.md)
 - [Owner-Aware Governance Interface Contract (CLI Contract 5)](docs/specs/governance-interface.md)
 - [Project Actuals and Git History Contract (CLI Contract 6)](docs/specs/project-actuals.md)
+- [JSON Schema Artifact Contract](docs/specs/json-schema.md)
+- [JSON Schema source acceptance](docs/process/json-schema-acceptance.md)
 - [Contract 5-to-6 migration](docs/process/cli-contract-6-migration.md)
 - [Contract 4-to-5 migration](docs/process/cli-contract-5-migration.md)
 - [Issue #4 governance implementation acceptance](docs/process/governance-acceptance.md)

package/dist/cli.js

@@ -31,6 +31,7 @@ import { convertWithVelocity, durationSuffix } from "./model/units.js";
 import { recommendationInvariantExitCode } from "./recommendation/failure.js";
 import { recommendationAnalysisToJson } from "./recommendation/json.js";
 import { TARGET_GRAMMAR_5_CAPABILITY, } from "./parser/document-parser.js";
+import { getJsonSchemaResult, renderJsonSchemaResult, serializeJsonSchemaResult, } from "./schema/registry.js";
 import { TOOL_VERSION } from "./version.js";
 class UsageError extends Error {
     code = "PTCLI-001";
@@ -2541,6 +2542,44 @@ function runCommandHelp(args) {
     }
     return result.ok ? 0 : 1;
 }
+function runJsonSchema(args) {
+    const parsed = parseCommandOptions("schema", args);
+    if (parsed.positionals.length > 1) {
+        throw new UsageError("schema accepts at most one <schema-id>");
+    }
+    const viewValue = parsed.values.get("view");
+    const view = viewValue === undefined || viewValue === "full" || viewValue === "outline"
+        ? viewValue
+        : (() => {
+            throw new UsageError("--view must be full or outline");
+        })();
+    const reference = parsed.values.get("ref");
+    if (parsed.positionals.length === 0 &&
+        (view !== undefined || reference !== undefined)) {
+        throw new UsageError("schema view selection requires one <schema-id>");
+    }
+    if (reference !== undefined && view !== "outline") {
+        throw new UsageError("--ref requires --view outline");
+    }
+    const format = outputFormat(parsed.values.get("format"));
+    const result = getJsonSchemaResult(parsed.positionals[0] ?? null, {
+        ...(view === undefined ? {} : { view }),
+        ...(reference === undefined ? {} : { ref: reference }),
+    });
+    if (format === "json") {
+        process.stdout.write(serializeJsonSchemaResult(result));
+    }
+    else {
+        const rendered = renderJsonSchemaResult(result);
+        if (result.ok) {
+            process.stdout.write(rendered);
+        }
+        else {
+            process.stderr.write(rendered);
+        }
+    }
+    return result.ok ? 0 : 1;
+}
 function runAgentHelp(args) {
     const parsed = parseCommandOptions("agent.help", args);
     if (parsed.positionals.length > 2) {
@@ -2587,6 +2626,8 @@ async function dispatchCommand(descriptor, args) {
     switch (descriptor.operation) {
         case "help":
             return runCommandHelp(args);
+        case "schema":
+            return runJsonSchema(args);
         case "guide":
             return runGuide(args);
         case "document.check":