@research-engineering/agentic-proofkit 0.1.157 → 0.1.159

package/proofkit/{cli-contract.v1.json → cli-contract.v2.json}

@@ -1,15 +1,33 @@
 {
-  "schemaVersion": 1,
-  "contractId": "proofkit.cli-contract.v1",
+  "schemaVersion": 2,
+  "contractId": "proofkit.cli-contract.v2",
   "packageName": "@research-engineering/agentic-proofkit",
   "processContract": {
     "successExitCode": 0,
     "failureExitCode": 1,
     "stdout": "Successful JSON commands write exactly one JSON value to stdout unless an admitted explicit output-file flag writes that JSON value to the selected path and leaves stdout empty. Successful text or help commands write text to stdout unless an admitted explicit output-file flag writes the selected representation to the selected path and leaves stdout empty. Commands do not write stderr on success.",
     "stderr": "Argument parsing, unsupported command, input admission, and output serialization failures write human diagnostics to stderr. Failed report commands may still write a machine-readable failed report to stdout when admission succeeds. Opt-in agent-envelope repair packets may write deterministic invalid-input JSON to stdout with exit code 1 and empty stderr.",
+    "globalOptions": {
+      "jsonLayout": {
+        "flag": "--json-layout",
+        "position": "before_command",
+        "values": [
+          "compact",
+          "pretty"
+        ],
+        "default": "pretty",
+        "scope": "json_output_only"
+      }
+    },
     "helpGrammar": {
-      "rootHelpFlags": ["--help", "-h"],
-      "commandHelpFlags": ["--help", "-h"],
+      "rootHelpFlags": [
+        "--help",
+        "-h"
+      ],
+      "commandHelpFlags": [
+        "--help",
+        "-h"
+      ],
       "helpCommandPositionalTarget": "optional_supported_command",
       "helpCatalogFormsSource": "proofkit/command-families.v1.json",
       "helpReadsCommandInput": false
@@ -132,8 +150,14 @@
                   "readiness_closeout_input",
                   "registry_consumer_input",
                   "release_authority_input",
+                  "requirement_context_catalog",
+                  "requirement_context_repo_root",
+                  "requirement_context_slice_input",
+                  "requirement_semantic_diff_input",
                   "requirement_source",
                   "requirement_source_transition",
+                  "requirement_traceability_graph_input",
+                  "requirement_workspace_input",
                   "scaffold_profile_plan",
                   "scaffold_project_structure",
                   "selective_evidence",
@@ -170,11 +194,14 @@
               "check_overview_claims",
               "decide_obligations",
               "inspect_coverage",
+              "inspect_requirement_context",
+              "inspect_requirement_traceability",
               "inventory_tests",
               "plan_selective_checks",
               "release_or_deploy_evidence",
               "render_human_view",
               "retire_local_infrastructure",
+              "review_requirement_change",
               "scaffold_first_module",
               "unknown",
               "validate_requirement_source",
@@ -249,6 +276,49 @@
           "This input contract describes agent-route admission only.",
           "It does not validate referenced file contents, execute commands, read repositories, or approve merge."
         ]
+      },
+      "outputContract": {
+        "contractId": "proofkit.agent-route.output.v2",
+        "schemaVersion": 2,
+        "authority": "deterministic route report derived from admitted agent-route input",
+        "requiredFields": [
+          "guidanceSlice",
+          "reportId",
+          "reportKind",
+          "schemaVersion",
+          "selectedRouteFamily",
+          "state"
+        ],
+        "fields": {
+          "schemaVersion": {
+            "value": 2
+          },
+          "selectedRouteFamily": {
+            "enum": [
+              "adoption",
+              "migration",
+              "release_and_deployment",
+              "rendered_views",
+              "repository_structure",
+              "requirement_proof_binding",
+              "requirement_source",
+              "selective_evidence",
+              "selective_planning",
+              "test_inventory_and_coverage",
+              "unknown"
+            ]
+          },
+          "guidanceSlice": {
+            "requiredFields": [
+              "routeFamily"
+            ],
+            "routeFamilyRule": "must equal selectedRouteFamily"
+          }
+        },
+        "changesFromV1": [
+          "selectedFamily is replaced by selectedRouteFamily",
+          "guidanceSlice.family is replaced by guidanceSlice.routeFamily"
+        ]
       }
     },
     {
@@ -974,10 +1044,82 @@
         "--port",
         "--scope",
         "--serve",
+        "--session-mode",
+        "--session-timeout-seconds",
         "--view"
       ],
       "requiredFlags": [
         "--view"
+      ],
+      "flagValueRequirements": [
+        {
+          "flag": "--session-mode",
+          "requiredFlags": [
+            "--open",
+            "--serve",
+            "--view"
+          ],
+          "value": "one-shot-question"
+        }
+      ],
+      "inputContract": {
+        "schemaVersion": 1,
+        "workspaceRequiredFields": [
+          "context",
+          "schemaVersion",
+          "workspaceId"
+        ],
+        "workspaceOptionalFields": [
+          "diffInput",
+          "graphInput"
+        ],
+        "sessionModeValues": [
+          "browse",
+          "one-shot-question"
+        ],
+        "sessionTimeoutSeconds": {
+          "minimum": 1,
+          "maximum": 7200,
+          "requiresSessionMode": "one-shot-question"
+        },
+        "oneShotRequirements": {
+          "open": true,
+          "serve": true,
+          "view": "workspace"
+        },
+        "jsonLayoutRule": "allowed for non-serving JSON plans; serving and one-shot modes reject the global layout option because one-shot terminal packets are fixed compact JSON"
+      }
+    },
+    {
+      "command": "requirement-context-compose",
+      "input": "required",
+      "stdin": true,
+      "inputPointer": true,
+      "scopeClass": "explicit_filesystem_scan",
+      "outputModes": [
+        "json"
+      ],
+      "allowedFlags": [
+        "--input",
+        "--input-pointer",
+        "--repo-root"
+      ],
+      "requiredFlags": [
+        "--repo-root"
+      ]
+    },
+    {
+      "command": "requirement-context-slice",
+      "input": "required",
+      "stdin": true,
+      "inputPointer": true,
+      "scopeClass": "explicit_caller_input",
+      "outputModes": [
+        "json"
+      ],
+      "allowedFlags": [
+        "--input",
+        "--input-pointer"
       ]
     },
     {
@@ -1278,6 +1420,20 @@
         "--scope"
       ]
     },
+    {
+      "command": "requirement-semantic-diff",
+      "input": "required",
+      "stdin": true,
+      "inputPointer": true,
+      "scopeClass": "explicit_caller_input",
+      "outputModes": [
+        "json"
+      ],
+      "allowedFlags": [
+        "--input",
+        "--input-pointer"
+      ]
+    },
     {
       "command": "requirement-source-admission",
       "input": "required",
@@ -1331,7 +1487,15 @@
       "scopeClass": "explicit_caller_input",
       "inputContract": {
         "schemaVersion": 2,
-        "requiredFields": ["schemaVersion", "treeId", "rootNodeId", "callerAnnotations", "nodes", "edges", "overlays"],
+        "requiredFields": [
+          "schemaVersion",
+          "treeId",
+          "rootNodeId",
+          "callerAnnotations",
+          "nodes",
+          "edges",
+          "overlays"
+        ],
         "callerTextAuthority": "callerAnnotations fields are untrusted presentation annotations and never command-owned nonClaims"
       },
       "outputModes": [
@@ -1350,7 +1514,15 @@
       "scopeClass": "explicit_caller_input",
       "inputContract": {
         "schemaVersion": 2,
-        "requiredFields": ["schemaVersion", "treeId", "rootNodeId", "callerAnnotations", "nodes", "edges", "overlays"],
+        "requiredFields": [
+          "schemaVersion",
+          "treeId",
+          "rootNodeId",
+          "callerAnnotations",
+          "nodes",
+          "edges",
+          "overlays"
+        ],
         "callerTextAuthority": "callerAnnotations fields are untrusted presentation annotations and never command-owned nonClaims"
       },
       "outputModes": [
@@ -1368,7 +1540,10 @@
         "contractId": "proofkit.requirement-spec-tree-view.output.v2",
         "schemaVersion": 2,
         "authority": "requirement spec tree view output contract",
-        "nonJsonFormats": ["html", "markdown"],
+        "nonJsonFormats": [
+          "html",
+          "markdown"
+        ],
         "requiredFields": [
           "authority",
           "nodeCount",
@@ -1382,6 +1557,20 @@
         ]
       }
     },
+    {
+      "command": "requirement-traceability-graph",
+      "input": "required",
+      "stdin": true,
+      "inputPointer": true,
+      "scopeClass": "explicit_caller_input",
+      "outputModes": [
+        "json"
+      ],
+      "allowedFlags": [
+        "--input",
+        "--input-pointer"
+      ]
+    },
     {
       "command": "scaffold-profile-plan",
       "input": "required",
@@ -1836,7 +2025,71 @@
       ],
       "requiredFlags": [
         "--repo-root"
-      ]
+      ],
+      "inputContract": {
+        "contractId": "proofkit.typescript-public-api-surfaces.input.v1",
+        "schemaVersion": 1,
+        "authority": "caller-owned manifest plus explicitly selected filesystem snapshot",
+        "fields": {
+          "schemaVersion": {
+            "required": true,
+            "value": 1
+          },
+          "machineContract": {
+            "required": true,
+            "value": "public_api_surfaces"
+          },
+          "entries": {
+            "required": true,
+            "maxItems": 1024,
+            "item": {
+              "requiredFields": [
+                "exportConditions",
+                "exportKey",
+                "packageManifestPath",
+                "packageName",
+                "runtimeExports",
+                "typeExports"
+              ],
+              "optionalFields": [
+                "deniedExportKeys"
+              ],
+              "pathAuthority": "packageManifestPath names an explicit repo-relative package.json; every export condition names its explicit repo-relative non-JSX TypeScript sourcePath, and the canonical resolved source target must also have a .ts, .mts, or .cts extension",
+              "setFields": "deniedExportKeys, runtimeExports, and typeExports are sorted unique arrays",
+              "exportConditionsRule": "non-empty and sorted unique by condition"
+            }
+          }
+        },
+        "resourceBudgets": {
+          "maxSourceFileBytes": 8388608,
+          "maxPackageManifestBytes": 262144,
+          "maxAggregateFileReadBytes": 67108864
+        },
+        "sourceGrammar": {
+          "grammarId": "proofkit.typescript-public-api.export-subset.v1",
+          "mode": "fail_closed",
+          "identifierDomain": "direct ASCII identifiers in code; Unicode remains permitted inside comments and literals",
+          "admittedExportForms": [
+            "named runtime re-exports from a string module specifier",
+            "named type re-exports from a string module specifier",
+            "ASCII-named function, class, enum, interface, type, const, let, and var exports"
+          ],
+          "rejectedLexicalForms": [
+            "slash tokens outside comments, including division and regular-expression literals",
+            "template interpolation",
+            "escaped or direct non-ASCII code identifiers",
+            "unterminated comments or literals",
+            "unbalanced delimiters",
+            "top-level angle-bracket syntax in variable export declarations"
+          ]
+        },
+        "nonClaims": [
+          "The command does not infer conventional package or source layouts.",
+          "The command does not parse JSX or admit TSX source files.",
+          "The command does not parse unrestricted TypeScript; sources outside the documented export grammar fail closed.",
+          "Caller-owned source-to-condition mappings do not prove compiler output provenance, checkout freshness, package-manager truth, merge readiness, or rollout."
+        ]
+      }
     },
     {
       "command": "witness-plan",

package/proofkit/command-families.v1.json

@@ -110,6 +110,17 @@
         "workspace-manifest-facts"
       ]
     },
+    {
+      "familyId": "requirement-context-and-traceability",
+      "label": "Requirement context and traceability",
+      "purpose": "Compose bounded semantic context and derive diff and traceability projections.",
+      "commands": [
+        "requirement-context-compose",
+        "requirement-context-slice",
+        "requirement-semantic-diff",
+        "requirement-traceability-graph"
+      ]
+    },
     {
       "familyId": "requirement-navigation-and-rendering",
       "label": "Requirement navigation and rendering",