pi-gnosis 0.1.0

package/pi.json

@@ -0,0 +1,42 @@
+{
+  "name": "pi-gnosis",
+  "package": "pi-gnosis",
+  "version": "0.2.0",
+  "kind": "pi-package",
+  "description": "Circuitry-first Pi package that turns research and tutoring plans into executable Circuitry graph programs.",
+  "dependsOn": {
+    "pi-circuitry": "github:darkhorseprojects/pi-circuitry#v0.2.6",
+    "circuitry": "transitive through pi-circuitry",
+    "pi-web-access": "npm:pi-web-access@^0.10.7",
+    "pi-exa-search": "optional github:najibninaba/pi-exa-search#main"
+  },
+  "runtimeDefaults": {
+    "provider": "pi",
+    "model": "inherit"
+  },
+  "entrypoints": {
+    "skill": "skills/pi-gnosis/SKILL.md",
+    "manimSkill": "skills/manim-video/SKILL.md",
+    "config": "config/gnosis.config.json",
+    "graphs": {
+      "research": "graphs/research.circuitry.yaml",
+      "tutoringSession": "graphs/tutoring-session.circuitry.yaml",
+      "noteExport": "graphs/note-export.circuitry.yaml",
+      "manimLecture": "graphs/manim-lecture.circuitry.yaml",
+      "cleanup": "graphs/cleanup.circuitry.yaml",
+      "smoke": "graphs/minimal-smoke.circuitry.yaml"
+    },
+    "cli": "bin/pi-gnosis.js"
+  },
+  "capabilities": [
+    "circuitry-graph-programs",
+    "source-grounded-research",
+    "web-search-via-pi-web-access",
+    "optional-exa-source-discovery",
+    "open-ended-diagnostic-probing",
+    "knowledge-tracing-dag-state",
+    "obsidian-compatible-note-export",
+    "manim-lecture-generation",
+    "safe-cleanup-planning"
+  ]
+}

package/scripts/check-circuitry-v02.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Structural checker for Pi-GNOSIS Circuitry v0.2 graph programs.
+
+This is not a replacement for the official pi-circuitry/circuitry validator. It is a
+local smoke verifier used in offline packaging to catch schema drift, legacy graph
+shapes, missing model inheritance, unsafe wiring, and the prior architecture mistake
+of treating Circuitry itself as a single generic orchestration node.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+LEGACY_TOP_LEVEL = {"agents", "inputs", "edges"}
+EXECUTABLE_TYPES = {"agent", "tool"}
+BANNED_IDENTITIES = {"Generic Simulation Node", "Simulation Orchestrator"}
+WEB_TOOLS = {"web_search", "fetch_content", "exa_search"}
+
+
+def fail(path: Path, message: str) -> str:
+    return f"{path}: {message}"
+
+
+def as_list(value: Any) -> list[Any]:
+    return value if isinstance(value, list) else []
+
+
+def validate_graph(path: Path) -> list[str]:
+    issues: list[str] = []
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except Exception as exc:  # pragma: no cover - defensive
+        return [fail(path, f"cannot parse yaml: {exc}")]
+
+    if not isinstance(data, dict):
+        return [fail(path, "graph must be a mapping")]
+
+    if str(data.get("circuitry")) != "0.2":
+        issues.append(fail(path, "must declare circuitry: \"0.2\""))
+
+    runtime = data.get("runtime") or {}
+    if not isinstance(runtime, dict):
+        issues.append(fail(path, "runtime must be a mapping"))
+    else:
+        if runtime.get("provider") != "pi":
+            issues.append(fail(path, "runtime.provider must be pi"))
+        if runtime.get("model") != "inherit":
+            issues.append(fail(path, "runtime.model must be inherit"))
+
+    for key in LEGACY_TOP_LEVEL:
+        if key in data:
+            issues.append(fail(path, f"must not mix v0.2 resources with legacy top-level {key}"))
+
+    resources = data.get("resources")
+    if not isinstance(resources, dict) or not resources:
+        issues.append(fail(path, "resources must be a non-empty map"))
+        return issues
+
+    ids = set(resources)
+    agent_count = 0
+    web_tool_seen = False
+
+    for rid, entry in resources.items():
+        if not isinstance(entry, dict):
+            issues.append(fail(path, f"resource {rid} must be a map"))
+            continue
+        rtype = entry.get("type")
+        if rtype not in {"text", "agent", "tool"}:
+            issues.append(fail(path, f"resource {rid} has invalid type {rtype!r}"))
+        inputs = as_list(entry.get("inputs"))
+        if rid in inputs:
+            issues.append(fail(path, f"resource {rid} has a self-loop"))
+        for target in inputs:
+            if target not in ids:
+                issues.append(fail(path, f"resource {rid} references unknown input {target!r}"))
+        if rtype in EXECUTABLE_TYPES and not inputs:
+            issues.append(fail(path, f"executable resource {rid} must have inputs"))
+        if rtype == "agent":
+            agent_count += 1
+            identity = entry.get("identity")
+            if not identity:
+                issues.append(fail(path, f"agent {rid} must have identity"))
+            if identity in BANNED_IDENTITIES:
+                issues.append(fail(path, f"agent {rid} uses banned identity {identity}"))
+            if entry.get("model") != "inherit":
+                issues.append(fail(path, f"agent {rid} must use model: inherit"))
+            if not entry.get("instructions"):
+                issues.append(fail(path, f"agent {rid} must have instructions"))
+            if not isinstance(entry.get("expect"), dict):
+                issues.append(fail(path, f"agent {rid} must declare expect schema"))
+            if WEB_TOOLS.intersection(set(as_list(entry.get("tools")))):
+                web_tool_seen = True
+
+    # Cycle check through DFS.
+    graph = {rid: as_list(entry.get("inputs")) if isinstance(entry, dict) else [] for rid, entry in resources.items()}
+    visiting: set[str] = set()
+    visited: set[str] = set()
+
+    def dfs(node: str, stack: list[str]) -> None:
+        if node in visiting:
+            issues.append(fail(path, "cycle detected: " + " -> ".join(stack + [node])))
+            return
+        if node in visited:
+            return
+        visiting.add(node)
+        for dep in graph.get(node, []):
+            if dep in graph:
+                dfs(dep, stack + [node])
+        visiting.remove(node)
+        visited.add(node)
+
+    for rid in resources:
+        dfs(rid, [])
+
+    if "research" in path.name and not web_tool_seen:
+        issues.append(fail(path, "research graph must include at least one agent with pi-web-access/pi-exa-search tools"))
+
+    if agent_count == 0:
+        issues.append(fail(path, "graph must include at least one agent"))
+
+    return issues
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 2:
+        print("usage: check-circuitry-v02.py <graph...>", file=sys.stderr)
+        return 2
+    paths: list[Path] = []
+    for arg in argv[1:]:
+        matched = list(Path().glob(arg)) if any(ch in arg for ch in "*?[") else [Path(arg)]
+        paths.extend(matched)
+    issues: list[str] = []
+    for path in paths:
+        issues.extend(validate_graph(path))
+    if issues:
+        print("Circuitry graph validation failed:", file=sys.stderr)
+        for issue in issues:
+            print("- " + issue, file=sys.stderr)
+        return 1
+    print(f"Validated {len(paths)} Circuitry v0.2 graph(s).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/skills/manim-video/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: manim-video
+description: Local Manim CE lecture/video generation skill for Pi-GNOSIS. Use when a Circuitry graph or Pi user requests animated explanations, mathematical or technical visualizations, algorithm walkthroughs, architecture diagrams, paper explainers, or a 3Blue1Brown-style lecture output. Inspired by the public Nous/Hermes Manim Video skill docs; not an official dependency.
+model: inherit
+---
+
+# Manim Video Production
+
+Credit: this local skill is inspired by Nous Research / Hermes Agent's public Manim Video documentation. It is rewritten for Pi-GNOSIS and bundled locally because there is no official Pi dependency to require.
+
+## Use
+
+Use Manim Community Edition to create educational videos and animated lectures. Plan before coding. The output should teach a concept visually, not merely animate text.
+
+## Required project structure
+
+```text
+<project>/
+  plan.md
+  scene_spec.json
+  script.py
+  render.sh
+  README.md
+  media/              # generated by Manim, disposable unless final clips are needed
+```
+
+## Pipeline
+
+1. Plan the narrative: misconception, prerequisite, visual metaphor, aha moment, scene list.
+2. Write `scene_spec.json` with scene names, objective, visual elements, narration beats, and estimated duration.
+3. Write one `script.py` with one Manim Scene class per scene.
+4. Run preflight before render: Python syntax, `manim --version`, `ffmpeg -version`, LaTeX availability if MathTex is used.
+5. Render draft with low quality first.
+6. Review stills/clips against the learning objective.
+7. Keep final video and source script; mark intermediate media for cleanup.
+
+## Quality rules
+
+- Every scene must have one visual objective.
+- Do not dump paragraphs onto the canvas.
+- Prefer spatial structure, transformations, highlighting, and progressive reveal.
+- Use consistent typography and timing.
+- Pause after important reveals.
+- Avoid decorative animation that does not teach.
+- For research topics, include uncertainty and source ids in the narration plan when needed.
+
+## Safety and side effects
+
+Write only inside the requested Manim output root. Do not delete source scripts, final videos, note exports, or DAG state. Media cache cleanup belongs to the cleanup graph.

package/skills/pi-gnosis/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: pi-gnosis
+description: Source-grounded, non-linear research tutoring for Pi. Use when the user wants to learn, research, build understanding, make notes, get a lecture/video, resume a topic, audit prior knowledge, generate open-ended probes, or maintain an Obsidian learning vault. This skill routes work into Circuitry graph programs through pi-circuitry instead of making the main Pi agent do everything directly.
+model: inherit
+---
+
+# Pi-GNOSIS
+
+You are the coordinator, not the whole pipeline. Use this skill to decide when to launch Pi-GNOSIS Circuitry graph programs and how to interpret their outputs.
+
+## Core rule
+
+Circuitry is the agentic programming layer. The graphs are the multi-agent simulations/conversations/workflows. Do not create a generic "simulation node". Run the appropriate graph program.
+
+## Graph selection
+
+- Need fresh research or source grounding: run `graphs/research.circuitry.yaml`.
+- Need one tutoring turn, diagnosis, feedback, or next step: run `graphs/tutoring-session.circuitry.yaml`.
+- Need Obsidian notes or vault update: run `graphs/note-export.circuitry.yaml`.
+- Need video/lecture/visual explanation: run `graphs/manim-lecture.circuitry.yaml` and let its Manim agent load `manim-video`.
+- Need to clean temp artifacts after a run: run `graphs/cleanup.circuitry.yaml`.
+- Need a quick dependency smoke check: run `graphs/minimal-smoke.circuitry.yaml`.
+
+## Conversation behavior
+
+The learner can quit, resume, jump topics, or change modality at any point. Do not force a fixed curriculum. Maintain enough state for continuation, then let Pi talk normally.
+
+Ask at most one useful preference question before starting, unless the user already specified enough. Good question: "Do you want text notes, Obsidian notes, a Manim video/lecture, or just a short explanation first?"
+
+Move on when the learner demonstrates understanding through open-ended evidence, not because a script says the section is done.
+
+## Probes
+
+Never use multiple-choice diagnostic questions. Use recall, explain, transfer, contrast, debug, teach-back, worked example, predict-observe-explain, or source-check probes.
+
+## State separation
+
+DAG state is canonical runtime memory. Obsidian is the learner's study surface.
+
+- Save source ledgers, claim ledgers, KT DAG, learner state, probe results, review schedules, and manifests under `.pi-gnosis/state/<run-id>/`.
+- Save learner-readable notes under the configured Obsidian-compatible notes path.
+- Treat Obsidian notes as evidence of learner understanding, not as source truth unless imported and validated.
+
+## Web research
+
+For research graph nodes, prefer the package tools from `pi-web-access`: `web_search` and `fetch_content`. If `pi-exa-search` is installed, use `exa_search` first for source discovery and follow with `fetch_content` for selected URLs.
+
+## Writes and cleanup
+
+Before any non-read-only work, require the graph agent to state the target root and output manifest. After non-read-only runs, run or offer the cleanup graph. Cleanup is plan-first and may delete only safe temporary files unless the user explicitly authorizes more.
+
+## Manim
+
+For video output, run the Manim graph. The relevant agent must include `skills: [pi-gnosis, manim-video]`, so it can read the bundled Manim skill. Generate projects under the configured Manim root. Rendering requires local Manim CE, LaTeX, and ffmpeg; if unavailable, return a runnable project and clear preflight report.

package/src/cleanup-policy.js

@@ -0,0 +1,43 @@
+import { relative, normalize } from 'node:path';
+
+const PROTECTED_PATTERNS = [
+  /^\.pi-gnosis\/state\//,
+  /^notes\//,
+  /source_ledger\.json$/,
+  /claim_ledger\.json$/,
+  /kt_dag\.json$/,
+  /learner_state\.json$/,
+  /final\.(mp4|mov|webm)$/,
+  /script\.py$/,
+  /package\.json$/,
+  /pi\.json$/,
+  /^config\//,
+  /^skills\//,
+  /^graphs\//,
+];
+
+function cleanPath(p) {
+  return normalize(String(p || '')).replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+export function classifyArtifact(path, options = {}) {
+  const p = cleanPath(path);
+  const tempRoot = cleanPath(options.tempRoot || '.pi-gnosis/tmp');
+  const manimRoot = cleanPath(options.manimRoot || 'manim');
+  if (!p || p.includes('..')) return { path: p, category: 'unknown', protected: true, reason: 'empty or parent traversal' };
+  if (PROTECTED_PATTERNS.some((re) => re.test(p))) return { path: p, category: 'protected', protected: true, reason: 'protected artifact type' };
+  if (p === tempRoot || p.startsWith(`${tempRoot}/`)) return { path: p, category: 'temporary', protected: false, reason: 'inside configured temporary root' };
+  if (p.startsWith(`${manimRoot}/`) && p.includes('/media/')) return { path: p, category: 'generated-media', protected: false, reason: 'Manim media cache' };
+  return { path: p, category: 'unknown', protected: true, reason: 'not in a safe cleanup root' };
+}
+
+export function planCleanup(paths, options = {}) {
+  if (!Array.isArray(paths)) throw new TypeError('paths must be an array');
+  const apply = Boolean(options.applyCleanup);
+  const allowMedia = Boolean(options.allowGeneratedMediaCleanup);
+  return paths.map((path) => {
+    const c = classifyArtifact(path, options);
+    const allowedNow = !c.protected && apply && (c.category === 'temporary' || (c.category === 'generated-media' && allowMedia));
+    return { ...c, allowed_now: allowedNow };
+  });
+}

package/src/config.js

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..');
+const CONFIG_PATH = resolve(PACKAGE_ROOT, 'config/gnosis.config.json');
+
+export function loadConfig(path = CONFIG_PATH) {
+  const raw = readFileSync(path, 'utf8');
+  const config = JSON.parse(raw);
+  if (config?.runtime?.provider !== 'pi') {
+    throw new Error('Pi-GNOSIS config must use runtime.provider = pi');
+  }
+  if (config?.runtime?.model !== 'inherit') {
+    throw new Error('Pi-GNOSIS config must default runtime.model = inherit');
+  }
+  return config;
+}
+
+export function packageRoot() {
+  return PACKAGE_ROOT;
+}
+
+export function graphPath(name) {
+  const names = {
+    research: 'graphs/research.circuitry.yaml',
+    tutoring: 'graphs/tutoring-session.circuitry.yaml',
+    'tutoring-session': 'graphs/tutoring-session.circuitry.yaml',
+    notes: 'graphs/note-export.circuitry.yaml',
+    'note-export': 'graphs/note-export.circuitry.yaml',
+    manim: 'graphs/manim-lecture.circuitry.yaml',
+    'manim-lecture': 'graphs/manim-lecture.circuitry.yaml',
+    cleanup: 'graphs/cleanup.circuitry.yaml',
+    smoke: 'graphs/minimal-smoke.circuitry.yaml',
+  };
+  const rel = names[name];
+  if (!rel) throw new Error(`Unknown graph name: ${name}`);
+  return resolve(PACKAGE_ROOT, rel);
+}

package/src/graph-template.js

@@ -0,0 +1,10 @@
+import { readFileSync } from 'node:fs';
+import { graphPath } from './config.js';
+
+export function getGraphProgram(name) {
+  return readFileSync(graphPath(name), 'utf8');
+}
+
+export function listGraphPrograms() {
+  return ['research', 'tutoring-session', 'note-export', 'manim-lecture', 'cleanup', 'smoke'];
+}

package/src/graph-validator.js

@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs';
+
+const LEGACY_TOP_LEVEL = ['agents:', 'edges:'];
+const BANNED_IDENTITIES = ['Generic Simulation Node', 'Simulation Orchestrator'];
+
+export function validateCircuitryText(text, filename = '<graph>') {
+  const issues = [];
+  if (!text.includes('circuitry: "0.2"') && !text.includes("circuitry: '0.2'") && !text.includes('circuitry: 0.2')) {
+    issues.push(`${filename}: missing circuitry: "0.2"`);
+  }
+  if (!/runtime:\s*\n\s*provider:\s*pi\s*\n\s*model:\s*inherit/m.test(text)) {
+    issues.push(`${filename}: runtime must be provider pi and model inherit`);
+  }
+  if (!/resources:\s*\n/.test(text)) {
+    issues.push(`${filename}: missing resources map`);
+  }
+  for (const key of LEGACY_TOP_LEVEL) {
+    const re = new RegExp(`^${key}`, 'm');
+    if (re.test(text)) issues.push(`${filename}: must not use legacy top-level ${key}`);
+  }
+  for (const phrase of BANNED_IDENTITIES) {
+    if (text.includes(phrase)) issues.push(`${filename}: contains banned fake simulation node identity`);
+  }
+  const agentCount = (text.match(/type:\s*agent/g) || []).length;
+  const inheritCount = (text.match(/model:\s*inherit/g) || []).length;
+  if (agentCount > 0 && inheritCount < agentCount + 1) {
+    issues.push(`${filename}: every agent plus runtime must use model: inherit`);
+  }
+  return { ok: issues.length === 0, issues };
+}
+
+export function validateCircuitryFile(path) {
+  return validateCircuitryText(readFileSync(path, 'utf8'), path);
+}
+
+export function assertValidCircuitryText(text, filename = '<graph>') {
+  const result = validateCircuitryText(text, filename);
+  if (!result.ok) throw new Error(result.issues.join('\n'));
+  return true;
+}

package/src/index.js

@@ -0,0 +1,8 @@
+export { loadConfig, packageRoot, graphPath } from './config.js';
+export { getGraphProgram, listGraphPrograms } from './graph-template.js';
+export { validateCircuitryFile, validateCircuitryText, assertValidCircuitryText } from './graph-validator.js';
+export { buildReviewSchedule, intervalDaysForConcept } from './review-scheduler.js';
+export { storagePlan } from './storage-contract.js';
+export { assertAllowedProbe, isForbiddenProbe, recommendedProbeTypes } from './probe-policy.js';
+export { classifyArtifact, planCleanup } from './cleanup-policy.js';
+export { buildManimProject } from './manim-project.js';

package/src/manim-project.js

@@ -0,0 +1,44 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function slugify(s) {
+  return String(s || 'lecture').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'lecture';
+}
+
+export function buildManimProject({ topic = 'knowledge tracing DAGs', outputRoot = 'manim', write = false } = {}) {
+  const slug = slugify(topic);
+  const projectRoot = resolve(outputRoot, slug);
+  const sceneSpec = {
+    topic,
+    scenes: [
+      {
+        className: 'OpeningMap',
+        learningGoal: 'Show that Pi-GNOSIS separates conversation, Circuitry programs, DAG state, and notes.',
+        visualMetaphor: 'Four labeled boxes connected by arrows',
+        durationSeconds: 25,
+      },
+      {
+        className: 'KTDagScene',
+        learningGoal: 'Show why learner state is a graph rather than a checklist.',
+        visualMetaphor: 'Concept nodes with prerequisite and misconception edges',
+        durationSeconds: 35,
+      },
+    ],
+  };
+  const plan = `# ${topic}\n\nNarrative arc: start with one Pi conversation, reveal delegated Circuitry graph programs, then show how evidence updates a KT DAG while Obsidian stays human-readable.\n\nAha moment: the graph is not just notes; it is executable state for tutoring decisions.\n`;
+  const script = `from manim import *\n\n\nclass OpeningMap(Scene):\n    def construct(self):\n        title = Text(\"Pi-GNOSIS\", font_size=42)\n        subtitle = Text(\"conversation -> Circuitry -> state -> notes\", font_size=28).next_to(title, DOWN)\n        self.play(Write(title))\n        self.play(FadeIn(subtitle))\n        self.wait(1)\n\n\nclass KTDagScene(Scene):\n    def construct(self):\n        nodes = VGroup(*[Circle(radius=0.35).shift(RIGHT * (i - 1) * 2) for i in range(3)])\n        labels = VGroup(Text(\"A\", font_size=24).move_to(nodes[0]), Text(\"B\", font_size=24).move_to(nodes[1]), Text(\"C\", font_size=24).move_to(nodes[2]))\n        arrows = VGroup(Arrow(nodes[0].get_right(), nodes[1].get_left(), buff=0.1), Arrow(nodes[1].get_right(), nodes[2].get_left(), buff=0.1))\n        caption = Text(\"open-ended evidence updates the DAG\", font_size=28).next_to(nodes, DOWN)\n        self.play(Create(nodes), Write(labels))\n        self.play(Create(arrows))\n        self.play(FadeIn(caption))\n        self.wait(1)\n`;
+  const render = '#!/usr/bin/env bash\nset -euo pipefail\nmanim -ql script.py OpeningMap KTDagScene\n';
+  const readme = `# ${topic}\n\nGenerated by Pi-GNOSIS. Run \`./render.sh\` after installing Manim CE, ffmpeg, and LaTeX if needed.\n`;
+  const files = {
+    'plan.md': plan,
+    'scene_spec.json': JSON.stringify(sceneSpec, null, 2) + '\n',
+    'script.py': script,
+    'render.sh': render,
+    'README.md': readme,
+  };
+  if (write) {
+    mkdirSync(projectRoot, { recursive: true });
+    for (const [name, content] of Object.entries(files)) writeFileSync(resolve(projectRoot, name), content, 'utf8');
+  }
+  return { projectRoot, files };
+}

package/src/probe-policy.js

@@ -0,0 +1,22 @@
+const FORBIDDEN_RECOGNITION_PATTERNS = [
+  /multiple\s*choice/i,
+  /select\s+one/i,
+  /choose\s+the\s+correct/i,
+  /which\s+of\s+the\s+following/i,
+  /\bA\)\s+.*\bB\)/s,
+];
+
+export function isForbiddenProbe(prompt) {
+  return FORBIDDEN_RECOGNITION_PATTERNS.some((re) => re.test(String(prompt || '')));
+}
+
+export function assertAllowedProbe(prompt) {
+  if (isForbiddenProbe(prompt)) {
+    throw new Error('Recognition-only diagnostic probe is forbidden by Pi-GNOSIS policy');
+  }
+  return true;
+}
+
+export function recommendedProbeTypes() {
+  return ['recall', 'explain', 'transfer', 'contrast', 'debug', 'teach_back', 'worked_example', 'predict_observe_explain', 'source_check'];
+}

package/src/review-scheduler.js

@@ -0,0 +1,54 @@
+const BASE_INTERVAL_BY_DECAY_RISK = new Map([
+  [5, 2],
+  [4, 3],
+  [3, 5],
+  [2, 10],
+  [1, 20],
+  [0, 30],
+]);
+
+function toDateOnly(dateLike) {
+  const d = dateLike ? new Date(dateLike) : new Date();
+  if (Number.isNaN(d.getTime())) throw new Error(`Invalid date: ${dateLike}`);
+  return d;
+}
+
+function addDays(date, days) {
+  const d = new Date(date.getTime());
+  d.setUTCDate(d.getUTCDate() + days);
+  return d.toISOString().slice(0, 10);
+}
+
+function clampRisk(n) {
+  const v = Number(n ?? 0);
+  if (!Number.isFinite(v)) return 0;
+  return Math.max(0, Math.min(5, Math.round(v)));
+}
+
+export function intervalDaysForConcept(concept) {
+  const decay = clampRisk(concept.decay_risk);
+  const misconception = clampRisk(concept.misconception_risk);
+  const base = BASE_INTERVAL_BY_DECAY_RISK.get(decay) ?? 14;
+  let factor = 1;
+  if (misconception >= 4) factor = 0.5;
+  else if (misconception === 3) factor = 0.75;
+  return Math.max(1, Math.round(base * factor));
+}
+
+export function buildReviewSchedule(concepts, options = {}) {
+  if (!Array.isArray(concepts)) throw new TypeError('concepts must be an array');
+  const today = toDateOnly(options.today || new Date().toISOString().slice(0, 10));
+  return concepts.map((concept) => {
+    const first = intervalDaysForConcept(concept);
+    return {
+      concept: concept.concept || concept.label || concept.id,
+      first_review_date: addDays(today, first),
+      interval_days: [first, first * 2, first * 4].map((n) => Math.max(1, Math.round(n))),
+      reasons: {
+        decay_risk: clampRisk(concept.decay_risk),
+        misconception_risk: clampRisk(concept.misconception_risk),
+      },
+      promotion_requires: ['define from memory', 'new example', 'transfer', 'contrast', 'misconception repair', 'source check'],
+    };
+  });
+}

package/src/storage-contract.js

@@ -0,0 +1,42 @@
+export const DAG_STATE_FILES = [
+  'run_manifest.json',
+  'source_ledger.json',
+  'claim_ledger.json',
+  'kt_dag.json',
+  'learner_state.json',
+  'probe_results.json',
+  'review_schedule.json',
+  'output_manifest.json',
+];
+
+export const OBSIDIAN_FILES = [
+  '00-map.md',
+  'source-ledger.md',
+  'concepts/<concept>.md',
+  'misconceptions.md',
+  'probes.md',
+  'review-plan.md',
+  'reflection-log.md',
+  'manifest.md',
+];
+
+export function storagePlan({ topic = 'topic', dagStateRoot = '.pi-gnosis/state', obsidianRoot = 'notes', manimRoot = 'manim' } = {}) {
+  const slug = String(topic).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'topic';
+  return {
+    canonical: {
+      root: `${dagStateRoot}/${slug}`,
+      role: 'machine-readable runtime state for Pi-GNOSIS and pi-circuitry',
+      files: DAG_STATE_FILES.map((name) => `${dagStateRoot}/${slug}/${name}`),
+    },
+    obsidian: {
+      root: `${obsidianRoot}/${slug}`,
+      role: 'learner-facing notes and study memory',
+      files: OBSIDIAN_FILES.map((name) => `${obsidianRoot}/${slug}/${name}`),
+    },
+    manim: {
+      root: `${manimRoot}/${slug}`,
+      role: 'video lecture project output',
+      files: ['plan.md', 'scene_spec.json', 'script.py', 'render.sh', 'README.md'].map((name) => `${manimRoot}/${slug}/${name}`),
+    },
+  };
+}