perttool 0.5.1 → 0.5.3

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.3] - 2026-07-30
+
+Compatible CLI Contract 6 and Grammar 5 beta patch. This version retires the
+obsolete alpha publication path and tightens the caller workflow for loose
+owner-confirmation assertions without changing command, option, result,
+schema, or runtime payload identities.
+
+### Changed
+
+- Retired the obsolete npm `alpha` distribution channel and restricted the
+  maintainer publication guard to `beta`. Historical alpha packages remain
+  available by exact version pin.
+- Tightened loose owner-confirmation guidance so callers begin with an
+  assertion-free preview, explicitly identify affected scopes, review
+  human-readable timestamps, sizes, and diffs before supplemental digests, and
+  never carry `--accepted-by-owner` into ordinary maintenance or a later
+  candidate.
+
+## [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 +270,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.1...HEAD
+[Unreleased]: https://github.com/mako10k/perttool/compare/v0.5.3...HEAD
+[0.5.3]: https://github.com/mako10k/perttool/compare/v0.5.2...v0.5.3
+[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,39 @@ 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.3` 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,
+Git 2.54 UTC compatibility, and scope-bound human-readable confirmation
+guidance. npm `beta` resolves to `0.5.3`; `latest`
+remains on the separately accepted `0.5.1`. Beta releases may contain
+breaking CLI or schema changes. Version `0.5.3` requires Node.js 22 or later.
+The complete-schema Contract 6 artifact remains available by pinning `0.5.2`,
+and 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. npm has no maintained `alpha`
+dist-tag; historical `0.1.0-alpha.2` remains available by exact pin.
 
 ## 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.3 -- perttool --version
+npx --yes --package=perttool@0.5.3 -- perttool document check PLAN.pert
+npx --yes --package=perttool@0.5.3 -- perttool dag next PLAN.pert --format json
+npx --yes --package=perttool@0.5.3 -- 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.3 -- perttool --version
+npm exec --yes --package=perttool@0.5.3 -- perttool document check PLAN.pert
+npm exec --yes --package=perttool@0.5.3 -- perttool dag analyze PLAN.pert
+npm exec --yes --package=perttool@0.5.3 -- perttool project history PLAN.pert --format json
 ```
 
 `npx` and `npm exec` may download the selected package version into the npm
@@ -46,14 +50,17 @@ 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.3`; `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`. The retired alpha
+preview remains installable only as the exact pin
+`perttool@0.1.0-alpha.2`.
 
 ## Plan files
 
@@ -184,6 +191,17 @@ pre-change document determines owners and delegates, and an atomic batch must
 satisfy every affected scope. These assertions are not authentication,
 verified identity, signatures, or a durable approval audit.
 
+Treat each `--accepted-by-owner` value as a single-candidate, scope-bound
+caller assertion rather than workstream or session authority. First preview
+without it. Omit it when the result reports `governance.applicable=false`.
+Before a non-direct governed write, identify the operation, affected scopes,
+required owners, available modification time, byte size before and after, diff
+counts, and semantic candidate summary. Keep source and candidate digests as
+supplemental machine identity rather than the primary human explanation;
+never copy the assertion to later maintenance, a changed candidate, or the
+next `dag advance`. See the
+[loose assertion scope experiment](docs/process/governance-assertion-scope-experiment.md).
+
 Contract 5 previews may still omit actor and owner confirmation. A Contract 4
 runtime fails closed on Grammar 4 and governance options; there is no
 `--cli-contract 4` switch, compatibility alias, or environment toggle. Pin
@@ -309,6 +327,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 +341,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 +363,13 @@ 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.3`, `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`.
+Scope-bound, human-readable loose owner-confirmation guidance requires
+`0.5.3`.
 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));
     }