feat(cli): add deterministic patch reviews

.github/workflows/node-ci.yml

@@ -256,7 +256,7 @@ jobs:
         run: ./sdk/typescript/scripts/prepare-windows-test-root.ps1
 
       - name: Test shard ${{ matrix.shard }}
-        timeout-minutes: 10
+        timeout-minutes: 15
         env:
           TEMP: ${{ steps.windows-temp.outputs.path }}
           TMP: ${{ steps.windows-temp.outputs.path }}

README.md

@@ -16,10 +16,22 @@ Requires Node.js 22.13.0 or later and Python 3.10 or later.
 npm install @openai/codex-security
 codex-security login
 codex-security scan /path/to/directory
+codex-security scan /path/to/directory --patch --review-minimality --review-style
 ```
 
 For CI, set `OPENAI_API_KEY` instead of signing in.
 
+Add `--review-minimality` or `--review-style` to `scan --patch` or `patch`
+to trigger a deterministic review workflow. The CLI runs each selected review
+as a separate, independent, read-only model invocation: minimality first, then
+local coding style. Review scope comes from the Git delta observed after the
+author run, excluding pre-existing worktree changes. Both reviews are optional
+and disabled by default.
+Set `--max-review-revisions 5` to allow up to five author revisions across
+actionable review findings; later-stage revisions restart earlier reviews, and
+blocked reviews still stop immediately. The revision limit requires at least
+one selected review stage.
+
 ## TypeScript SDK
 
 Codex Security is a Javascript package:

sdk/typescript/README.md

@@ -857,6 +857,7 @@ npx @openai/codex-security validate "Possible SQL injection" --effort high
 npx @openai/codex-security patch OCCURRENCE_ID
 npx @openai/codex-security patch --scan SCAN_ID --severity high --json
 npx @openai/codex-security patch --scan SCAN_ID --severity high --create-pr
+npx @openai/codex-security patch --scan SCAN_ID --review-minimality --review-style
 npx @openai/codex-security patch --scan SCAN_ID --assess-patch-risk --create-pr
 npx @openai/codex-security patch --linear-issue SEC-123 --assess-patch-risk --create-pr
 ```
@@ -878,6 +879,20 @@ existing work is never included. If publication fails, run the printed
 `patch --resume-pr BRANCH` command in the same repository. It reuses the saved
 commit without rerunning Codex, but refuses to publish if the branch changed.
 
+Add `--review-minimality` or `--review-style` to `patch` or `scan --patch` for
+independent, read-only review stages. Minimality runs before style. The CLI
+derives each review from the candidate-only delta against a snapshot of the
+containing worktree, including after revisions, and excludes pre-existing
+changes. Nested Git repositories and submodules are separate patch targets.
+Automatic PR creation stops if a reviewed file had pre-existing changes, and a
+`verified` result without an observed candidate delta fails. Reviewer findings
+are hypotheses that the revision author validates against the repository.
+
+Both stages are off by default. `--max-review-revisions 5` allows up to five
+revisions across the selected stages; otherwise each stage permits one. After a
+later-stage revision, earlier selected stages run again. Reviewed scan results
+also include `patchRepository`, the Git worktree root used for patch paths.
+
 To patch Linear issues, repeat `--linear-issue ISSUE` (ID or URL), or use
 `--linear-project "PROJECT"` with an optional native JSON `--linear-filter`.
 Completed and canceled issues are excluded unless the filter sets `state`.

sdk/typescript/_bundled_plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-security",
-  "version": "0.1.60",
+  "version": "0.1.81",
   "description": "Codex Security workflows for security scans, analysis, and investigation.",
   "author": {
     "name": "OpenAI"

sdk/typescript/_bundled_plugin/schemas/patch-risk-assessment.schema.json

@@ -18,6 +18,9 @@
     "statusQuoRisk",
     "autoMergeExclusions",
     "affectedRuntimeRoots",
+    "importantCallers",
+    "riskDrivers",
+    "protectiveFactors",
     "materialBoundaries",
     "validation",
     "unknowns",
@@ -48,7 +51,8 @@
         "changedFiles": {"$ref": "#/$defs/stringList"},
         "sha256": {
           "type": "string",
-          "pattern": "^[0-9a-f]{64}$"
+          "maxLength": 64,
+          "pattern": "^[0-9a-fA-F]{64}$"
         }
       }
     },
@@ -137,30 +141,34 @@
           "invariant",
           "runtimeRoot",
           "counterexample",
+          "counterexampleSource",
           "legitimateControl",
+          "legitimateControlSource",
           "result"
         ],
         "properties": {
-          "id": {"$ref": "#/$defs/identifier"},
+          "id": {"$ref": "#/$defs/nonEmptyString"},
           "invariant": {"$ref": "#/$defs/nonEmptyString"},
           "runtimeRoot": {"$ref": "#/$defs/nonEmptyString"},
           "counterexample": {"$ref": "#/$defs/nonEmptyString"},
+          "counterexampleSource": {"$ref": "#/$defs/nonEmptyString"},
           "legitimateControl": {"$ref": "#/$defs/nonEmptyString"},
+          "legitimateControlSource": {"$ref": "#/$defs/nonEmptyString"},
           "result": {"enum": ["supported", "contradicted", "unresolved"]}
         }
       }
     },
     "validation": {
       "type": "array",
-      "minItems": 1,
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["name", "status", "protects"],
+        "required": ["name", "status", "protects", "relevant"],
         "properties": {
           "name": {"$ref": "#/$defs/nonEmptyString"},
           "status": {"enum": ["passed", "failed", "skipped", "unavailable"]},
-          "protects": {"$ref": "#/$defs/nonEmptyString"}
+          "protects": {"$ref": "#/$defs/nonEmptyString"},
+          "relevant": {"type": "boolean"}
         }
       }
     },
@@ -169,8 +177,9 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["summary", "decisionCritical"],
+        "required": ["id", "summary", "decisionCritical"],
         "properties": {
+          "id": {"$ref": "#/$defs/nonEmptyString"},
           "summary": {"$ref": "#/$defs/nonEmptyString"},
           "decisionCritical": {"type": "boolean"}
         }
@@ -182,13 +191,20 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["question", "action", "outcomes"],
+        "required": ["question", "action", "resolvesUnknowns", "outcomes"],
         "properties": {
           "question": {"$ref": "#/$defs/nonEmptyString"},
           "action": {"$ref": "#/$defs/nonEmptyString"},
+          "resolvesUnknowns": {
+            "type": "array",
+            "minItems": 1,
+            "items": {"$ref": "#/$defs/nonEmptyString"},
+            "uniqueItems": true
+          },
           "outcomes": {
             "type": "object",
             "additionalProperties": {"$ref": "#/$defs/recommendation"},
+            "propertyNames": {"$ref": "#/$defs/nonEmptyString"},
             "minProperties": 2
           }
         }
@@ -198,11 +214,8 @@
   "$defs": {
     "nonEmptyString": {
       "type": "string",
-      "minLength": 1
-    },
-    "identifier": {
-      "type": "string",
-      "pattern": "^[a-z0-9][a-z0-9_-]*$"
+      "minLength": 1,
+      "pattern": "^[\\s\\S]*\\S[\\s\\S]*$"
     },
     "stringList": {
       "type": "array",

sdk/typescript/_bundled_plugin/scripts/finalize_scan_contract.py

@@ -1489,6 +1489,31 @@ def _schema_values_equal(left: Any, right: Any) -> bool:
     return left == right
 
 
+def _schema_value_key(value: Any) -> Any:
+    """Return a hashable key with the equality used by JSON Schema."""
+    if isinstance(value, bool):
+        return ("boolean", value)
+    if isinstance(value, (int, float)):
+        if isinstance(value, float) and math.isnan(value):
+            # NaN is never equal, including to itself.
+            return ("number", object())
+        return ("number", value)
+    if value is None:
+        return ("null",)
+    if isinstance(value, str):
+        return ("string", value)
+    if isinstance(value, list):
+        return ("array", tuple(_schema_value_key(item) for item in value))
+    if isinstance(value, dict):
+        return (
+            "object",
+            frozenset(
+                (key, _schema_value_key(item)) for key, item in value.items()
+            ),
+        )
+    return ("value", type(value), value)
+
+
 def _resolve_schema_reference(
     root_schema: dict[str, Any], reference: str, context: str
 ) -> dict[str, Any]:
@@ -1539,6 +1564,8 @@ def _validate_schema_node(
     if isinstance(value, str):
         if schema.get("minLength", 0) and len(value) < schema["minLength"]:
             raise ContractError(f"{context}: string is too short")
+        if "maxLength" in schema and len(value) > schema["maxLength"]:
+            raise ContractError(f"{context}: string is too long")
         if "pattern" in schema and not re.fullmatch(schema["pattern"], value):
             raise ContractError(f"{context}: string does not match schema pattern")
         if schema.get("format") == "date-time":
@@ -1554,12 +1581,12 @@ def _validate_schema_node(
         if "maxItems" in schema and len(value) > schema["maxItems"]:
             raise ContractError(f"{context}: array has too many items")
         if schema.get("uniqueItems") is True:
-            for index, item in enumerate(value):
-                if any(
-                    _schema_values_equal(item, candidate)
-                    for candidate in value[:index]
-                ):
+            seen_items: set[Any] = set()
+            for item in value:
+                key = _schema_value_key(item)
+                if key in seen_items:
                     raise ContractError(f"{context}: array items must be unique")
+                seen_items.add(key)
         contains = schema.get("contains")
         if isinstance(contains, dict):
             matches = 0
@@ -1598,6 +1625,15 @@ def _validate_schema_node(
                 raise ContractError(f"{context}.{key}: missing required schema property")
         if "minProperties" in schema and len(value) < schema["minProperties"]:
             raise ContractError(f"{context}: object has too few properties")
+        property_names = schema.get("propertyNames")
+        if isinstance(property_names, dict):
+            for key in value:
+                _validate_schema_node(
+                    key,
+                    property_names,
+                    f"{context} property name",
+                    root_schema,
+                )
         properties = schema.get("properties", {})
         additional_properties = schema.get("additionalProperties", True)
         for key, item in value.items():

sdk/typescript/_bundled_plugin/skills/assess-patch-risk/SKILL.md

@@ -55,10 +55,10 @@ Return both a concise Markdown report and a JSON object conforming to [`../../sc
 2. recommendation and workflow label;
 3. impact, likelihood, regression protection, recoverability, and confidence ratings with evidence, plus any strict auto-merge exclusions;
 4. affected production roots, important callers, contracts, and state;
-5. strongest counterexample and legitimate control for each material boundary;
-6. relevant tests and checks, including whether they ran and what they actually protect;
+5. strongest counterexample and legitimate control for each material boundary, with `counterexampleSource` and `legitimateControlSource` locations;
+6. tests and checks, including whether they ran, what they protect, and an explicit `relevant` classification;
 7. top risk drivers, protective factors, and status-quo risk; and
-8. unknowns plus the bounded evidence plan when held.
+8. stable ids for unknowns plus the bounded evidence plan when held; each plan action lists the unknown ids it resolves in `resolvesUnknowns`.
 
 This skill lives at `<plugin-root>/skills/assess-patch-risk/SKILL.md`, so
 `<plugin-root>` is two directories up. Resolve `<python_command>` to the