PR 8.8: Entity progression dimension (phase vs level)

- Added phase and level fields
- Enforced type-based conditional requirements

Author: DavidQ

docs/dev/codex_commands.md

@@ -3,10 +3,11 @@ REASONING: medium
 
 TASK:
 - Update workspace.schema.json:
-  - Replace sampleId usage with id
-  - Add type field requirement
-  - Ensure entity array structure matches manifest
-- Ensure no additionalProperties allowed
+  - Add phase and level fields
+  - Add conditional rules:
+    - sample → phase required, level forbidden
+    - game → level required, phase forbidden
+- Validate manifest against schema
 - Do NOT modify runtime
 - Do NOT add validators
 - Do NOT modify start_of_day

docs/dev/commit_comment.txt

@@ -1,5 +1,4 @@
-PR 8.7: Workspace schema aligned to id/type structure
+PR 8.8: Entity progression dimension (phase vs level)
 
-- Removed sampleId from schema
-- Added id + type requirements
-- Enforced strict entity shape
+- Added phase and level fields
+- Enforced type-based conditional requirements

docs/pr/PR_8.8_ENTITY_PROGRESS_DIMENSION.md

@@ -0,0 +1,67 @@
+# PR 8.8 — Entity Progress Dimension (phase vs level)
+
+## Purpose
+Support different progression dimensions per entity type:
+- Samples → phase
+- Games → level
+
+## Change
+
+### workspace.schema.json
+
+Add optional progression fields with type constraint:
+
+```json
+{
+  "phase": { "type": "string" },
+  "level": { "type": "string" }
+}
+```
+
+### Rules
+
+- If type == "sample":
+  - phase REQUIRED
+  - level MUST NOT exist
+
+- If type == "game":
+  - level REQUIRED
+  - phase MUST NOT exist
+
+- Other types:
+  - neither required unless defined later
+
+## Enforcement (schema intent)
+- Use conditional validation (`if/then`)
+- Disallow invalid combinations
+
+## Example
+
+Sample:
+```json
+{
+  "id": "0305",
+  "type": "sample",
+  "phase": "03",
+  "tool": "vector-map-editor"
+}
+```
+
+Game:
+```json
+{
+  "id": "game-001",
+  "type": "game",
+  "level": "1",
+  "tool": "engine-runtime"
+}
+```
+
+## Non-Goals
+- no runtime logic
+- no validators
+
+## Acceptance
+- samples require phase
+- games require level
+- no mixed usage allowed

tools/schemas/workspace.schema.json

@@ -2,7 +2,12 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "tools/schemas/workspace.schema.json",
   "type": "object",
-  "required": ["documentKind", "schema", "version", "samples"],
+  "required": [
+    "documentKind",
+    "schema",
+    "version",
+    "samples"
+  ],
   "additionalProperties": false,
   "properties": {
     "documentKind": {
@@ -19,10 +24,13 @@
     },
     "samples": {
       "type": "array",
-      "uniqueItems": true,
       "items": {
         "type": "object",
-        "required": ["id", "type", "tool"],
+        "required": [
+          "id",
+          "type",
+          "tool"
+        ],
         "additionalProperties": false,
         "properties": {
           "id": {
@@ -31,30 +39,82 @@
           },
           "type": {
             "type": "string",
-            "minLength": 1
+            "enum": [
+              "sample",
+              "game"
+            ]
           },
           "phase": {
             "type": "string",
             "minLength": 1
           },
+          "level": {
+            "type": "string",
+            "minLength": 1
+          },
           "tool": {
             "type": "string",
             "minLength": 1
           },
           "tools": {
             "type": "array",
-            "uniqueItems": true,
             "items": {
               "type": "string",
               "minLength": 1
-            }
+            },
+            "uniqueItems": true
           },
           "palette": {
             "type": "string",
             "minLength": 1
           }
         },
-        "description": "id must be unique across samples."
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "type": {
+                  "const": "sample"
+                }
+              },
+              "required": [
+                "type"
+              ]
+            },
+            "then": {
+              "required": [
+                "phase"
+              ],
+              "not": {
+                "required": [
+                  "level"
+                ]
+              }
+            }
+          },
+          {
+            "if": {
+              "properties": {
+                "type": {
+                  "const": "game"
+                }
+              },
+              "required": [
+                "type"
+              ]
+            },
+            "then": {
+              "required": [
+                "level"
+              ],
+              "not": {
+                "required": [
+                  "phase"
+                ]
+              }
+            }
+          }
+        ]
       }
     }
   }