naive-framework 0.4.0 → 0.5.0

package/interface/cli/naive.mjs

@@ -17,6 +17,9 @@
 //   naive typegen                                   write .naive/types/ from the route table and the MCP tools
 //   naive upgrade [<venture dir>] [--framework]     move a venture onto the next Naive layout; --framework first
 //                                                   updates the installed framework with the venture's package manager (I-29)
+//   naive phase [<next phase>] [--meet <criterion> --evidence <text>] [--reason] [--override <why>]
+//                                                   the venture development lifecycle: where the venture is, its gate's exit
+//                                                   criteria, and moving to the next phase once a person has met them
 //   naive port <folder> --venture <dir> [--to <path>]  plan moving a folder into the venture as it is (codebase/<name>)
 //   naive port --venture <dir> --apply --confirm port
 //                                                   carry out that plan (EE-076)
@@ -178,6 +181,12 @@ else if (cmd === "build" || cmd === "start") {
   if (["list", "match", "check", "eval"].includes(sub)) process.exit(run("schema/frames.mjs", rest));
   const words = rest.filter((a, i) => a !== "--venture" && rest[i - 1] !== "--venture" && a !== "--frame" && rest[i - 1] !== "--frame" && a !== "--lookup" && rest[i - 1] !== "--lookup").join(" ");
   process.exit(run("schema/frames.mjs", ["run", here(), ...(opt("frame") ? [opt("frame")] : []), ...(words ? ["--text", words] : []), ...(opt("lookup") ? ["--lookup", opt("lookup")] : [])]));
+} else if (cmd === "phase") {
+  // The venture development lifecycle (schema/lifecycle.mjs): where the venture is, its gate, and moving on.
+  // naive phase | naive phase --meet <criterion> [--evidence <text>] | naive phase <next> [--reason] [--override]
+  const target = rest.find((a, i) => !a.startsWith("--") && !["--venture", "--meet", "--evidence", "--reason", "--override", "--by"].includes(rest[i - 1]));
+  const pass = ["evidence", "reason", "override", "by"].flatMap((k) => opt(k) !== undefined ? [`--${k}`, opt(k)] : []);
+  process.exit(run("schema/lifecycle.mjs", [here(), ...(opt("meet") ? ["meet", opt("meet")] : target ? ["advance", target] : []), ...pass, ...(rest.includes("--json") ? ["--json"] : [])]));
 } else if (cmd === "setup") {
   // Setup in the model's harness (EE-083): the state, the artifact, and the founder confirming relayed answers.
   process.exit(run("schema/setup.mjs", [here(), ...(rest.length ? rest.filter((a, i) => a !== "--venture" && rest[i - 1] !== "--venture") : ["state"])]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naive-framework",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Naive, a venture development framework: conventions, routes, records, checks and an agent interface for building a venture.",
   "type": "module",
   "license": "MIT",

package/schema/lifecycle.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// The venture development lifecycle (VDL): where a venture is, what its phase's gate asks, and whether
+// it may move on. Phases and gates are defined once in purpose/frameworks/product-anatomy/phases.json;
+// each venture states its own exit criteria per phase in its telos. A criterion is met when a person
+// says so, with evidence; a phase change is a person's decision, and the gate refuses it while the
+// current phase has unmet criteria, unless the person overrides it with a reason (logged).
+//
+//   node schema/lifecycle.mjs <venture dir>                                  where the venture is, as text (--json)
+//   node schema/lifecycle.mjs <venture dir> meet <criterion> [--evidence <text>] [--by <person>]
+//   node schema/lifecycle.mjs <venture dir> advance <phase> [--reason <text>] [--override <why>] [--by <person>]
+//
+// advance goes one phase forward; a step back (a venture can return to discovery) needs --reason, and
+// skipping a phase needs --override. The change itself, with its staleness, is schema/freshness.mjs's phase().
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { agentFromEnv, record } from "../interface/provenance.mjs";
+import { phase as changePhase } from "./freshness.mjs";
+import { ventureFile } from "./venture-paths.mjs";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const load = (f) => JSON.parse(readFileSync(f, "utf8"));
+export const PHASES = load(join(root, "purpose/frameworks/product-anatomy/phases.json")).phases.map(({ id, name, question, gate, binding_constraint }) => ({ id, name, question, gate, binding_constraint }));
+// Where a venture keeps its telos: foundation/ (setup writes it there) or the older purpose/.
+const TELOS = ["foundation/telos.json", "purpose/telos.json"];
+const telosFile = (dir) => TELOS.map((t) => ventureFile(dir, t)).find(existsSync) ?? null;
+
+/** Where the venture is in the lifecycle and what stands between it and the next phase. */
+export function lifecycle(dir) {
+  const v = load(join(dir, "venture.json"));
+  const i = PHASES.findIndex((p) => p.id === v.phase);
+  const tf = telosFile(dir);
+  const telos = tf ? load(tf) : null;
+  const criteria = (telos?.phases?.find((p) => p.phase === v.phase)?.exit_criteria ?? []).map((c) => ({ id: c.id, statement: c.statement, evidence: c.evidence ?? null, met: c.met ?? null }));
+  const unmet = criteria.filter((c) => !c.met).map((c) => c.id);
+  return {
+    venture: v.id, phase: v.phase, step: i + 1, of: PHASES.length,
+    current: PHASES[i] ?? null, next: PHASES[i + 1] ?? null,
+    telos: tf ? tf.slice(dir.length + 1) : null,
+    exit_criteria: criteria,
+    ready: criteria.length > 0 && unmet.length === 0,
+    blocking: !criteria.length ? [`no exit criteria for ${v.phase} in the telos: state what must be true to leave it`] : unmet.map((id) => `exit criterion ${id} is not met`),
+  };
+}
+
+/** A person marks one of the current phase's exit criteria met, with the evidence for it. */
+export function meet(dir, id, { evidence, by } = {}) {
+  const tf = telosFile(dir);
+  if (!tf) return { ok: false, error: "the venture has no telos yet, so no exit criteria to meet" };
+  const v = load(join(dir, "venture.json"));
+  const t = load(tf);
+  const c = t.phases?.find((p) => p.phase === v.phase)?.exit_criteria?.find((x) => x.id === id);
+  if (!c) return { ok: false, error: `${v.phase} has no exit criterion ${id}` };
+  const agent = by ?? agentFromEnv("person", "cli");
+  if (agent.kind !== "person") return { ok: false, error: "only a person can say an exit criterion is met; an agent can propose it" };
+  c.met = { at: new Date().toISOString(), by: agent.id ?? "person", ...(evidence ? { evidence } : {}) };
+  writeFileSync(tf, JSON.stringify(t, null, 2) + "\n");
+  record(dir, { entity: tf.slice(dir.length + 1), route: "foundation/telos", activity: "confirm", agent, note: `exit criterion ${v.phase}/${id} met${evidence ? `: ${evidence}` : ""}` });
+  return { ok: true, result: lifecycle(dir) };
+}
+
+/** A person moves the venture to another phase, through the gate. */
+export function advance(dir, to, { reason, override, by, now } = {}) {
+  const agent = by ?? agentFromEnv("person", "cli");
+  if (agent.kind !== "person") return { ok: false, error: "a phase change is a person's decision; an agent can suggest it, never make it" };
+  const l = lifecycle(dir);
+  const from = PHASES.findIndex((p) => p.id === l.phase), target = PHASES.findIndex((p) => p.id === to);
+  if (target < 0) return { ok: false, error: `${to} is not a phase (${PHASES.map((p) => p.id).join(", ")})` };
+  if (target === from) return { ok: false, error: `${l.venture} is already in ${to}` };
+  if (target < from && !reason) return { ok: false, error: `going back to ${to} needs --reason` };
+  if (target > from + 1 && !override) return { ok: false, error: `${to} skips ${PHASES.slice(from + 1, target).map((p) => p.id).join(", ")}; pass --override "<why>" to skip` };
+  if (target > from && !l.ready && !override) return { ok: false, error: `the ${l.current.gate} gate is not passed: ${l.blocking.join("; ")}. Meet them with naive phase --meet <id>, or pass --override "<why>"`, result: l };
+  const why = [reason, override && `gate overridden: ${override}`].filter(Boolean).join("; ");
+  const r = changePhase(dir, to, { reason: why || `${l.current.gate} passed`, by: agent, now });
+  if (r.ok) r.result.gate = { phase: l.phase, gate: l.current.gate, passed: l.ready, overridden: override ?? null };
+  return r;
+}
+
+const text = (l) => [
+  `${l.venture}: ${l.current?.name ?? l.phase} (phase ${l.step} of ${l.of})`,
+  l.current ? `  ${l.current.question}` : "",
+  l.current ? `  Gate: ${l.current.gate}` : "",
+  ...(l.exit_criteria.length ? l.exit_criteria.map((c) => `  ${c.met ? "✓" : "○"} ${c.id}: ${c.statement}${c.met ? `  (met ${c.met.at.slice(0, 10)} by ${c.met.by})` : ""}`) : [`  ○ ${l.blocking[0]}`]),
+  l.next ? `Next: ${l.next.name}, ${l.next.question}${l.ready ? "  Ready: naive phase " + l.next.id : ""}` : "This is the last phase.",
+].filter(Boolean).join("\n");
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const [dir, cmd, arg, ...rest] = process.argv.slice(2);
+  const all = process.argv.slice(2);
+  const opt = (k) => { const i = all.indexOf(`--${k}`); return i < 0 ? undefined : all[i + 1]; };
+  if (!dir || !existsSync(join(dir, "venture.json"))) { console.error("usage: node schema/lifecycle.mjs <venture dir> [meet <criterion> | advance <phase>]"); process.exit(2); }
+  const by = opt("by") ? agentFromEnv("person", "cli", { id: opt("by") }) : undefined;
+  const out = (r) => { if (!r.ok) { console.error(r.error); process.exit(1); } return r.result; };
+  if (!cmd || cmd.startsWith("--")) { const l = lifecycle(dir); console.log(all.includes("--json") ? JSON.stringify(l, null, 2) : text(l)); }
+  else if (cmd === "meet") console.log(text(out(meet(dir, arg, { evidence: opt("evidence"), by }))));
+  else if (cmd === "advance") { const r = out(advance(dir, arg, { reason: opt("reason"), override: opt("override"), by })); console.log(`${r.venture}: ${r.from} -> ${r.to}. ${r.note}`); }
+  else { console.error(`unknown command ${cmd}`); process.exit(2); }
+  void rest;
+}

package/schema/telos.schema.json

@@ -141,6 +141,29 @@
                 "evidence": {
                   "type": "string",
                   "description": "How it is shown: a check command, an evidence record, or a metric"
+                },
+                "met": {
+                  "type": "object",
+                  "required": [
+                    "at",
+                    "by"
+                  ],
+                  "additionalProperties": false,
+                  "description": "Set when a person says the criterion is met (naive phase --meet); the gate to the next phase passes when every criterion of the current phase has it",
+                  "properties": {
+                    "at": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "by": {
+                      "type": "string",
+                      "description": "The person who said it is met"
+                    },
+                    "evidence": {
+                      "type": "string",
+                      "description": "What shows it: a record, a metric, a check"
+                    }
+                  }
                 }
               }
             }