opencode-swarm 7.107.0 → 7.107.1

package/dist/cli/index-357p0baj.js

@@ -0,0 +1,719 @@
+// @bun
+import {
+  exports_external
+} from "./index-293f68mj.js";
+
+// src/sdd/effective-spec.ts
+import { createHash } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+
+// src/config/spec-schema.ts
+var ObligationSchema = exports_external.enum(["MUST", "SHALL", "SHOULD", "MAY"]);
+var SpecRequirementSchema = exports_external.object({
+  id: exports_external.string().regex(/^FR-(?!000)\d{3}$/, "Requirement ID must match FR-### pattern (e.g., FR-001)"),
+  obligation: ObligationSchema,
+  text: exports_external.string().min(1)
+});
+var SpecScenarioSchema = exports_external.object({
+  name: exports_external.string().min(1),
+  given: exports_external.array(exports_external.string()).optional().default([]),
+  when: exports_external.array(exports_external.string()).min(1, 'Scenario must have at least one "when" clause'),
+  thenClauses: exports_external.array(exports_external.string()).min(1, 'Scenario must have at least one "then" clause')
+});
+var SpecSectionSchema = exports_external.object({
+  name: exports_external.string().min(1),
+  requirements: exports_external.array(SpecRequirementSchema).default([])
+});
+var SwarmSpecSchema = exports_external.object({
+  title: exports_external.string().min(1),
+  purpose: exports_external.string().min(1),
+  sections: exports_external.array(SpecSectionSchema).min(1, "Spec must have at least one section")
+});
+var SpecDeltaSchema = exports_external.object({
+  added: exports_external.array(SpecRequirementSchema).default([]),
+  modified: exports_external.array(SpecRequirementSchema).default([]),
+  removed: exports_external.array(SpecRequirementSchema).default([])
+});
+var DeltaSpecSchema = exports_external.union([
+  SwarmSpecSchema,
+  SpecDeltaSchema
+]);
+var FENCED_BLOCK_PATTERN = /```[\s\S]*?```/g;
+var INLINE_CODE_PATTERN = /`[^`]*`/g;
+var FR_ID_PATTERN = /\bFR-\d{3}\b/g;
+var OBLIGATION_PATTERN = /\b(MUST|SHALL|SHOULD|MAY)\b/g;
+var SECTION_HEADER_PATTERN = /^##\s+.+$/gm;
+function stripCodeBlocks(content) {
+  return content.replace(FENCED_BLOCK_PATTERN, "").replace(INLINE_CODE_PATTERN, "");
+}
+function getLineNumber(content, position) {
+  const prefix = content.substring(0, position);
+  return (prefix.match(/\n/g) || []).length + 1;
+}
+function validateSpecContent(content) {
+  const issues = [];
+  if (!content || content.trim().length === 0) {
+    return { valid: false, issues: [{ line: 1, message: "Content is empty" }] };
+  }
+  const strippedContent = stripCodeBlocks(content);
+  const frMatches = strippedContent.match(FR_ID_PATTERN);
+  if (!frMatches || frMatches.length === 0) {
+    issues.push({
+      line: 1,
+      message: "No FR-### requirement IDs found in spec content"
+    });
+  }
+  const obligationMatches = strippedContent.match(OBLIGATION_PATTERN);
+  if (!obligationMatches || obligationMatches.length === 0) {
+    issues.push({
+      line: 1,
+      message: "No obligation keywords (MUST, SHALL, SHOULD, MAY) found in spec content"
+    });
+  }
+  const sectionMatches = strippedContent.match(SECTION_HEADER_PATTERN);
+  if (!sectionMatches || sectionMatches.length === 0) {
+    issues.push({
+      line: 1,
+      message: "No section headers (## Section Name) found in spec content"
+    });
+  }
+  const idMatches = strippedContent.matchAll(/\bFR-(\d{3})\b/g);
+  for (const idMatch of idMatches) {
+    const num = parseInt(idMatch[1], 10);
+    if (num === 0) {
+      const pos = idMatch.index;
+      issues.push({
+        line: getLineNumber(strippedContent, pos),
+        message: `Invalid FR-ID "${idMatch[0]}" \u2014 number must be 001-999`
+      });
+    }
+  }
+  return {
+    valid: issues.length === 0,
+    issues
+  };
+}
+
+// src/sdd/effective-spec.ts
+var SWARM_SPEC_REL = path.join(".swarm", "spec.md");
+var OPENSPEC_ROOT = "openspec";
+var SPECKIT_MARKER = ".specify";
+var SPECKIT_SPECS_DIR = "specs";
+var MAX_SPEC_BYTES = 256 * 1024;
+var MAX_SOURCE_BYTES = 512 * 1024;
+var MAX_SPEC_FILES = 100;
+var MAX_WALK_DEPTH = 10;
+var SPECKIT_REQUIRED_SECTIONS = [
+  "## Functional Requirements",
+  "## Success Criteria"
+];
+function toPosix(relPath) {
+  return relPath.split(path.sep).join("/");
+}
+function hash(content) {
+  return createHash("sha256").update(content, "utf-8").digest("hex");
+}
+function readTextBounded(absPath) {
+  let stat;
+  try {
+    stat = fs.lstatSync(absPath);
+  } catch {
+    return null;
+  }
+  if (!stat.isFile() || stat.size > MAX_SOURCE_BYTES) {
+    return null;
+  }
+  try {
+    return fs.readFileSync(absPath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function fileArtifact(root, absPath) {
+  try {
+    const stat = fs.lstatSync(absPath);
+    if (!stat.isFile() || stat.size > MAX_SOURCE_BYTES)
+      return null;
+    return {
+      relPath: toPosix(path.relative(root, absPath)),
+      bytes: stat.size,
+      mtimeMs: stat.mtimeMs
+    };
+  } catch {
+    return null;
+  }
+}
+function walkSpecFiles(root, startRel) {
+  const start = path.join(root, startRel);
+  if (!fs.existsSync(start))
+    return [];
+  const artifacts = [];
+  const stack = [
+    { abs: start, depth: 0 }
+  ];
+  while (stack.length > 0 && artifacts.length < MAX_SPEC_FILES) {
+    const item = stack.pop();
+    if (!item || item.depth > MAX_WALK_DEPTH)
+      continue;
+    let entries;
+    try {
+      entries = fs.readdirSync(item.abs, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    const dirents = entries.filter((entry) => typeof entry?.name === "string");
+    for (const entry of dirents.sort((a, b) => b.name.localeCompare(a.name))) {
+      const abs = path.join(item.abs, entry.name);
+      if (entry.isSymbolicLink())
+        continue;
+      if (entry.isDirectory()) {
+        stack.push({ abs, depth: item.depth + 1 });
+      } else if (entry.isFile() && entry.name === "spec.md") {
+        const artifact = fileArtifact(root, abs);
+        if (artifact)
+          artifacts.push(artifact);
+        if (artifacts.length >= MAX_SPEC_FILES)
+          break;
+      }
+    }
+  }
+  return artifacts.sort((a, b) => a.relPath.localeCompare(b.relPath));
+}
+function listOpenSpecChanges(root) {
+  const changesDir = path.join(root, OPENSPEC_ROOT, "changes");
+  if (!fs.existsSync(changesDir))
+    return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(changesDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.filter((entry) => entry.isDirectory() && entry.name !== "archive").sort((a, b) => a.name.localeCompare(b.name)).map((entry) => {
+    const rel = path.join(OPENSPEC_ROOT, "changes", entry.name);
+    return {
+      id: entry.name,
+      proposal: fs.existsSync(path.join(root, rel, "proposal.md")),
+      design: fs.existsSync(path.join(root, rel, "design.md")),
+      tasks: fs.existsSync(path.join(root, rel, "tasks.md")),
+      specs: walkSpecFiles(root, path.join(rel, "specs"))
+    };
+  });
+}
+function detectKind(line, current) {
+  const upper = line.toUpperCase();
+  if (/^#{2,6}\s+ADDED\b/.test(upper))
+    return "ADDED";
+  if (/^#{2,6}\s+MODIFIED\b/.test(upper))
+    return "MODIFIED";
+  if (/^#{2,6}\s+REMOVED\b/.test(upper))
+    return "REMOVED";
+  return current;
+}
+function requirementTextFromBlock(title, block, kind) {
+  const joined = block.join(" ").replace(/\s+/g, " ").trim();
+  const obligation = joined.match(/\b(MUST|SHALL|SHOULD|MAY)\b/i)?.[1];
+  if (obligation)
+    return joined;
+  if (kind === "REMOVED") {
+    return `MAY remove or retire behavior for ${title}.`;
+  }
+  return `MUST satisfy OpenSpec requirement ${title}.`;
+}
+function parseRequirements(content, sourceRel, defaultKind) {
+  const requirements = [];
+  const lines = content.replace(/\r\n/g, `
+`).split(`
+`);
+  let kind = defaultKind;
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    kind = detectKind(line, kind);
+    const explicit = line.match(/\b(FR-(?!000)\d{3})\b/);
+    if (explicit && /\b(MUST|SHALL|SHOULD|MAY)\b/i.test(line)) {
+      requirements.push({
+        id: explicit[1].toUpperCase(),
+        kind,
+        title: explicit[1].toUpperCase(),
+        text: line.trim().replace(/^\s*[-*]\s*/, ""),
+        sourceRel
+      });
+      continue;
+    }
+    const openSpecReq = line.match(/^#{3,4}\s+Requirement:\s*(.+)$/i);
+    if (!openSpecReq)
+      continue;
+    const title = openSpecReq[1].trim();
+    const block = [];
+    for (let j = i + 1;j < lines.length; j++) {
+      if (/^##\s+/.test(lines[j]))
+        break;
+      if (/^#{3,4}\s+Requirement:/i.test(lines[j]))
+        break;
+      const trimmed = lines[j].trim();
+      if (trimmed)
+        block.push(trimmed);
+    }
+    const id = block.join(`
+`).match(/\b(FR-(?!000)\d{3})\b/)?.[1] ?? null;
+    requirements.push({
+      id: id?.toUpperCase() ?? null,
+      kind,
+      title,
+      text: requirementTextFromBlock(title, block, kind),
+      sourceRel
+    });
+  }
+  return requirements;
+}
+function nextFrId(used, warnings, reserved) {
+  for (let n = 1;n <= 999; n++) {
+    const id = `FR-${String(n).padStart(3, "0")}`;
+    if (!used.has(id) && !reserved?.has(id)) {
+      used.add(id);
+      return id;
+    }
+  }
+  warnings.push("More than 999 FR identifiers are required; reusing FR-999.");
+  return "FR-999";
+}
+function renderRequirement(req, used, warnings, reserved) {
+  const id = req.id && !used.has(req.id) ? req.id : nextFrId(used, warnings, reserved);
+  if (req.id && req.id !== id) {
+    warnings.push(`Duplicate requirement id ${req.id} in ${req.sourceRel}; generated ${id}.`);
+  }
+  if (req.id === id)
+    used.add(id);
+  let text = req.text;
+  if (!text.includes(id)) {
+    text = `${id}: ${text}`;
+  }
+  return `- ${text} _(source: ${req.sourceRel})_`;
+}
+function detectSpeckit(directory) {
+  const root = path.resolve(directory);
+  const markerPath = path.join(root, SPECKIT_MARKER);
+  const markerPresent = fs.statSync(markerPath, { throwIfNoEntry: false })?.isDirectory() ?? false;
+  if (!markerPresent) {
+    return { markerPresent: false, features: [] };
+  }
+  const specsRoot = path.join(root, SPECKIT_SPECS_DIR);
+  if (!fs.existsSync(specsRoot)) {
+    return { markerPresent: true, features: [] };
+  }
+  let entries;
+  try {
+    entries = fs.readdirSync(specsRoot, { withFileTypes: true });
+  } catch {
+    return { markerPresent: true, features: [] };
+  }
+  const featureDirs = entries.filter((entry) => typeof entry?.name === "string" && !entry.isSymbolicLink() && entry.isDirectory()).sort((a, b) => a.name.localeCompare(b.name));
+  const features = [];
+  for (const entry of featureDirs) {
+    if (features.length >= MAX_SPEC_FILES)
+      break;
+    const specAbs = path.join(specsRoot, entry.name, "spec.md");
+    let stat;
+    try {
+      stat = fs.lstatSync(specAbs);
+    } catch {
+      continue;
+    }
+    if (!stat.isFile() || stat.size > MAX_SOURCE_BYTES)
+      continue;
+    features.push({
+      featureId: entry.name,
+      specRelPath: toPosix(path.relative(root, specAbs))
+    });
+  }
+  return { markerPresent: true, features };
+}
+function parseSpeckitRequirements(content, sourceRel) {
+  const requirements = [];
+  const lines = content.replace(/\r\n/g, `
+`).split(`
+`);
+  let inFrSection = false;
+  for (const line of lines) {
+    if (/^##\s+/.test(line)) {
+      inFrSection = /^##\s+Functional Requirements\s*$/i.test(line);
+      continue;
+    }
+    if (!inFrSection)
+      continue;
+    if (!/^\s*[-*]\s+/.test(line))
+      continue;
+    if (!/\b(MUST|SHALL|SHOULD|MAY)\b/i.test(line))
+      continue;
+    const text = line.trim().replace(/^\s*[-*]\s+/, "");
+    const explicit = line.match(/\b(FR-(?!000)\d{3})\b/);
+    if (explicit) {
+      requirements.push({
+        id: explicit[1].toUpperCase(),
+        kind: "CURRENT",
+        title: explicit[1].toUpperCase(),
+        text,
+        sourceRel
+      });
+      continue;
+    }
+    requirements.push({
+      id: null,
+      kind: "CURRENT",
+      title: text,
+      text,
+      sourceRel
+    });
+  }
+  return requirements;
+}
+function resolveSpeckitProjection(directory, options = {}) {
+  const root = path.resolve(directory);
+  const detection = detectSpeckit(root);
+  if (!detection.markerPresent) {
+    return { kind: "not_speckit" };
+  }
+  if (detection.features.length === 0) {
+    return { kind: "empty" };
+  }
+  let selectedFeature;
+  if (options.feature) {
+    const found = detection.features.find((f) => f.featureId === options.feature);
+    if (!found) {
+      return {
+        kind: "unknown_feature",
+        feature: options.feature,
+        available: detection.features.map((f) => f.featureId)
+      };
+    }
+    selectedFeature = found;
+  } else if (detection.features.length === 1) {
+    selectedFeature = detection.features[0];
+  } else {
+    return {
+      kind: "ambiguous",
+      features: detection.features.map((f) => f.featureId)
+    };
+  }
+  const specAbs = path.join(root, selectedFeature.specRelPath);
+  const content = readTextBounded(specAbs);
+  if (content === null) {
+    return { kind: "zero_requirements", feature: selectedFeature.featureId };
+  }
+  const warnings = [];
+  const usedIds = new Set;
+  const requirements = parseSpeckitRequirements(content, selectedFeature.specRelPath);
+  if (requirements.length === 0) {
+    return { kind: "zero_requirements", feature: selectedFeature.featureId };
+  }
+  const reservedIds = new Set;
+  for (const req of requirements) {
+    if (req.id)
+      reservedIds.add(req.id);
+  }
+  let mtimeMs = 0;
+  try {
+    mtimeMs = fs.lstatSync(specAbs).mtimeMs;
+  } catch {}
+  const lines = [
+    "# Specification: Effective SDD Projection",
+    "",
+    "Generated from Spec-Kit feature artifacts. Update the source artifacts, then run `/swarm sdd project` to refresh this projection.",
+    "",
+    "## Source Artifacts",
+    `- ${selectedFeature.specRelPath}`,
+    "",
+    "## Functional Requirements"
+  ];
+  for (const req of requirements) {
+    lines.push(renderRequirement(req, usedIds, warnings, reservedIds));
+  }
+  const projected = `${lines.join(`
+`)}
+`;
+  if (projected.length > MAX_SPEC_BYTES) {
+    return {
+      kind: "too_large",
+      feature: selectedFeature.featureId,
+      bytes: projected.length
+    };
+  }
+  const validation = validateSpecContent(projected);
+  if (!validation.valid) {
+    warnings.push(...validation.issues.map((issue) => `Projection line ${issue.line}: ${issue.message}`));
+  }
+  const spec = {
+    source: "speckit_projection",
+    content: projected,
+    hash: hash(projected),
+    mtime: mtimeMs > 0 ? new Date(mtimeMs).toISOString() : null,
+    sourcePaths: [selectedFeature.specRelPath],
+    warnings
+  };
+  return { kind: "ok", spec, feature: selectedFeature.featureId };
+}
+function buildSpeckitProjectionSync(directory, options = {}) {
+  const resolution = resolveSpeckitProjection(directory, options);
+  return resolution.kind === "ok" ? resolution.spec : null;
+}
+function loadSddStatusSync(directory, opts) {
+  const root = path.resolve(directory);
+  const swSpecPath = path.join(root, SWARM_SPEC_REL);
+  const openSpecPath = path.join(root, OPENSPEC_ROOT);
+  const errors = [];
+  const warnings = [];
+  const swSpecExists = fs.existsSync(swSpecPath);
+  const openSpecExists = fs.existsSync(openSpecPath);
+  const currentSpecs = walkSpecFiles(root, path.join(OPENSPEC_ROOT, "specs"));
+  const changes = listOpenSpecChanges(root);
+  const effectiveSpec = readEffectiveSpecSync(root, opts);
+  if (openSpecExists && currentSpecs.length === 0 && changes.length === 0) {
+    errors.push("openspec/ exists but contains no specs or active changes.");
+  }
+  for (const change of changes) {
+    if (!change.proposal) {
+      warnings.push(`Change ${change.id} is missing proposal.md.`);
+    }
+    if (!change.tasks) {
+      warnings.push(`Change ${change.id} is missing tasks.md; tasks remain proposal input, not plan state.`);
+    }
+    if (change.specs.length === 0) {
+      errors.push(`Change ${change.id} has no specs/**/spec.md delta files.`);
+    }
+  }
+  return {
+    provider: effectiveSpec?.source ?? "none",
+    swSpecExists,
+    openSpecExists,
+    currentSpecs,
+    changes,
+    effectiveSpec,
+    errors,
+    warnings
+  };
+}
+function buildOpenSpecProjectionSync(directory, options = {}) {
+  const root = path.resolve(directory);
+  const currentSpecs = walkSpecFiles(root, path.join(OPENSPEC_ROOT, "specs"));
+  const allChanges = listOpenSpecChanges(root);
+  const changes = options.changeId ? allChanges.filter((change) => change.id === options.changeId) : allChanges;
+  const sourcePaths = [];
+  const warnings = [];
+  const usedIds = new Set;
+  const currentRequirements = [];
+  const changeRequirements = new Map;
+  let parsedRequirementCount = 0;
+  let mtimeMs = 0;
+  if (options.changeId && changes.length === 0)
+    return null;
+  if (currentSpecs.length === 0 && changes.length === 0)
+    return null;
+  for (const artifact of currentSpecs) {
+    const abs = path.join(root, artifact.relPath);
+    const content2 = readTextBounded(abs);
+    if (content2 === null) {
+      warnings.push(`Skipped unreadable or oversized spec ${artifact.relPath}.`);
+      continue;
+    }
+    sourcePaths.push(artifact.relPath);
+    mtimeMs = Math.max(mtimeMs, artifact.mtimeMs);
+    const parsed = parseRequirements(content2, artifact.relPath, "CURRENT");
+    currentRequirements.push(...parsed);
+    parsedRequirementCount += parsed.length;
+  }
+  for (const change of changes) {
+    const reqs = [];
+    for (const artifact of change.specs) {
+      const abs = path.join(root, artifact.relPath);
+      const content2 = readTextBounded(abs);
+      if (content2 === null) {
+        warnings.push(`Skipped unreadable or oversized spec ${artifact.relPath}.`);
+        continue;
+      }
+      sourcePaths.push(artifact.relPath);
+      mtimeMs = Math.max(mtimeMs, artifact.mtimeMs);
+      const parsed = parseRequirements(content2, artifact.relPath, "ADDED");
+      reqs.push(...parsed);
+      parsedRequirementCount += parsed.length;
+    }
+    changeRequirements.set(change.id, reqs);
+  }
+  if (sourcePaths.length > 0 && parsedRequirementCount === 0) {
+    return null;
+  }
+  const lines = [
+    "# Specification: Effective SDD Projection",
+    "",
+    "Generated from OpenSpec-compatible artifacts. Update the source artifacts, then run `/swarm sdd project` to refresh this projection.",
+    "",
+    "## Source Artifacts",
+    ...sourcePaths.map((rel) => `- ${rel}`),
+    "",
+    "## Current Requirements"
+  ];
+  if (currentRequirements.length === 0) {
+    lines.push("- No current OpenSpec requirements found in source artifacts.");
+    warnings.push("No current requirements found; projection includes an advisory note only.");
+  } else {
+    for (const req of currentRequirements) {
+      lines.push(renderRequirement(req, usedIds, warnings));
+    }
+  }
+  for (const [changeId, reqs] of changeRequirements.entries()) {
+    lines.push("", `## Pending Change: ${changeId}`);
+    if (reqs.length === 0) {
+      lines.push(`- ${nextFrId(usedIds, warnings)} SHOULD add OpenSpec delta requirements for change ${changeId}.`);
+      warnings.push(`Change ${changeId} contains no parsable requirements.`);
+      continue;
+    }
+    for (const req of reqs) {
+      lines.push(renderRequirement(req, usedIds, warnings));
+    }
+  }
+  const content = `${lines.join(`
+`)}
+`;
+  if (content.length > MAX_SPEC_BYTES) {
+    warnings.push(`Projected spec exceeds ${MAX_SPEC_BYTES} bytes; refusing to use projection.`);
+    return null;
+  }
+  const validation = validateSpecContent(content);
+  if (!validation.valid) {
+    warnings.push(...validation.issues.map((issue) => `Projection line ${issue.line}: ${issue.message}`));
+  }
+  return {
+    source: "openspec_projection",
+    content,
+    hash: hash(content),
+    mtime: mtimeMs > 0 ? new Date(mtimeMs).toISOString() : null,
+    sourcePaths,
+    warnings
+  };
+}
+function readEffectiveSpecSync(directory, opts) {
+  const root = path.resolve(directory);
+  const swSpecPath = path.join(root, SWARM_SPEC_REL);
+  try {
+    const stat = fs.lstatSync(swSpecPath);
+    if (stat.isFile() && stat.size <= MAX_SPEC_BYTES) {
+      const content = fs.readFileSync(swSpecPath, "utf-8");
+      return {
+        source: "swarm",
+        content,
+        hash: hash(content),
+        mtime: stat.mtime.toISOString(),
+        sourcePaths: [toPosix(SWARM_SPEC_REL)],
+        warnings: []
+      };
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+  if (opts?.source) {
+    switch (opts.source) {
+      case "openspec":
+        return buildOpenSpecProjectionSync(root);
+      case "speckit":
+        return buildSpeckitProjectionSync(root, { feature: opts.feature });
+      case "swarm":
+        return null;
+    }
+  }
+  const speckitDetection = detectSpeckit(root);
+  if (!speckitDetection.markerPresent) {
+    return buildOpenSpecProjectionSync(root);
+  }
+  const speckitPresent = speckitDetection.features.length > 0;
+  if (!speckitPresent) {
+    return buildOpenSpecProjectionSync(root);
+  }
+  const openspecProjection = buildOpenSpecProjectionSync(root);
+  const openspecPresent = openspecProjection !== null;
+  if (openspecPresent) {
+    console.warn("[opencode-swarm] Multiple SDD sources detected (openspec and speckit). " + "Enforcement/projection is suppressed until you disambiguate. " + "Pass --source openspec or --source speckit to select a provider.");
+    return null;
+  }
+  return buildSpeckitProjectionSync(root, { feature: opts?.feature });
+}
+function writeProjectedSpecSync(directory, options = {}) {
+  const root = path.resolve(directory);
+  const projection = options.source === "speckit" ? buildSpeckitProjectionSync(root, { feature: options.feature }) : buildOpenSpecProjectionSync(root, { changeId: options.changeId });
+  const target = path.join(root, SWARM_SPEC_REL);
+  if (!projection || options.dryRun) {
+    return { written: false, projection, path: target };
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  let archivePath;
+  if (fs.existsSync(target)) {
+    const prior = fs.readFileSync(target, "utf-8");
+    if (prior !== projection.content) {
+      const archiveDir = path.join(root, ".swarm", "spec-archive");
+      fs.mkdirSync(archiveDir, { recursive: true });
+      const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+      archivePath = path.join(archiveDir, `sdd-projection-${stamp}.md`);
+      fs.writeFileSync(archivePath, prior, "utf-8");
+    }
+  }
+  const tmp = `${target}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tmp, projection.content, "utf-8");
+  fs.renameSync(tmp, target);
+  return { written: true, projection, archivePath, path: target };
+}
+function validateSpeckit(directory, options = {}) {
+  const root = path.resolve(directory);
+  const resolution = resolveSpeckitProjection(root, options);
+  const problems = [];
+  if (resolution.kind !== "ok" && resolution.kind !== "zero_requirements") {
+    return { resolution, problems };
+  }
+  if (resolution.kind === "zero_requirements") {
+    problems.push(`Feature '${resolution.feature}' contains no parsable functional requirements.`);
+  }
+  const detection = detectSpeckit(root);
+  const featureEntry = detection.features.find((f) => f.featureId === resolution.feature);
+  if (!featureEntry) {
+    return { resolution, problems };
+  }
+  const specAbs = path.join(root, featureEntry.specRelPath);
+  let specContent = null;
+  try {
+    specContent = readTextBounded(specAbs);
+  } catch {}
+  if (specContent !== null) {
+    const specLines = specContent.replace(/\r\n/g, `
+`).split(`
+`);
+    for (const requiredHeader of SPECKIT_REQUIRED_SECTIONS) {
+      if (!specLines.some((line) => line.trimEnd() === requiredHeader)) {
+        problems.push(`Missing required spec.md section: ${requiredHeader}`);
+      }
+    }
+  }
+  const tasksAbs = path.join(path.dirname(specAbs), "tasks.md");
+  let tasksContent = null;
+  try {
+    tasksContent = readTextBounded(tasksAbs);
+  } catch {}
+  if (tasksContent !== null) {
+    const tasksLines = tasksContent.replace(/\r\n/g, `
+`).split(`
+`);
+    for (const line of tasksLines) {
+      const taskMatch = line.match(/^\s*-\s+\[[ xX]\]\s+(T\d+)/);
+      if (!taskMatch)
+        continue;
+      const taskId = taskMatch[1];
+      const hasStoryRef = /\[US\d+\]/i.test(line);
+      const hasReqRef = /\bFR-(?!000)\d{3}\b/i.test(line);
+      if (!hasStoryRef && !hasReqRef) {
+        problems.push(`Task ${taskId} has no spec/requirement reference.`);
+      }
+    }
+  }
+  return { resolution, problems };
+}
+
+export { detectSpeckit, resolveSpeckitProjection, loadSddStatusSync, buildOpenSpecProjectionSync, readEffectiveSpecSync, writeProjectedSpecSync, validateSpeckit };