scrumrun 1.5.2 → 2.0.0

package/lib/memory/service.js

@@ -0,0 +1,300 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const {
+  ARTIFACT_TYPES,
+  ArtifactRepository,
+  METHOD_VERSION,
+  assertNoSymlinkPath,
+  atomicWrite,
+  parseArtifact,
+  transitionArtifact,
+  validateArtifact,
+  withArtifactLock
+} = require("../v2/artifacts");
+const { extractEvidence, renderBullets } = require("./markdown");
+const { assertNoSecret } = require("../security/secrets");
+
+const MEMORY_KINDS = new Set(["knowledge", "decision", "insight", "dossier"]);
+const DEFAULT_STATUS = Object.freeze({ knowledge: "candidate", decision: "open", insight: "candidate", dossier: "active" });
+const ACTIONS = Object.freeze({
+  knowledge: { approve: "approved", reject: "rejected", deprecate: "deprecated", invalidate: "invalidated" },
+  decision: { resolve: "resolved", deprecate: "deprecated", invalidate: "invalidated" },
+  insight: { confirm: "confirmed", stale: "stale", reject: "invalidated", invalidate: "invalidated", deprecate: "deprecated" },
+  dossier: { refresh: "active", stale: "stale", archive: "archived", deprecate: "deprecated" }
+});
+const CONFIRMED_STATUS = new Set(["approved", "confirmed", "resolved"]);
+const ARTIFACT_PREFIX_KIND = Object.freeze(Object.fromEntries(
+  Object.entries(ARTIFACT_TYPES).map(([kind, spec]) => [spec.prefix, kind])
+));
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function oneLine(value, field) {
+  const text = String(value || "").trim();
+  if (!text) throw new Error(`${field} is required.`);
+  if (/\r|\n/.test(text)) throw new Error(`${field} must be one line.`);
+  return text;
+}
+
+function normalizedList(values, field) {
+  if (values === undefined || values === null) return [];
+  const list = Array.isArray(values) ? values : [values];
+  return [...new Set(list.map((value) => oneLine(value, field)))];
+}
+
+function optionalDate(value, field) {
+  if (value === undefined || value === null || value === "") return null;
+  const text = oneLine(value, field);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(text)) throw new Error(`${field} must be YYYY-MM-DD.`);
+  return text;
+}
+
+function nextMemoryId(repository, kind) {
+  const prefix = ARTIFACT_TYPES[kind].prefix;
+  const highest = repository.list(kind).reduce((max, artifact) => {
+    const match = artifact.record && artifact.record.id.match(/-(\d+)$/);
+    return match ? Math.max(max, Number(match[1])) : max;
+  }, 0);
+  return `${prefix}-${String(highest + 1).padStart(3, "0")}`;
+}
+
+function assertV2Project(projectRoot) {
+  const marker = path.join(projectRoot, ".scrumrun", "method.json");
+  if (!fs.existsSync(marker) || !fs.lstatSync(marker).isFile()) throw new Error("Canonical ScrumRun 2.0 method.json is missing.");
+  let value;
+  try {
+    value = JSON.parse(fs.readFileSync(marker, "utf8"));
+  } catch {
+    throw new Error("Canonical ScrumRun method.json is malformed.");
+  }
+  if (value.method !== METHOD_VERSION) throw new Error(`Project method must be ${METHOD_VERSION}.`);
+}
+
+function currentCommit(projectRoot) {
+  const gitDir = path.join(projectRoot, ".git");
+  const headFile = path.join(gitDir, "HEAD");
+  if (!fs.existsSync(headFile)) return null;
+  const head = fs.readFileSync(headFile, "utf8").trim();
+  if (/^[a-f0-9]{40,64}$/i.test(head)) return head;
+  const ref = head.match(/^ref:\s+(.+)$/);
+  if (!ref || ref[1].includes("..")) return null;
+  const refFile = path.resolve(gitDir, ref[1]);
+  if (!refFile.startsWith(`${path.resolve(gitDir)}${path.sep}`) || !fs.existsSync(refFile)) return null;
+  const value = fs.readFileSync(refFile, "utf8").trim();
+  return /^[a-f0-9]{40,64}$/i.test(value) ? value : null;
+}
+
+function kindForArtifactId(reference) {
+  const match = String(reference).match(/^([A-Z]+)-\d{3,}$/);
+  return match ? ARTIFACT_PREFIX_KIND[match[1]] || null : null;
+}
+
+function evidencePath(reference) {
+  return String(reference)
+    .replace(/^path:\s*/i, "")
+    .replace(/#L\d+(?:-L\d+)?$/i, "")
+    .replace(/:\d+(?::\d+)?$/, "");
+}
+
+function resolveEvidence(projectRoot, repository, reference) {
+  const value = oneLine(reference, "evidence");
+  const artifactKind = kindForArtifactId(value);
+  if (artifactKind) {
+    const artifact = repository.read(artifactKind, value);
+    return artifact && !artifact.errors.length
+      ? { reference: value, type: "artifact", resolved: true }
+      : { reference: value, type: "artifact", resolved: false, reason: "artifact not found or invalid" };
+  }
+
+  const relative = evidencePath(value);
+  if (path.isAbsolute(relative) || relative.split(/[\\/]+/).includes("..")) {
+    return { reference: value, type: "path", resolved: false, reason: "unsafe path" };
+  }
+  if (/(^|[\\/])vault(?:\.local)?\.md$|(^|[\\/])vault([\\/]|$)/i.test(relative)) {
+    return { reference: value, type: "path", resolved: false, reason: "vault evidence is forbidden" };
+  }
+  const root = path.resolve(projectRoot);
+  const target = path.resolve(root, relative);
+  const inside = target === root || target.startsWith(`${root}${path.sep}`);
+  if (inside) {
+    try {
+      assertNoSymlinkPath(root, target);
+    } catch (error) {
+      return { reference: value, type: "path", resolved: false, reason: error.message };
+    }
+  }
+  return {
+    reference: value,
+    type: "path",
+    resolved: inside && fs.existsSync(target),
+    reason: inside ? (fs.existsSync(target) ? null : "path not found") : "path escapes project"
+  };
+}
+
+function assertResolvableEvidence(projectRoot, repository, evidence) {
+  if (!evidence.length) throw new Error("Confirmed memory requires at least one evidence reference.");
+  const resolution = evidence.map((item) => resolveEvidence(projectRoot, repository, item));
+  const unresolved = resolution.filter((item) => !item.resolved);
+  if (unresolved.length) {
+    throw new Error(`Unresolved evidence: ${unresolved.map((item) => `${item.reference} (${item.reason})`).join(", ")}`);
+  }
+  return resolution;
+}
+
+function createMemoryUnlocked(projectRoot, kind, options = {}) {
+  if (!MEMORY_KINDS.has(kind)) throw new Error(`Unsupported memory kind: ${kind}`);
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  const repository = new ArtifactRepository(scrumDir);
+  const created = today();
+  const title = oneLine(options.title || options.content, "title");
+  const content = String(options.content || title).trim();
+  if (!content) throw new Error("content is required.");
+  const evidence = normalizedList(options.evidence, "evidence");
+  const relations = normalizedList(options.relations, "relation");
+  assertNoSecret([title, content, ...evidence, ...relations]);
+  const malformedRelation = relations.find((relation) => !/^[a-z][a-z0-9_]*\s*(?::|→|->)\s*\S/i.test(relation));
+  if (malformedRelation) throw new Error(`Malformed relation: ${malformedRelation}. Use relation: target.`);
+  const sourceType = oneLine(options.sourceType || "human", "sourceType").toLowerCase();
+  const confidence = options.confidence === undefined || options.confidence === null
+    ? null
+    : Number(options.confidence);
+  if (confidence !== null && (!Number.isFinite(confidence) || confidence < 0 || confidence > 1)) {
+    throw new Error("confidence must be a number between 0 and 1.");
+  }
+  const record = {
+    id: nextMemoryId(repository, kind),
+    kind,
+    status: DEFAULT_STATUS[kind],
+    created,
+    updated: created,
+    method: METHOD_VERSION,
+    subject_type: options.subjectType ? oneLine(options.subjectType, "subjectType") : null,
+    subject_id: options.subjectId ? oneLine(options.subjectId, "subjectId") : null,
+    source_type: sourceType,
+    source_id: options.sourceId ? oneLine(options.sourceId, "sourceId") : null,
+    confidence,
+    valid_from: optionalDate(options.validFrom, "validFrom"),
+    valid_until: optionalDate(options.validUntil, "validUntil"),
+    last_verified_commit: null,
+    review_trigger: options.reviewTrigger ? oneLine(options.reviewTrigger, "reviewTrigger") : null
+  };
+  if (kind === "insight" && sourceType === "ai") record.status = "candidate";
+  if (kind === "dossier") assertResolvableEvidence(projectRoot, repository, evidence);
+  const body = [
+    `# ${title}`,
+    "",
+    kind === "decision" ? "## Decision" : kind === "dossier" ? "## Scope" : "## Statement",
+    "",
+    content,
+    "",
+    "## Evidence",
+    "",
+    renderBullets(evidence, "confirmation requires resolvable evidence."),
+    "",
+    "## Relations",
+    "",
+    renderBullets(relations, "no explicit relations."),
+    "",
+    "## Lifecycle",
+    "",
+    `- ${created}: ${record.status} — proposed by ${sourceType}.`
+  ].join("\n");
+  repository.write(record, body);
+  return repository.read(kind, record.id);
+}
+
+function createMemory(projectRoot, kind, options = {}) {
+  if (!MEMORY_KINDS.has(kind)) throw new Error(`Unsupported memory kind: ${kind}`);
+  assertV2Project(projectRoot);
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  return withArtifactLock(scrumDir, `memory-${kind}`, () => createMemoryUnlocked(projectRoot, kind, options));
+}
+
+function setFrontmatter(content, updates) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---([\s\S]*)$/);
+  if (!match) throw new Error("Memory artifact has malformed frontmatter.");
+  let frontmatter = match[1];
+  for (const [field, value] of Object.entries(updates)) {
+    const rendered = value === null ? "null" : String(value);
+    const line = new RegExp(`^${field}:\\s*.*$`, "m");
+    frontmatter = line.test(frontmatter)
+      ? frontmatter.replace(line, `${field}: ${rendered}`)
+      : `${frontmatter}\n${field}: ${rendered}`;
+  }
+  return `---\n${frontmatter}\n---${match[2]}`;
+}
+
+function transitionMemoryUnlocked(projectRoot, kind, id, action, options = {}) {
+  if (!MEMORY_KINDS.has(kind)) throw new Error(`Unsupported memory kind: ${kind}`);
+  const nextStatus = ACTIONS[kind] && ACTIONS[kind][action];
+  if (!nextStatus) throw new Error(`Unsupported ${kind} action: ${action}`);
+  const repository = new ArtifactRepository(path.join(projectRoot, ".scrumrun"));
+  const artifact = repository.read(kind, id);
+  if (!artifact) throw new Error(`${id} not found.`);
+  if (artifact.errors.length) throw new Error(`Invalid ${id}: ${artifact.errors.join("; ")}`);
+  const addedEvidence = normalizedList(options.evidence, "evidence");
+  assertNoSecret([options.note || "", ...addedEvidence]);
+  const allEvidence = [...new Set([...extractEvidence(artifact.body), ...addedEvidence])];
+  if (CONFIRMED_STATUS.has(nextStatus)) assertResolvableEvidence(projectRoot, repository, allEvidence);
+
+  const date = today();
+  const refreshInPlace = kind === "dossier" && action === "refresh" && artifact.record.status === "active";
+  if (!refreshInPlace) transitionArtifact(artifact.record, nextStatus, date);
+  const previous = fs.readFileSync(artifact.file, "utf8");
+  const verified = CONFIRMED_STATUS.has(nextStatus) || action === "refresh";
+  const commit = verified ? currentCommit(projectRoot) : artifact.record.last_verified_commit;
+  let next = setFrontmatter(previous, {
+    status: nextStatus,
+    updated: date,
+    ...(verified ? { last_verified_commit: commit || "unavailable" } : {})
+  });
+  const note = options.note ? oneLine(options.note, "note") : `${action} requested through ScrumRun.`;
+  const review = [
+    "",
+    `## Memory Review ${date} · ${action}`,
+    "",
+    `- Transition: ${refreshInPlace ? `${nextStatus} (refreshed)` : `${artifact.record.status} → ${nextStatus}`}`,
+    `- Note: ${note}`
+  ].join("\n");
+  const evidenceReview = addedEvidence.length
+    ? `\n\n## Evidence ${date} · ${action}\n\n${renderBullets(addedEvidence, "none.")}`
+    : "";
+  next = `${next.trimEnd()}\n${review}${evidenceReview}\n`;
+  const parsed = parseArtifact(next);
+  const errors = [...parsed.errors, ...validateArtifact(parsed.record, kind)];
+  if (errors.length) throw new Error(`Memory transition validation failed: ${errors.join("; ")}`);
+  atomicWrite(artifact.file, next);
+  return repository.read(kind, id);
+}
+
+function transitionMemory(projectRoot, kind, id, action, options = {}) {
+  if (!MEMORY_KINDS.has(kind)) throw new Error(`Unsupported memory kind: ${kind}`);
+  assertV2Project(projectRoot);
+  return withArtifactLock(path.join(projectRoot, ".scrumrun"), `memory-${kind}`, () => transitionMemoryUnlocked(projectRoot, kind, id, action, options));
+}
+
+function listMemory(projectRoot, kind, { includeInactive = true } = {}) {
+  if (!MEMORY_KINDS.has(kind)) throw new Error(`Unsupported memory kind: ${kind}`);
+  const excluded = new Set(["rejected", "invalidated", "deprecated", "archived"]);
+  return new ArtifactRepository(path.join(projectRoot, ".scrumrun")).list(kind)
+    .filter((artifact) => includeInactive || !excluded.has(artifact.record.status));
+}
+
+function showMemory(projectRoot, kind, id) {
+  if (!MEMORY_KINDS.has(kind)) throw new Error(`Unsupported memory kind: ${kind}`);
+  return new ArtifactRepository(path.join(projectRoot, ".scrumrun")).read(kind, id);
+}
+
+module.exports = {
+  ACTIONS,
+  assertV2Project,
+  createMemory,
+  listMemory,
+  resolveEvidence,
+  showMemory,
+  transitionMemory
+};

package/lib/runtime/budgets.js

@@ -0,0 +1,19 @@
+"use strict";
+
+const V1_CONTROL_CONTEXT_BASELINE_CHARS = 48000;
+const LEAN_CONTROL_CONTEXT_MAX_RATIO = 0.25;
+const LEAN_CONTROL_CONTEXT_MAX_CHARS = V1_CONTROL_CONTEXT_BASELINE_CHARS * LEAN_CONTROL_CONTEXT_MAX_RATIO;
+const MAX_CONTEXT_RESULTS = 100;
+const DEFAULT_CONTEXT_RESULTS = 10;
+const MAX_RELATIONS_PER_RESULT = 100;
+const DEFAULT_RELATIONS_PER_RESULT = 40;
+
+module.exports = {
+  DEFAULT_CONTEXT_RESULTS,
+  DEFAULT_RELATIONS_PER_RESULT,
+  LEAN_CONTROL_CONTEXT_MAX_CHARS,
+  LEAN_CONTROL_CONTEXT_MAX_RATIO,
+  MAX_CONTEXT_RESULTS,
+  MAX_RELATIONS_PER_RESULT,
+  V1_CONTROL_CONTEXT_BASELINE_CHARS
+};

package/lib/runtime/context.js

@@ -0,0 +1,141 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { ARTIFACT_TYPES, ArtifactRepository, sha256 } = require("../v2/artifacts");
+const { readProjectModel } = require("../v2/project-store");
+const { containsSecret } = require("../security/secrets");
+
+const EXCLUDED_ROOT_ENTRIES = new Set([".git", ".scrumrun", "node_modules", "dist", "build", "coverage"]);
+
+function read(file) {
+  return fs.existsSync(file) && fs.lstatSync(file).isFile() ? fs.readFileSync(file, "utf8") : "";
+}
+
+function capped(text, limit = 1200) {
+  if (text.length <= limit) return text;
+  return `${text.slice(0, limit)}\n…[truncated ${text.length - limit} chars]`;
+}
+
+function projectScan(projectRoot) {
+  const entries = fs.readdirSync(projectRoot, { withFileTypes: true })
+    .filter((entry) => !EXCLUDED_ROOT_ENTRIES.has(entry.name))
+    .map((entry) => ({ name: entry.name, kind: entry.isDirectory() ? "directory" : "file" }))
+    .slice(0, 80);
+  const packageFile = path.join(projectRoot, "package.json");
+  let packageSummary = null;
+  if (fs.existsSync(packageFile) && fs.lstatSync(packageFile).isFile()) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(packageFile, "utf8"));
+      packageSummary = {
+        name: pkg.name || null,
+        scripts: Object.keys(pkg.scripts || {}).sort(),
+        dependencies: Object.keys(pkg.dependencies || {}).sort().slice(0, 100),
+        devDependencies: Object.keys(pkg.devDependencies || {}).sort().slice(0, 100)
+      };
+    } catch {
+      packageSummary = { error: "package.json is malformed" };
+    }
+  }
+  return { project: path.basename(projectRoot), entries, package: packageSummary };
+}
+
+function guardrailRecords(content) {
+  const headings = [...content.matchAll(/^## (GR-\d{3,})\s*[-—:]\s*([^\r\n]+)$/gm)];
+  return headings.map((heading, index) => {
+    const end = index + 1 < headings.length ? headings[index + 1].index : content.length;
+    const block = content.slice(heading.index, end);
+    const rule = (block.match(/^Rule:\s*(.+)$/m) || [])[1] || heading[2];
+    const status = ((block.match(/^Status:\s*(.+)$/m) || [])[1] || "active").trim();
+    return { id: heading[1], title: heading[2].trim(), rule: capped(rule.trim(), 500), status };
+  });
+}
+
+function artifactSnapshot(scrumDir) {
+  const repository = new ArtifactRepository(scrumDir);
+  const records = {};
+  const hashes = [];
+  const warnings = [];
+  for (const kind of Object.keys(ARTIFACT_TYPES)) {
+    records[kind] = repository.list(kind).map((artifact) => {
+      const relative = path.relative(scrumDir, artifact.file).split(path.sep).join("/");
+      const content = read(artifact.file);
+      hashes.push(`${relative}\0${sha256(content)}`);
+      if (containsSecret(content)) {
+        warnings.push(`Secret-like content detected in canonical artifact: ${relative}`);
+        return { id: artifact.record ? artifact.record.id : path.basename(artifact.file, ".md"), status: "unsafe", title: "[redacted]" };
+      }
+      return artifact.record ? {
+        id: artifact.record.id,
+        status: artifact.record.status,
+        title: ((artifact.body || "").match(/^# ([^\r\n]+)/m) || [])[1] || artifact.record.id,
+        task: artifact.record.task || null,
+        sprint: artifact.record.sprint || null,
+        feature: artifact.record.feature || null
+      } : { id: path.basename(artifact.file, ".md"), status: "invalid", errors: artifact.errors };
+    });
+  }
+  return { records, hashes, warnings };
+}
+
+function contextFingerprint(scrumDir, artifactHashes) {
+  const canonical = ["guardrails.md", "config.md", "project.md", "method.json"]
+    .map((relative) => {
+      const content = read(path.join(scrumDir, relative));
+      return `${relative}\0${content ? sha256(content) : "missing"}`;
+    });
+  return sha256([...canonical, ...artifactHashes].sort().join("\n"));
+}
+
+function buildContextPackage(projectRoot, request) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  if (!fs.existsSync(scrumDir)) throw new Error("Not a ScrumRun project: .scrumrun/ is missing.");
+  const model = readProjectModel(projectRoot);
+  const securityWarnings = [];
+  const safeControl = (relative, limit) => {
+    const content = read(path.join(scrumDir, relative));
+    if (containsSecret(content)) {
+      securityWarnings.push(`Secret-like content detected in canonical control: ${relative}`);
+      return "[redacted: secret-like content]";
+    }
+    return capped(content, limit);
+  };
+  const guardrailsContent = safeControl("guardrails.md", 10000);
+  const config = safeControl("config.md", 1000);
+  const project = safeControl("project.md", 1400);
+  const artifacts = model.source === "canonical-v2" ? artifactSnapshot(scrumDir) : { records: {}, hashes: [], warnings: [] };
+  const openDecisions = (artifacts.records.decision || []).filter((record) => record.status === "open").slice(-10);
+  const recentRuns = (artifacts.records.run || []).slice(-10).reverse();
+  const activeWork = ["feature", "task", "sprint", "run"].flatMap((kind) =>
+    (artifacts.records[kind] || []).filter((record) => !["completed", "failed", "cancelled"].includes(record.status))
+  ).slice(0, 50);
+  const missing = [];
+  for (const relative of ["guardrails.md", "config.md", "project.md"]) {
+    if (!fs.existsSync(path.join(scrumDir, relative))) missing.push(relative);
+  }
+  const fingerprint = contextFingerprint(scrumDir, artifacts.hashes);
+  const stateContent = read(path.join(scrumDir, "state.md"));
+  const stateFingerprint = (stateContent.match(/^Source fingerprint:\s*([a-f0-9]{64})$/m) || [])[1];
+  if (!stateFingerprint) missing.push("state.md has no source fingerprint and is stale");
+  else if (stateFingerprint !== fingerprint) missing.push("state.md source fingerprint is stale");
+  return {
+    request: capped(request.trim(), 10000),
+    layout: model.layout,
+    source: model.source,
+    fingerprint,
+    projectScan: projectScan(projectRoot),
+    guardrails: guardrailRecords(guardrailsContent).filter((record) => record.status === "active").slice(0, 100),
+    config,
+    project: project || "[missing]",
+    history: { recentRuns },
+    decisions: { open: openDecisions },
+    activeWork,
+    graph: {
+      nodeCount: model.graph.nodes.length,
+      edgeCount: model.graph.edges.length
+    },
+    warnings: [...(model.warnings || []), ...securityWarnings, ...(artifacts.warnings || []), ...missing.map((relative) => relative.startsWith("state.md") ? relative : `Missing canonical context: ${relative}`)]
+  };
+}
+
+module.exports = { buildContextPackage, contextFingerprint, guardrailRecords, projectScan };