@namewta/speculo 0.8.13 → 1.0.1

package/template/workflows/learning/common/schemas/change-status.schema.json

@@ -1,41 +1,69 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:learning:change-status:v1",
-  "title": "Learning Change Status",
+  "$id": "urn:speculo:learning:change-status:v2",
+  "title": "Learning Change Status v2",
   "type": "object",
-  "required": ["schema_version", "artifact", "change", "domain", "domain_type", "topic", "change_status", "phase", "current_work", "works_run", "created_at", "updated_at", "completed_at", "archived_at", "archive_path", "mastery", "blockers"],
+  "required": ["schema_version", "artifact", "change_id", "kind", "domain", "domain_type", "topic_id", "parent_change", "root_change", "locator", "lifecycle", "phase", "current_work", "works_run", "created_at", "updated_at", "closed_at", "archived_at", "closure_reason", "archive_path", "homework", "mastery", "children", "blockers"],
   "properties": {
-    "schema_version": {"const": 1},
+    "schema_version": {"const": 2},
     "artifact": {"const": "learning-change-status"},
-    "change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "change_id": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "kind": {"enum": ["learning", "consolidation"]},
     "domain": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
     "domain_type": {"enum": ["project", "product", "subject", "language", "skill"]},
-    "topic": {"type": "string", "minLength": 1},
-    "change_status": {"enum": ["active", "blocked", "awaiting_retention", "completed", "archived"]},
-    "phase": {"enum": ["intake", "assessment", "teaching", "practice", "immediate_quiz", "retention", "ready_to_archive", "archived"]},
+    "topic_id": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "parent_change": {"type": ["string", "null"]},
+    "root_change": {"type": "string"},
+    "locator": {"type": "string", "pattern": "^(?:changes/.+|archive/[0-9]{4}-[0-9]{2}/.+)$"},
+    "lifecycle": {"enum": ["active", "blocked", "closed", "archived"]},
+    "phase": {"enum": ["planning", "teaching", "homework", "review", "consolidating", "closed", "archived"]},
     "current_work": {"type": ["string", "null"], "pattern": "^learning/"},
     "works_run": {"type": "array", "items": {"type": "string", "pattern": "^learning/"}, "uniqueItems": true},
     "created_at": {"type": "string", "format": "date-time"},
     "updated_at": {"type": "string", "format": "date-time"},
-    "completed_at": {"type": ["string", "null"], "format": "date-time"},
+    "closed_at": {"type": ["string", "null"], "format": "date-time"},
     "archived_at": {"type": ["string", "null"], "format": "date-time"},
-    "archive_path": {"anyOf": [{"type": "null"}, {"type": "string", "pattern": "^<Path>\\{roots\\.state\\}/learning/archive/[0-9]{4}-[0-9]{2}/[^<]+</Path>$"}]},
+    "closure_reason": {"type": ["string", "null"]},
+    "archive_path": {"type": ["string", "null"]},
+    "homework": {
+      "type": "object",
+      "required": ["status", "latest_id", "submitted_at"],
+      "properties": {
+        "status": {"enum": ["none", "pending", "reviewed", "needs_revision"]},
+        "latest_id": {"type": ["string", "null"]},
+        "submitted_at": {"type": ["string", "null"], "format": "date-time"}
+      },
+      "additionalProperties": false
+    },
     "mastery": {
       "type": "object",
-      "required": ["immediate", "retention", "score", "critical_objectives_passed", "transfer_passed", "blocking_misconceptions", "evidence", "next_review_at"],
+      "required": ["overall", "immediate", "retention", "critical_objectives", "transfer", "blocking_misconceptions", "evidence", "next_review_at"],
       "properties": {
-        "immediate": {"enum": ["not_attempted", "failed", "passed", "needs_review"]},
-        "retention": {"enum": ["not_attempted", "failed", "passed", "needs_review"]},
-        "score": {"type": ["number", "null"], "minimum": 0, "maximum": 100},
-        "critical_objectives_passed": {"type": "boolean"},
-        "transfer_passed": {"type": "boolean"},
+        "overall": {"enum": ["unverified", "immediate", "retention_verified"]},
+        "immediate": {"enum": ["not_attempted", "passed", "needs_review"]},
+        "retention": {"enum": ["not_scheduled", "due", "passed", "needs_review"]},
+        "critical_objectives": {"enum": ["not_attempted", "passed", "needs_review"]},
+        "transfer": {"enum": ["not_attempted", "passed", "needs_review"]},
         "blocking_misconceptions": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
-        "evidence": {"type": "array", "items": {"type": "string", "pattern": "^<Path>\\{roots\\.state\\}/learning/(?:changes/[^<]+|archive/[0-9]{4}-[0-9]{2}/[^<]+)/quiz/[^<]+\\.md</Path>$"}, "uniqueItems": true},
+        "evidence": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
         "next_review_at": {"type": ["string", "null"], "format": "date-time"}
       },
       "additionalProperties": false
     },
-    "blockers": {"type": "array", "items": {"type": "string"}, "uniqueItems": true}
+    "children": {"type": "array", "items": {"$ref": "#/$defs/child"}, "uniqueItems": true},
+    "blockers": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
+    "child": {
+      "type": "object",
+      "required": ["change_id", "locator", "content_hash", "effective_at", "lifecycle"],
+      "properties": {
+        "change_id": {"type": "string"},
+        "locator": {"type": "string"},
+        "content_hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+        "effective_at": {"type": "string", "format": "date-time"},
+        "lifecycle": {"type": "string"}
+      },
+      "additionalProperties": false
+    }
   },
   "additionalProperties": false
 }

package/template/workflows/learning/common/schemas/status.schema.json

@@ -1,32 +1,33 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:learning:status:v1",
-  "title": "Learning Global Status",
+  "$id": "urn:speculo:learning:status:v2",
+  "title": "Learning Global Status v2",
   "type": "object",
   "required": ["schema_version", "workflow", "active", "archived"],
   "properties": {
-    "schema_version": {"const": 1},
+    "schema_version": {"const": 2},
     "workflow": {"const": "learning"},
-    "active": {
-      "type": "array",
-      "items": {
-        "type": "object",
-        "required": ["change", "domain", "topic", "current_work", "works_run"],
-        "properties": {
-          "change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
-          "domain": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
-          "topic": {"type": "string", "minLength": 1},
-          "current_work": {"type": ["string", "null"], "pattern": "^learning/"},
-          "works_run": {"type": "array", "items": {"type": "string", "pattern": "^learning/"}, "uniqueItems": true}
-        },
-        "additionalProperties": false
-      }
-    },
-    "archived": {
-      "type": "array",
-      "items": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
-      "uniqueItems": true
-    }
+    "active": {"type": "array", "items": {"$ref": "#/$defs/entry"}},
+    "archived": {"type": "array", "items": {"$ref": "#/$defs/entry"}}
   },
-  "additionalProperties": false
+  "additionalProperties": false,
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "required": ["change_id", "kind", "domain", "topic_id", "locator", "parent_change", "root_change", "current_work", "works_run"],
+      "properties": {
+        "change_id": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
+        "kind": {"enum": ["learning", "consolidation"]},
+        "domain": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+        "topic_id": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+        "locator": {"type": "string", "pattern": "^(?:changes/.+|archive/[0-9]{4}-[0-9]{2}/.+)$"},
+        "parent_change": {"type": ["string", "null"]},
+        "root_change": {"type": "string"},
+        "current_work": {"type": ["string", "null"], "pattern": "^learning/"},
+        "works_run": {"type": "array", "items": {"type": "string", "pattern": "^learning/"}, "uniqueItems": true},
+        "updated_at": {"type": "string", "format": "date-time"}
+      },
+      "additionalProperties": false
+    }
+  }
 }

package/template/workflows/learning/common/skills/topic-synthesis/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: topic-synthesis
+description: 将 Learning Change 作为不可变原料，生成带 claim 级 provenance 的主题综合并显式发布。
+---
+
+# Topic Synthesis
+
+1. 只接收 C-consolidate 已确认的 source manifest；按稳定 Change ID 读取当前 locator，禁止依赖旧路径猜测。
+2. 对每个 claim 记录 source Change、Lesson/Homework/Review anchor、外部 source id、证据状态、冲突、空白和验证时间；不要把类比或索引摘要当成事实来源。
+3. 生成新的 `synthesis/revisions/<version>.md`，旧版本只读保留。综合可以包含未掌握证据，但不得写 `mastered`，除非 R evidence 已存在。
+4. 发布 context 前必须再次获得用户确认；发布只更新 topic INDEX/current view 和 provenance，不删除或改写任何 child 原料。
+
+## 引用模板
+
+| claim_id | 陈述 | evidence_status | source_change_id | artifact anchor | external source | verified_at |
+| --- | --- | --- | --- | --- | --- | --- |
+| CLM-001 | `<claim>` | supported | `<change-id>` | `L-001#heading` | `S-001` | `<ISO-8601>` |

package/template/workflows/learning/common/skills/topic-synthesis/claim-template.md

@@ -0,0 +1,15 @@
+# Claim <CLM-NNN>
+
+## 陈述
+
+## Evidence status
+
+`draft | supported | contested | unresolved`
+
+## 来源与定位
+
+- Change ID / current locator：
+- Lesson/Homework/Review anchor：
+- External source ID / URL / access date：
+
+## 冲突、空白与下一次验证

package/template/workflows/learning/common/tools/relocate-learning.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+const CHANGE_ID = /^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function args(argv) {
+  const result = { stateRoot: null, parent: null, sources: [], apply: false, rollback: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--state-root") result.stateRoot = resolve(argv[++index] ?? "");
+    else if (arg === "--parent") result.parent = argv[++index] ?? null;
+    else if (arg === "--source") result.sources.push(argv[++index] ?? "");
+    else if (arg === "--apply") result.apply = true;
+    else if (arg === "--rollback") result.rollback = resolve(argv[++index] ?? "");
+    else throw new Error(`unknown option: ${arg}`);
+  }
+  if (!result.stateRoot) throw new Error("--state-root is required");
+  if (result.rollback) return result;
+  if (!result.parent || !CHANGE_ID.test(result.parent) || result.sources.length === 0) {
+    throw new Error("--parent and at least one --source are required");
+  }
+  if (result.sources.some((source) => !CHANGE_ID.test(source)) || new Set(result.sources).size !== result.sources.length) {
+    throw new Error("source ids must be unique valid Change IDs");
+  }
+  if (result.sources.includes(result.parent)) throw new Error("a parent cannot be one of its own sources");
+  return result;
+}
+
+async function json(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function files(root) {
+  const result = [];
+  async function visit(current) {
+    const entries = await (await import("node:fs/promises")).readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) await visit(path);
+      else if (entry.isFile()) result.push(path);
+    }
+  }
+  await visit(root);
+  return result.sort();
+}
+
+async function contentHash(root) {
+  const hash = createHash("sha256");
+  for (const path of await files(root)) {
+    const rel = relative(root, path).split(sep).join("/");
+    if (rel === ".status.json") continue;
+    hash.update(rel);
+    hash.update(await readFile(path));
+  }
+  return hash.digest("hex");
+}
+
+async function loadLocations(stateRoot) {
+  const path = join(stateRoot, "locations.json");
+  const value = await json(path, { schema_version: 2, workflow: "learning", entries: [] });
+  if (value.schema_version !== 2 || value.workflow !== "learning" || !Array.isArray(value.entries)) {
+    throw new Error("locations.json must use Learning schema v2");
+  }
+  return { path, value };
+}
+
+function locatorFor(entry, stateRoot) {
+  const locator = entry?.locator;
+  if (typeof locator === "string" && (locator.startsWith("changes/") || locator.startsWith("archive/"))) return locator;
+  return `changes/${entry.change_id}`;
+}
+
+function updateLocation(value, id, from, to, hash, now, parent) {
+  const existing = value.entries.find((entry) => entry.change_id === id);
+  if (existing) {
+    existing.previous = Array.isArray(existing.previous) ? existing.previous : [];
+    existing.previous.push({ locator: from, moved_at: now, reason: "consolidate", content_hash: hash });
+    existing.locator = to;
+    existing.parent_change = parent;
+    existing.root_change = value.entries.find((entry) => entry.change_id === parent)?.root_change ?? parent;
+    existing.content_hash = hash;
+    existing.updated_at = now;
+    return;
+  }
+  value.entries.push({
+    change_id: id,
+    locator: to,
+    parent_change: parent,
+    root_change: parent,
+    content_hash: hash,
+    previous: [{ locator: from, moved_at: now, reason: "consolidate", content_hash: hash }],
+    updated_at: now,
+  });
+}
+
+async function updateStatus(path, id, to, parent, now) {
+  const statusPath = join(path, ".status.json");
+  if (!existsSync(statusPath)) return;
+  const value = await json(statusPath, null);
+  if (!value || value.schema_version !== 2 || value.change_id !== id) return;
+  value.parent_change = parent;
+  value.root_change = value.root_change === id ? parent : value.root_change;
+  value.locator = to;
+  value.updated_at = now;
+  await writeFile(statusPath, JSON.stringify(value, null, 2) + "\n", "utf8");
+}
+
+async function updateGlobalStatus(stateRoot, ids, parent, now) {
+  const path = join(stateRoot, "status.json");
+  const value = await json(path, null);
+  if (!value || value.schema_version !== 2) return;
+  const root = value.active.find((entry) => entry.change_id === parent)?.root_change ?? parent;
+  for (const entry of [...value.active, ...value.archived]) {
+    if (!ids.includes(entry.change_id)) continue;
+    entry.parent_change = parent;
+    entry.root_change = root;
+    entry.locator = entry.locator;
+    entry.updated_at = now;
+  }
+  await writeFile(path, JSON.stringify(value, null, 2) + "\n", "utf8");
+}
+
+async function rollbackManifest(manifestPath) {
+  const manifest = await json(manifestPath, null);
+  if (!manifest || !Array.isArray(manifest.moves)) throw new Error("invalid relocation manifest");
+  for (const move of [...manifest.moves].reverse()) {
+    if (existsSync(move.to) && !existsSync(move.from)) await rename(move.to, move.from);
+  }
+  await writeFile(manifestPath, JSON.stringify({ ...manifest, rolled_back_at: new Date().toISOString() }, null, 2) + "\n", "utf8");
+  console.log(JSON.stringify({ status: "rolled-back", manifest: manifestPath }));
+}
+
+async function main() {
+  const options = args(process.argv.slice(2));
+  if (options.rollback) {
+    await rollbackManifest(options.rollback);
+    return;
+  }
+  const changesRoot = join(options.stateRoot, "changes");
+  const parentPath = join(changesRoot, options.parent);
+  if (!existsSync(parentPath)) throw new Error(`parent Change does not exist: ${options.parent}`);
+  const { path: locationsPath, value: locations } = await loadLocations(options.stateRoot);
+  const moves = [];
+  for (const id of options.sources) {
+    const entry = locations.entries.find((candidate) => candidate.change_id === id);
+    const fromLocator = locatorFor(entry, options.stateRoot);
+    if (!fromLocator.startsWith("changes/")) throw new Error(`source is not an active/closed Change: ${id}`);
+    const from = join(options.stateRoot, ...fromLocator.split("/"));
+    if (!existsSync(from)) throw new Error(`source Change is missing: ${fromLocator}`);
+    const relativeFrom = fromLocator.split("/");
+    if (relativeFrom.slice(0, 2).join("/") === `changes/${options.parent}` || from === parentPath || parentPath.startsWith(from + sep)) {
+      throw new Error(`source/parent cycle detected for ${id}`);
+    }
+    const to = join(parentPath, "children", id);
+    if (existsSync(to)) throw new Error(`target child already exists: ${id}`);
+    moves.push({ id, from, to, from_locator: fromLocator, to_locator: `changes/${options.parent}/children/${id}` });
+  }
+  const hashes = [];
+  for (const move of moves) hashes.push({ id: move.id, content_hash: await contentHash(move.from) });
+  const now = new Date().toISOString();
+  const manifest = {
+    schema_version: 1,
+    artifact: "learning-relocation-manifest",
+    parent_change: options.parent,
+    created_at: now,
+    moves: moves.map((move) => ({ ...move, content_hash: hashes.find((item) => item.id === move.id).content_hash })),
+  };
+  if (!options.apply) {
+    console.log(JSON.stringify({ status: "dry-run", ...manifest }, null, 2));
+    return;
+  }
+
+  await mkdir(join(parentPath, "children"), { recursive: true });
+  const lockPath = join(options.stateRoot, ".consolidate.lock");
+  let lock;
+  try {
+    lock = await open(lockPath, "wx");
+    for (const move of moves) await rename(move.from, move.to);
+    for (const move of manifest.moves) {
+      updateLocation(locations, move.id, move.from_locator, move.to_locator, move.content_hash, now, options.parent);
+      await updateStatus(join(options.stateRoot, ...move.to_locator.split("/")), move.id, move.to_locator, options.parent, now);
+    }
+    await writeFile(locationsPath, JSON.stringify(locations, null, 2) + "\n", "utf8");
+    await updateGlobalStatus(options.stateRoot, options.sources, options.parent, now);
+    const manifestPath = join(parentPath, "synthesis", `relocation-${now.replaceAll(/[^0-9]/g, "").slice(0, 14)}.json`);
+    await mkdir(dirname(manifestPath), { recursive: true });
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+    console.log(JSON.stringify({ status: "applied", manifest: manifestPath, moves: manifest.moves }, null, 2));
+  } catch (error) {
+    for (const move of [...moves].reverse()) {
+      if (existsSync(move.to) && !existsSync(move.from)) await rename(move.to, move.from);
+    }
+    throw error;
+  } finally {
+    if (lock) await lock.close();
+    await rm(lockPath, { force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(`Learning relocation failed: ${error.message}`);
+  process.exitCode = 1;
+});