naive-framework 0.0.0-stage → 0.1.0

package/schema/reference.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "reference.schema.json",
+  "title": "References",
+  "description": "A layer's references (EE-014): the sources behind its opinionated defaults and the alternatives it considered. One file per layer at <layer>/references/references.json. A URL is recorded when one exists and re-checked; the find-reference skill fills gaps from title, authors and year.",
+  "type": "object",
+  "required": [
+    "layer",
+    "references"
+  ],
+  "properties": {
+    "layer": {
+      "enum": [
+        "purpose",
+        "knowledge",
+        "operations",
+        "evidence",
+        "governance",
+        "interface"
+      ]
+    },
+    "references": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "title",
+          "authors",
+          "year",
+          "kind",
+          "summary",
+          "informs",
+          "stance"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "title": {
+            "type": "string"
+          },
+          "authors": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "year": {
+            "type": "integer"
+          },
+          "kind": {
+            "enum": [
+              "book",
+              "article",
+              "paper",
+              "standard",
+              "law",
+              "dataset",
+              "conversation"
+            ]
+          },
+          "summary": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "checked": {
+            "type": "string",
+            "format": "date",
+            "description": "When the url last resolved"
+          },
+          "informs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^(noun|phase|gate|rule|field):[a-z0-9-_.]+$"
+            }
+          },
+          "stance": {
+            "type": "object",
+            "required": [
+              "is",
+              "why"
+            ],
+            "properties": {
+              "is": {
+                "enum": [
+                  "adopted",
+                  "adapted",
+                  "alternative",
+                  "rejected"
+                ]
+              },
+              "why": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "dependentRequired": {
+          "checked": [
+            "url"
+          ]
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schema/route-aliases.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "route-aliases.schema.json",
+  "title": "Route aliases",
+  "description": "Renamed routes (EE-032). Routes are an API that agents and scripts depend on, so a renamed record keeps its old route as an alias: the router follows it and answers with a deprecation note. Remove an alias only after the version it was deprecated in has been out for a release. interface/test.mjs checks that every alias points at a route that exists.",
+  "type": "object",
+  "required": ["aliases"],
+  "additionalProperties": false,
+  "properties": {
+    "aliases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "since"],
+        "additionalProperties": false,
+        "properties": {
+          "from": { "type": "string", "description": "The old route" },
+          "to": { "type": "string", "description": "The route it became" },
+          "since": { "type": "string", "format": "date" },
+          "note": { "type": "string", "description": "Why it moved, cited by decision id" }
+        }
+      }
+    }
+  }
+}

package/schema/run-handoff.mjs

@@ -0,0 +1,51 @@
+// Runs a handoff's done-criteria and writes the result as evidence (EE-017).
+//
+//   node schema/run-handoff.mjs <venture dir> <handoff id> [--runner <session or job id>]
+//
+// Each conformance and self-proof criterion's `check` is run as a shell command from the
+// repository root; exit code 0 passes. A review criterion is recorded only when its reviewer
+// gives a verdict: --review <criterion>=pass|fail --by <role> --note "<what was judged>". The
+// result goes to <venture>/evidence/results/<handoff>-<timestamp>.json and is appended to
+// the handoff's `evidence`; nothing else in the handoff changes, so its status stays the
+// holder's call (and check-execution.mjs holds them to it).
+
+import { execSync, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const [dir, id] = process.argv.slice(2);
+if (!dir || !id) { console.error("usage: node schema/run-handoff.mjs <venture dir> <handoff id> [--runner <id>]"); process.exit(2); }
+const opt = (k) => process.argv.includes(k) ? process.argv[process.argv.indexOf(k) + 1] : undefined;
+const runner = opt("--runner") ?? "local";
+const [reviewId, verdict] = (opt("--review") ?? "").split("=");
+const root = new URL("..", import.meta.url).pathname;
+const hPath = join(dir, "operations/handoffs", `${id}.json`);
+const h = JSON.parse(readFileSync(hPath, "utf8"));
+const dirty = execSync("git status --porcelain", { cwd: root, encoding: "utf8" }).trim() ? "+uncommitted" : "";
+const version = execSync("git rev-parse --short HEAD", { cwd: root, encoding: "utf8" }).trim() + dirty;
+const trim = (s) => s.trim().split("\n").slice(-12).join("\n");
+
+const results = [];
+for (const c of h.done_criteria.filter((d) => d.kind === "review" && d.id === reviewId)) {
+  if (!["pass", "fail"].includes(verdict) || !opt("--by") || !opt("--note")) { console.error("a review needs --review <id>=pass|fail, --by <role> and --note"); process.exit(2); }
+  results.push({ criterion: c.id, kind: "review", passed: verdict === "pass", by: opt("--by"), command: c.check, output: opt("--note") });
+  console.log(`${verdict === "pass" ? "pass" : "FAIL"} ${c.id} (review by ${opt("--by")})`);
+}
+for (const c of h.done_criteria.filter((d) => d.kind !== "review")) {
+  const run = spawnSync("/bin/bash", ["-c", c.check], { cwd: root, encoding: "utf8" });
+  const passed = run.status === 0, output = `${run.stdout}${run.stderr}`;
+  results.push({ criterion: c.id, kind: c.kind, passed, command: c.check, output: trim(output) });
+  console.log(`${passed ? "pass" : "FAIL"} ${c.id}`);
+}
+
+const at = new Date().toISOString().replace(/\.\d+Z$/, "Z");
+const eid = `${h.id}-${at.replace(/[-:TZ]/g, "").slice(0, 14)}`;
+const ev = { id: eid, subject: { kind: "handoff", id: h.id, version }, ran_at: at, runner, results, passed: results.every((r) => r.passed) };
+mkdirSync(join(dir, "evidence/results"), { recursive: true });
+const ePath = join(dir, "evidence/results", `${eid}.json`);
+writeFileSync(ePath, JSON.stringify(ev, null, 2) + "\n");
+h.evidence = [...(h.evidence ?? []), relative(join(dir, "operations/handoffs"), ePath)];
+writeFileSync(hPath, JSON.stringify(h, null, 2) + "\n");
+const pending = h.done_criteria.filter((d) => d.kind === "review" && d.id !== reviewId).map((d) => `${d.id} (${d.reviewer})`);
+console.log(`${ev.passed ? "every criterion run passed" : "some criteria failed"}${pending.length ? `; review still owed: ${pending.join(", ")}` : ""}: ${relative(process.cwd(), ePath)}`);
+process.exit(ev.passed ? 0 : 1);

package/schema/scaffold/defaults.json

@@ -0,0 +1,54 @@
+{
+  "version": "0.3.0",
+  "note": "Which layers a new venture starts with, by phase (EE-012). Every venture has every layer; a layer not listed starts as false and is switched on when the venture needs it. Folder names are the layer names. Every venture also gets the three pillars, as short stubs that point to the full guides, and a venture profile (EE-010, EE-011). Governance is added when the venture is formalized: a legal form other than none, or other members.",
+  "layers": {
+    "discovery": [
+      "knowledge"
+    ],
+    "validation": [
+      "purpose",
+      "knowledge",
+      "operations",
+      "evidence"
+    ],
+    "beachhead": [
+      "purpose",
+      "knowledge",
+      "operations",
+      "evidence"
+    ],
+    "scale": [
+      "purpose",
+      "knowledge",
+      "operations",
+      "evidence",
+      "interface"
+    ],
+    "platform": [
+      "purpose",
+      "knowledge",
+      "operations",
+      "evidence",
+      "interface"
+    ]
+  },
+  "formalized": [
+    "governance"
+  ],
+  "pillars": {
+    "guides": "governance/venture-template/pillars/",
+    "stubs": {
+      "product": "What the venture makes: its core product (in venture.json), its products (in products/), and what each needs to be specified, built, shipped and operated.",
+      "brand": "How the venture is known: its name, voice, promise wording and visual identity.",
+      "business": "How the venture sustains itself: business models, pricing, costs, legal form and funding."
+    }
+  },
+  "readme": {
+    "purpose": "Why this venture exists: its core product, products and the Product Anatomy matrix.",
+    "knowledge": "Memory: every record the venture keeps, including notes, specs, decisions and references.",
+    "operations": "How work is run here: the MAD record (.mad/) and chosen methods, and handoffs of work to people and agents.",
+    "evidence": "Did it work: reviews, evals and metrics.",
+    "governance": "Who may decide what: roles and decision rights.",
+    "interface": "How people and agents see this venture: consoles and dashboards."
+  }
+}

package/schema/site-presence.schema.json

@@ -0,0 +1,337 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "site-presence.schema.json",
+  "title": "Site presence",
+  "description": "How present a venture's public records are on its marketing site, weighed by who the site must speak to now (EE-062, EE-063). Written by operations/marketing/site/presence.mjs from a read of the site; version 0.x, ours and unevaluated.",
+  "type": "object",
+  "required": [
+    "version",
+    "site",
+    "judged_by",
+    "facts",
+    "score",
+    "audiences",
+    "pages",
+    "items",
+    "fix_first",
+    "icp",
+    "sitemap"
+  ],
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "site": {
+      "type": "string"
+    },
+    "venture": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "read_via": {
+      "enum": [
+        "firecrawl",
+        "fetch"
+      ]
+    },
+    "read_at": {
+      "type": "string"
+    },
+    "judged_by": {
+      "enum": [
+        "jev",
+        "keywords"
+      ]
+    },
+    "facts": {
+      "type": "object"
+    },
+    "score": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100
+    },
+    "audiences": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "weight"
+        ],
+        "properties": {
+          "weight": {
+            "type": "number"
+          },
+          "score": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          }
+        }
+      }
+    },
+    "pages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "path",
+          "type",
+          "level"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "level": {
+            "enum": [
+              "home",
+              "nav",
+              "linked",
+              "anywhere"
+            ]
+          }
+        }
+      }
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "label",
+          "record",
+          "need",
+          "required",
+          "score",
+          "note"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "record": {
+            "type": "string"
+          },
+          "need": {
+            "type": "number"
+          },
+          "required": {
+            "enum": [
+              "home",
+              "nav",
+              "linked",
+              "anywhere"
+            ]
+          },
+          "for": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "at": {
+            "enum": [
+              "home",
+              "nav",
+              "linked",
+              "anywhere",
+              null
+            ]
+          },
+          "score": {
+            "enum": [
+              0,
+              0.5,
+              1
+            ]
+          },
+          "found": {
+            "type": "array"
+          },
+          "note": {
+            "type": "string"
+          },
+          "evidence": {
+            "type": "array",
+            "description": "Who needs the item and why: each audience's weight, the item's importance to it, and the reason (for customers, from the customer types)",
+            "items": {
+              "type": "object",
+              "required": [
+                "audience",
+                "need",
+                "why",
+                "source"
+              ],
+              "properties": {
+                "audience": {
+                  "type": "string"
+                },
+                "weight": {
+                  "type": "number"
+                },
+                "importance": {
+                  "type": "number"
+                },
+                "need": {
+                  "type": "number"
+                },
+                "why": {
+                  "type": "string"
+                },
+                "source": {
+                  "enum": [
+                    "customer types",
+                    "matrix"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "fix_first": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "icp": {
+      "type": "object",
+      "required": [
+        "text",
+        "source",
+        "cite",
+        "types"
+      ],
+      "description": "Who the site is for and where that comes from: the founder's words, the venture's ICP record, or inferred from the home page; and the customer types Jev placed it in",
+      "properties": {
+        "text": {
+          "type": "string"
+        },
+        "source": {
+          "enum": [
+            "founder",
+            "record",
+            "inferred"
+          ]
+        },
+        "cite": {
+          "type": "string"
+        },
+        "types": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "label"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "label": {
+                "type": "string"
+              },
+              "p": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "sitemap": {
+      "type": "array",
+      "description": "The site's routes as a tree from the home page, each rated on the items that belong there; ghost routes are pages the venture's priorities call for that the site lacks",
+      "items": {
+        "type": "object",
+        "required": [
+          "path",
+          "parent",
+          "label",
+          "type",
+          "level",
+          "read",
+          "rating",
+          "expected",
+          "found",
+          "missing"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "parent": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "label": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          },
+          "level": {
+            "enum": [
+              "home",
+              "nav",
+              "linked",
+              "anywhere"
+            ]
+          },
+          "read": {
+            "type": "boolean"
+          },
+          "rating": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "expected": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "found": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "missing": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "ghost": {
+            "type": "boolean"
+          }
+        }
+      }
+    }
+  }
+}

package/schema/strategic-foundation.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "strategic-foundation.schema.json",
+  "title": "Strategic foundation frame",
+  "description": "The framework's map of strategic foundation (EE-051): per question of the Five Ws and How plus whether, the record attributes that answer it.",
+  "type": "object",
+  "required": [
+    "version",
+    "questions"
+  ],
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "note": {
+      "type": "string"
+    },
+    "questions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "ask",
+          "statements"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "ask": {
+            "type": "string"
+          },
+          "statements": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "record",
+                "attribute"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9-]+$"
+                },
+                "record": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "attribute": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "derived_from": {
+                  "type": "string",
+                  "description": "The id of another statement this one is derived from; it takes that statement's status and value"
+                },
+                "note": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schema/stream.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "stream.schema.json",
+  "title": "Data stream",
+  "description": "Declares one append-only stream under a data package's _streams/<id>/ (EE-070). sensitive true means the stream's events stay out of git and only summary.md is versioned.",
+  "type": "object",
+  "required": ["id", "sensitive"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "sensitive": { "type": "boolean" },
+    "summary": { "type": "string", "description": "What the versioned summary.md covers, when sensitive is true" }
+  }
+}