create-pathfinder 4.2.0 → 4.3.0

package/skills/render-artifact/engine/schemas/diagram.schema.json

@@ -0,0 +1,176 @@
+{
+  "$id": "diagram.schema.json",
+  "title": "Pathfinder artifact specification — diagram",
+  "description": "One diagram artifact. The producer describes the system: what exists, what each thing is, what relates to what, which things belong together, and which ordered walks matter. It describes no part of the canvas. Geometry, ranking, axis, size, spacing, routing, label placement, typography, shape, colour and emphasis are the renderer's, and the schema rejects an attempt at any of them rather than ignoring it.",
+  "type": "object",
+  "required": ["schema_version", "kind", "provenance", "artifact", "diagram"],
+  "additionalProperties": false,
+  "if": {
+    "description": "A derived diagram is the one that must declare where it was derived from. The requirement is conditional because a proposed diagram may legitimately have no repository behind it at all, and it is written as a conditional so the contract lives in the schema rather than only in code.",
+    "required": ["provenance"],
+    "properties": { "provenance": { "const": "derived" } }
+  },
+  "then": { "required": ["source"] },
+  "properties": {
+    "schema_version": { "$ref": "common.schema.json#/$defs/schema_version" },
+    "kind": { "const": "diagram" },
+    "provenance": {
+      "description": "What kind of claim this diagram makes, and the only thing that decides how strictly it is checked. `derived` maps what the repository asserts about itself at the declared commit: it requires a source, every node and edge carries a citation, claim-bearing prose on a group, path or view carries one, and `artifact.summary` is not permitted. `proposed` describes an intended system: citations are optional, and with no source they are refused outright. There is no default — a diagram that did not say would be assigned a trust level by the engine, and the engine has no business guessing which claim a producer meant to make.",
+      "enum": ["derived", "proposed"]
+    },
+    "artifact": { "$ref": "common.schema.json#/$defs/artifact" },
+    "source": { "$ref": "common.schema.json#/$defs/source" },
+    "diagram": {
+      "type": "object",
+      "required": ["topology", "nodes", "edges"],
+      "additionalProperties": false,
+      "properties": {
+        "topology": {
+          "description": "The structure of the graph, and the only discriminator. It selects the layout the renderer uses. `graph` — a directed graph with semantic roles, optional grouping and authored paths — is the only supported value; anything else is refused rather than approximated.",
+          "enum": ["graph"]
+        },
+        "nodes": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 40,
+          "items": { "$ref": "diagram.schema.json#/$defs/node" }
+        },
+        "groups": {
+          "description": "Boundaries. Which nodes belong together is meaning; whether a boundary is drawn as a box, a band or a tint is not.",
+          "type": "array",
+          "maxItems": 8,
+          "items": { "$ref": "diagram.schema.json#/$defs/group" }
+        },
+        "edges": {
+          "description": "Relationships. An empty list is legal: a diagram of things that do not yet relate is a diagram.",
+          "type": "array",
+          "maxItems": 80,
+          "items": { "$ref": "diagram.schema.json#/$defs/edge" }
+        },
+        "paths": {
+          "description": "Ordered walks that matter — a request flow, a clean run. A path names the edges it consists of, never the nodes, because two edges may join the same pair and a node sequence could not say which claim the path was making. Emphasis is derived from these: the producer says why something matters, and the renderer decides how much ink it gets.",
+          "type": "array",
+          "maxItems": 6,
+          "items": { "$ref": "diagram.schema.json#/$defs/path" }
+        },
+        "views": {
+          "description": "Authored focus sets — an argument about what matters together.",
+          "type": "array",
+          "maxItems": 6,
+          "items": { "$ref": "diagram.schema.json#/$defs/view" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "label": {
+      "description": "A short label the renderer places. The real cap is 32 columns and is enforced by the structural layer, because a column is not a character: `漢` is one character and two columns, and a combining mark is one character and none. `maxLength` here is only a sanity bound — a label may carry many more characters than columns once combining marks are counted, so it is set well above the column cap rather than duplicating it.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 400
+    },
+    "edge_label": {
+      "description": "Capped at 24 columns by the structural layer, on one line. `maxLength` is a sanity bound, as above.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 400
+    },
+    "role": {
+      "description": "What a node is, semantically. A closed vocabulary, because the renderer maps role to shape and colour and must never improvise a presentation for a value it does not know. Architecture roles and process roles share one vocabulary on purpose: a codebase map uses `service` and `store`, a migration map uses `step` and `decision`, and nothing in the renderer branches on which.",
+      "enum": [
+        "actor", "interface", "service", "store", "queue",
+        "job", "external", "step", "decision", "terminal"
+      ]
+    },
+    "relation": {
+      "description": "What one node does to another. Closed for the same reason as `role`.",
+      "enum": [
+        "calls", "reads", "writes", "publishes",
+        "consumes", "depends_on", "transitions_to", "triggers"
+      ]
+    },
+    "node": {
+      "type": "object",
+      "required": ["id", "label", "role"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "label": { "$ref": "diagram.schema.json#/$defs/label" },
+        "role": { "$ref": "diagram.schema.json#/$defs/role" },
+        "summary": { "type": "string", "minLength": 1, "maxLength": 1000 },
+        "detail": { "$ref": "common.schema.json#/$defs/prose" },
+        "group": {
+          "description": "The group this node belongs to, or nothing. A node belongs to at most one group: multiple membership is not a rule to detect later, it is a state this field cannot represent.",
+          "$ref": "common.schema.json#/$defs/identifier"
+        },
+        "evidence": { "$ref": "common.schema.json#/$defs/evidence" }
+      }
+    },
+    "group": {
+      "type": "object",
+      "required": ["id", "label"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "label": { "$ref": "diagram.schema.json#/$defs/label" },
+        "summary": { "type": "string", "minLength": 1, "maxLength": 1000 },
+        "parent": {
+          "description": "The group containing this one, or nothing. Nesting is one level: a parent must itself be a root.",
+          "$ref": "common.schema.json#/$defs/identifier"
+        },
+        "evidence": { "$ref": "common.schema.json#/$defs/evidence" }
+      }
+    },
+    "edge": {
+      "type": "object",
+      "required": ["id", "from", "to", "relation"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "description": "Required, because paths address edges by it and a highlight has to be exact.",
+          "$ref": "common.schema.json#/$defs/identifier"
+        },
+        "from": { "$ref": "common.schema.json#/$defs/identifier" },
+        "to": { "$ref": "common.schema.json#/$defs/identifier" },
+        "relation": { "$ref": "diagram.schema.json#/$defs/relation" },
+        "label": { "$ref": "diagram.schema.json#/$defs/edge_label" },
+        "evidence": { "$ref": "common.schema.json#/$defs/evidence" }
+      }
+    },
+    "path": {
+      "type": "object",
+      "required": ["id", "label", "edges"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "label": { "$ref": "diagram.schema.json#/$defs/label" },
+        "note": { "type": "string", "minLength": 1, "maxLength": 1000 },
+        "edges": {
+          "description": "Ordered edge ids. Each edge's target is the next edge's source, which is what makes the walk a walk.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 80,
+          "items": { "$ref": "common.schema.json#/$defs/identifier" }
+        },
+        "evidence": { "$ref": "common.schema.json#/$defs/evidence" }
+      }
+    },
+    "view": {
+      "type": "object",
+      "required": ["id", "label", "focus"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "label": { "$ref": "diagram.schema.json#/$defs/label" },
+        "note": { "type": "string", "minLength": 1, "maxLength": 1000 },
+        "focus": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 40,
+          "items": { "$ref": "common.schema.json#/$defs/identifier" }
+        },
+        "evidence": { "$ref": "common.schema.json#/$defs/evidence" }
+      }
+    }
+  }
+}

package/skills/render-artifact/engine/schemas/lesson.schema.json

@@ -0,0 +1,210 @@
+{
+  "$id": "lesson.schema.json",
+  "title": "Pathfinder artifact specification — lesson",
+  "description": "One lesson artifact. `learn-feature` supplies one module; `learn-codebase` supplies many. The same fields serve both: there is no consumer-specific field, branch, or escape hatch.",
+  "type": "object",
+  "required": ["schema_version", "kind", "artifact", "source", "lesson"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "$ref": "common.schema.json#/$defs/schema_version" },
+    "kind": { "const": "lesson" },
+    "artifact": { "$ref": "common.schema.json#/$defs/artifact" },
+    "source": { "$ref": "common.schema.json#/$defs/source" },
+    "lesson": {
+      "type": "object",
+      "required": ["modules"],
+      "additionalProperties": false,
+      "properties": {
+        "objectives": {
+          "description": "What a reader should be able to do afterwards. Renderer-owned chrome labels it; the producer owns the claims.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 20,
+          "items": { "type": "string", "minLength": 1, "maxLength": 400 }
+        },
+        "modules": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 60,
+          "items": { "$ref": "lesson.schema.json#/$defs/module" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "module": {
+      "description": "One unit of the lesson. A single module and sixty modules render through the same path; nothing branches on the count.",
+      "type": "object",
+      "required": ["id", "title", "sections"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "summary": { "type": "string", "minLength": 1, "maxLength": 1000 },
+        "requires": {
+          "description": "Module ids this module builds on. Optional: the module graph is allowed to be a flat list. Edges must resolve and must not form a cycle.",
+          "type": "array",
+          "maxItems": 20,
+          "items": { "$ref": "common.schema.json#/$defs/identifier" }
+        },
+        "sections": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 60,
+          "items": { "$ref": "lesson.schema.json#/$defs/section" }
+        }
+      }
+    },
+    "section": {
+      "description": "A section of a module, discriminated by `type`.",
+      "oneOf": [
+        { "$ref": "lesson.schema.json#/$defs/prose_section" },
+        { "$ref": "lesson.schema.json#/$defs/concept_section" },
+        { "$ref": "lesson.schema.json#/$defs/code_section" },
+        { "$ref": "lesson.schema.json#/$defs/flow_section" },
+        { "$ref": "lesson.schema.json#/$defs/quiz_section" },
+        { "$ref": "lesson.schema.json#/$defs/exercise_section" }
+      ]
+    },
+    "prose_section": {
+      "description": "Explanatory text carrying no claim that needs citing.",
+      "type": "object",
+      "required": ["type", "id", "body"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "prose" },
+        "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "body": { "$ref": "common.schema.json#/$defs/prose" }
+      }
+    },
+    "concept_section": {
+      "description": "A claim about the source. `evidence` is required and the evidence layer rejects it empty: a concept without evidence is an error, not a warning.",
+      "type": "object",
+      "required": ["type", "id", "title", "body", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "concept" },
+        "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "body": { "$ref": "common.schema.json#/$defs/prose" },
+        "evidence": { "$ref": "common.schema.json#/$defs/evidence" }
+      }
+    },
+    "code_section": {
+      "description": "A literal excerpt. `language` names the code's language for the reader; it selects no highlighter and no styling.",
+      "type": "object",
+      "required": ["type", "id", "language", "lines"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "code" },
+        "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "language": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9+#.-]{0,20}$"
+        },
+        "caption": { "type": "string", "minLength": 1, "maxLength": 1000 },
+        "first_line": {
+          "description": "The source line number the first emitted line had. Renders the gutter; changes nothing else.",
+          "type": "integer",
+          "minimum": 1
+        },
+        "lines": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 400,
+          "items": { "type": "string", "maxLength": 500 }
+        },
+        "evidence": { "$ref": "common.schema.json#/$defs/evidence" }
+      }
+    },
+    "flow_section": {
+      "description": "An ordered process. The first step is the entry; every other step must be reachable from it, and the graph must be acyclic.",
+      "type": "object",
+      "required": ["type", "id", "title", "steps"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "flow" },
+        "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 40,
+          "items": {
+            "type": "object",
+            "required": ["id", "title"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "$ref": "common.schema.json#/$defs/identifier" },
+              "title": { "type": "string", "minLength": 1, "maxLength": 200 },
+              "detail": { "type": "string", "minLength": 1, "maxLength": 2000 },
+              "next": {
+                "description": "Step ids this step leads to. Absent means the following step in the array, which is what a linear flow wants.",
+                "type": "array",
+                "maxItems": 10,
+                "items": { "$ref": "common.schema.json#/$defs/identifier" }
+              },
+              "evidence": { "$ref": "common.schema.json#/$defs/evidence" }
+            }
+          }
+        }
+      }
+    },
+    "quiz_section": {
+      "description": "Comprehension questions. Each answer is an index into that question's own options.",
+      "type": "object",
+      "required": ["type", "id", "questions"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "quiz" },
+        "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "questions": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 30,
+          "items": {
+            "type": "object",
+            "required": ["id", "prompt", "options", "answer"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "$ref": "common.schema.json#/$defs/identifier" },
+              "prompt": { "type": "string", "minLength": 1, "maxLength": 1000 },
+              "options": {
+                "type": "array",
+                "minItems": 2,
+                "maxItems": 8,
+                "uniqueItems": true,
+                "items": { "type": "string", "minLength": 1, "maxLength": 500 }
+              },
+              "answer": { "type": "integer", "minimum": 0 },
+              "explanation": { "type": "string", "minLength": 1, "maxLength": 2000 },
+              "evidence": { "$ref": "common.schema.json#/$defs/evidence" }
+            }
+          }
+        }
+      }
+    },
+    "exercise_section": {
+      "description": "Something for the reader to do. The renderer supplies the disclosure chrome around hints; the producer supplies their text.",
+      "type": "object",
+      "required": ["type", "id", "title", "body"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "exercise" },
+        "id": { "$ref": "common.schema.json#/$defs/identifier" },
+        "title": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "body": { "$ref": "common.schema.json#/$defs/prose" },
+        "hints": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 10,
+          "items": { "type": "string", "minLength": 1, "maxLength": 2000 }
+        },
+        "evidence": { "$ref": "common.schema.json#/$defs/evidence" }
+      }
+    }
+  }
+}