perttool 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -4,6 +4,24 @@ 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
@@ -234,7 +252,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.5.1...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

package/README.md

@@ -5,35 +5,36 @@ 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.
 
-Version `0.5.1` beta 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. It adds
-Draft 2020-12 artifacts for every active Contract 6 result and the public
-OverrideDecision result, plus Git 2.54 UTC compatibility. npm `beta` resolves
-to `0.5.1`, while `latest` remains on Contract 5 `0.4.0`. Beta releases may
-contain breaking CLI or schema changes. Version `0.5.1` requires Node.js 22
-or later. The compatible pre-schema Contract 6 artifact remains available by
-pinning `0.5.0`; Contract 5, Contract 4, and Contract 3 remain available by
-pinning `0.4.0`, `0.3.0`, and `0.2.0`, respectively.
+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.1 -- perttool --version
-npx --yes --package=perttool@0.5.1 -- perttool document check PLAN.pert
-npx --yes --package=perttool@0.5.1 -- perttool dag next PLAN.pert --format json
-npx --yes --package=perttool@0.5.1 -- 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.1 -- perttool --version
-npm exec --yes --package=perttool@0.5.1 -- perttool document check PLAN.pert
-npm exec --yes --package=perttool@0.5.1 -- perttool dag analyze PLAN.pert
-npm exec --yes --package=perttool@0.5.1 -- 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
@@ -46,14 +47,15 @@ Contract 3.
 Install the CLI globally when it is used regularly:
 
 ```sh
-npm install --global perttool@0.5.1
+npm install --global perttool
 perttool --version
 ```
 
-npm `beta` resolves to Contract 6 `0.5.1`, while `latest` remains on
-Contract 5 `0.4.0`. The prior 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`.
+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
 
@@ -309,6 +311,7 @@ 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
 ```
 
@@ -322,6 +325,17 @@ Supplying a schema identity returns its Draft 2020-12 artifact in the
 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
@@ -333,10 +347,11 @@ select compatibility from each result's `schema_version`, not from
 
 ## LLM and automation use
 
-Use `--format json` for machine consumers. `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`.
+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

package/dist/cli.js

@@ -2547,8 +2547,25 @@ function runJsonSchema(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);
+    const result = getJsonSchemaResult(parsed.positionals[0] ?? null, {
+        ...(view === undefined ? {} : { view }),
+        ...(reference === undefined ? {} : { ref: reference }),
+    });
     if (format === "json") {
         process.stdout.write(serializeJsonSchemaResult(result));
     }