triad-plus 1.7.0 → 1.9.0

package/runtime/lib/quality-baseline.mjs

@@ -0,0 +1,205 @@
+import { createHash } from "node:crypto";
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+
+const SHA256 = /^[a-f0-9]{64}$/i;
+const QUALITY_SCOPES = new Set(["product_quality", "delivery_closure"]);
+
+function qualityError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function objectLike(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Return a JSON-compatible value with object keys sorted recursively. Arrays
+ * intentionally retain their declared order: source and criterion order is
+ * part of the authored contract, while object formatting is not.
+ */
+export function canonicalizeQualityValue(value) {
+  if (Array.isArray(value)) return value.map(canonicalizeQualityValue);
+  if (!objectLike(value)) return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .sort()
+      .map((key) => [key, canonicalizeQualityValue(value[key])])
+  );
+}
+
+export function qualityBaselinePayload(manifest) {
+  if (!objectLike(manifest)) return manifest;
+  const { fingerprint: _fingerprint, ...payload } = manifest;
+  return canonicalizeQualityValue(payload);
+}
+
+export function qualityBaselineFingerprint(manifest) {
+  const canonical = JSON.stringify(qualityBaselinePayload(manifest));
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+function projectRelativePath(root, value, label) {
+  if (typeof value !== "string" || !value.trim() || path.isAbsolute(value)) {
+    throw qualityError("quality_baseline_invalid", `${label} must be a non-empty project-relative path`);
+  }
+  const normalized = value.replaceAll("\\", "/");
+  const posix = path.posix.normalize(normalized);
+  if (posix === "." || posix === ".." || posix.startsWith("../") || normalized.split("/").includes("..")) {
+    throw qualityError("quality_baseline_invalid", `${label} escapes the project root`);
+  }
+  const resolved = path.resolve(root, normalized);
+  if (!resolved.startsWith(`${root}${path.sep}`)) {
+    throw qualityError("quality_baseline_invalid", `${label} escapes the project root`);
+  }
+  return resolved;
+}
+
+function validateSha(value, label) {
+  if (typeof value !== "string" || !SHA256.test(value)) {
+    throw qualityError("quality_baseline_invalid", `${label} must be a SHA-256 hex digest`);
+  }
+}
+
+function rejectUnknownProperties(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw qualityError("quality_baseline_invalid", `${label} contains unknown property: ${key}`);
+  }
+}
+
+/**
+ * Validate the manifest shape and its self-declared fingerprint without
+ * touching source files. This is useful to callers that only need to inspect
+ * the immutable contract before resolving it against a project.
+ */
+export function validateQualityBaselineManifest(manifest) {
+  if (!objectLike(manifest)) throw qualityError("quality_baseline_invalid", "quality baseline must be a JSON object");
+  rejectUnknownProperties(manifest, new Set(["schema_version", "id", "revision", "sources", "criteria", "fingerprint"]), "quality baseline manifest");
+  if (manifest.schema_version !== 1) throw qualityError("quality_baseline_invalid", "quality baseline schema_version must be 1");
+  if (typeof manifest.id !== "string" || !manifest.id.trim()) throw qualityError("quality_baseline_invalid", "quality baseline id must be non-empty");
+  if (!Number.isInteger(manifest.revision) || manifest.revision < 1) throw qualityError("quality_baseline_invalid", "quality baseline revision must be a positive integer");
+  if (!Array.isArray(manifest.sources) || manifest.sources.length === 0) throw qualityError("quality_baseline_invalid", "quality baseline must declare at least one source");
+  if (!Array.isArray(manifest.criteria)) throw qualityError("quality_baseline_invalid", "quality baseline criteria must be an array");
+
+  const sourceIds = new Set();
+  for (const source of manifest.sources) {
+    if (!objectLike(source)) throw qualityError("quality_baseline_invalid", "quality baseline sources must contain objects");
+    rejectUnknownProperties(source, new Set(["id", "role", "path", "sha256"]), "quality baseline source");
+    if (typeof source.id !== "string" || !source.id.trim()) throw qualityError("quality_baseline_invalid", "quality baseline source id must be non-empty");
+    if (sourceIds.has(source.id)) throw qualityError("quality_baseline_invalid", `duplicate quality baseline source id: ${source.id}`);
+    sourceIds.add(source.id);
+    if (typeof source.role !== "string" || !source.role.trim()) throw qualityError("quality_baseline_invalid", `quality baseline source role is missing: ${source.id}`);
+    if (typeof source.path !== "string" || !source.path.trim() || path.isAbsolute(source.path)) throw qualityError("quality_baseline_invalid", `quality baseline source path must be project-relative: ${source.id}`);
+    const normalizedSourcePath = path.posix.normalize(source.path.replaceAll("\\", "/"));
+    if (normalizedSourcePath === "." || normalizedSourcePath === ".." || normalizedSourcePath.startsWith("../") || source.path.replaceAll("\\", "/").split("/").includes("..")) throw qualityError("quality_baseline_invalid", `quality baseline source path escapes the project root: ${source.id}`);
+    validateSha(source.sha256, `quality baseline source ${source.id}`);
+  }
+
+  const criterionIds = new Set();
+  for (const criterion of manifest.criteria) {
+    if (!objectLike(criterion)) throw qualityError("quality_baseline_invalid", "quality baseline criteria must contain objects");
+    rejectUnknownProperties(criterion, new Set(["id", "scope", "requirement"]), "quality baseline criterion");
+    if (typeof criterion.id !== "string" || !criterion.id.trim()) throw qualityError("quality_baseline_invalid", "quality baseline criterion id must be non-empty");
+    if (criterionIds.has(criterion.id)) throw qualityError("quality_baseline_invalid", `duplicate quality baseline criterion id: ${criterion.id}`);
+    criterionIds.add(criterion.id);
+    if (!QUALITY_SCOPES.has(criterion.scope)) throw qualityError("quality_baseline_invalid", `invalid quality baseline criterion scope: ${criterion.id}`);
+    if (typeof criterion.requirement !== "string" || !criterion.requirement.trim()) throw qualityError("quality_baseline_invalid", `quality baseline criterion requirement must be non-empty: ${criterion.id}`);
+  }
+
+  validateSha(manifest.fingerprint, "quality baseline fingerprint");
+  const calculatedFingerprint = qualityBaselineFingerprint(manifest);
+  if (manifest.fingerprint.toLowerCase() !== calculatedFingerprint) {
+    throw qualityError("quality_baseline_invalid", "quality baseline declared fingerprint does not match its canonical content");
+  }
+  return { manifest, fingerprint: calculatedFingerprint };
+}
+
+async function verifySources(manifest, root) {
+  const verifiedSources = [];
+  for (const source of manifest.sources) {
+    const sourcePath = projectRelativePath(root, source.path, `quality baseline source ${source.id}`);
+    let resolvedSource;
+    try {
+      resolvedSource = await realpath(sourcePath);
+    } catch {
+      throw qualityError("quality_baseline_invalid", `quality baseline source is missing: ${source.path}`);
+    }
+    if (!resolvedSource.startsWith(`${root}${path.sep}`)) {
+      throw qualityError("quality_baseline_invalid", `quality baseline source escapes the project root: ${source.path}`);
+    }
+    let content;
+    try {
+      content = await readFile(resolvedSource);
+    } catch {
+      throw qualityError("quality_baseline_invalid", `quality baseline source cannot be read: ${source.path}`);
+    }
+    const actual = createHash("sha256").update(content).digest("hex");
+    if (actual !== source.sha256.toLowerCase()) {
+      throw qualityError("quality_baseline_drift", `quality baseline source hash mismatch: ${source.path}`);
+    }
+    verifiedSources.push({ id: source.id, path: source.path, sha256: actual });
+  }
+  return verifiedSources;
+}
+
+/**
+ * Load, validate, fingerprint, and resolve the immutable quality contract
+ * against source files under the project root.
+ */
+export async function loadQualityBaseline(manifestPath, { projectRoot = process.cwd(), expectedFingerprint = null } = {}) {
+  const root = await realpath(projectRoot);
+  const resolvedManifestPath = projectRelativePath(root, manifestPath, "quality baseline path");
+  let source;
+  try {
+    source = await readFile(resolvedManifestPath, "utf8");
+  } catch {
+    throw qualityError("quality_baseline_invalid", `quality baseline manifest is missing: ${manifestPath}`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(source);
+  } catch (error) {
+    throw qualityError("quality_baseline_invalid", `quality baseline manifest is not valid JSON: ${error.message}`);
+  }
+  const validated = validateQualityBaselineManifest(manifest);
+  if (expectedFingerprint !== null && expectedFingerprint !== undefined) {
+    validateSha(expectedFingerprint, "expected quality baseline fingerprint");
+    if (expectedFingerprint.toLowerCase() !== validated.fingerprint) {
+      throw qualityError("quality_baseline_drift", "quality baseline fingerprint does not match the assignment binding");
+    }
+  }
+  const sources = await verifySources(manifest, root);
+  return {
+    manifest,
+    path: path.relative(root, resolvedManifestPath),
+    fingerprint: validated.fingerprint,
+    sources,
+    criteria: manifest.criteria,
+  };
+}
+
+/** Resolve the optional assignment binding while preserving legacy mode. */
+export async function resolveQualityContract(assignment, projectRoot) {
+  const manifestPath = assignment?.quality_baseline_path;
+  const expectedFingerprint = assignment?.expected_quality_baseline_fingerprint;
+  const pathPresent = typeof manifestPath === "string" && manifestPath.trim();
+  const fingerprintPresent = typeof expectedFingerprint === "string" && expectedFingerprint.trim();
+  if (!pathPresent && !fingerprintPresent) return null;
+  if (!pathPresent || !fingerprintPresent) {
+    throw qualityError("quality_baseline_invalid", "quality contract requires quality_baseline_path and expected_quality_baseline_fingerprint together");
+  }
+  return loadQualityBaseline(manifestPath, { projectRoot, expectedFingerprint });
+}
+
+export function qualityCriteriaByScope(manifestOrContract) {
+  const manifest = manifestOrContract?.manifest ?? manifestOrContract;
+  if (!objectLike(manifest) || !Array.isArray(manifest.criteria)) throw qualityError("quality_baseline_invalid", "quality baseline criteria are unavailable");
+  return {
+    product_quality: manifest.criteria.filter((criterion) => criterion.scope === "product_quality"),
+    delivery_closure: manifest.criteria.filter((criterion) => criterion.scope === "delivery_closure"),
+  };
+}
+
+export { QUALITY_SCOPES };

package/runtime/triad-assignment-packet.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeAssignmentPacket } from "./lib/assignment-packet.mjs";
+
+function option(argv, name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : null;
+}
+
+function usage() {
+  process.stderr.write(`Usage: node .triad-runtime/triad-assignment-packet.mjs --project <control-workspace> --assignment <assignment.json> [--output <packet.md>]\n`);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--help") || argv.includes("-h")) {
+    usage();
+    return;
+  }
+  const project = option(argv, "--project") ?? process.cwd();
+  const assignmentOption = option(argv, "--assignment");
+  if (!assignmentOption) throw Object.assign(new Error("--assignment is required"), { code: "assignment_packet_invalid" });
+  const projectRoot = path.resolve(project);
+  const assignmentPath = path.resolve(projectRoot, assignmentOption);
+  const assignment = JSON.parse(await readFile(assignmentPath, "utf8"));
+  const output = option(argv, "--output");
+  const result = await writeAssignmentPacket(assignment, {
+    projectRoot,
+    assignmentPath,
+    packetPath: output ? path.resolve(projectRoot, output) : null,
+  });
+  process.stdout.write(`${JSON.stringify({
+    status: "ready",
+    assignment: {
+      id: result.assignment.assignment_id,
+      feature_id: result.assignment.feature_id,
+      attempt: result.assignment.attempt,
+    },
+    packet_path: result.assignment.assignment_packet_path,
+    packet_absolute_path: result.packetPath,
+    packet_sha256: result.sha256,
+    dispatch: {
+      cwd: result.context.cwd,
+      control_workspace: result.context.controlWorkspace,
+      repository: result.context.repository,
+      branch: result.context.branch,
+      card_path: result.assignment.card_path,
+      packet_path: result.assignment.assignment_packet_path,
+      mandatory_skill_paths: result.context.requiredSkills.map((skill) => skill.path),
+    },
+  })}\n`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.code ? `${error.code}: ` : ""}${error.message}\n`);
+    process.exitCode = 2;
+  });
+}

package/runtime/triad-bmad-intake.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+import { access } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const runtimeDirectory = path.dirname(fileURLToPath(import.meta.url));
+
+async function loadIntegration() {
+  const candidates = [
+    path.join(runtimeDirectory, 'integrations', 'bmad', 'epics-parser.mjs'),
+    path.resolve(runtimeDirectory, '..', 'integrations', 'bmad', 'epics-parser.mjs')
+  ];
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return import(pathToFileURL(candidate).href);
+    } catch {}
+  }
+  throw new Error('BMAD native intake assets are not installed');
+}
+
+function option(argv, name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : null;
+}
+
+function repeated(argv, name) {
+  const values = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] !== name) continue;
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${name} requires a value`);
+    values.push(value);
+    index += 1;
+  }
+  return values;
+}
+
+function usage() {
+  process.stderr.write(`Native BMAD epics.md intake (integration/automation API)
+
+Usage:
+  node .triad-runtime/triad-bmad-intake.mjs --source <epics.md>
+  node .triad-runtime/triad-bmad-intake.mjs --source <epics.md> --project <control> --output <features-dir> [--repository <id>] [--required-gate <story-id>=<gate-id>] [--depends-on <story-id>=<card-id>]
+
+Without --output the command performs read-only ingestion and prints canonical
+Stories. With --output it resolves Triad execution readiness and writes normal
+Cards plus integration-side provenance. This command is an internal
+deterministic primitive; the normal user entry point is the host's /triad
+workflow with the epics.md path.
+`);
+}
+
+function keyed(values, label) {
+  const result = {};
+  for (const value of values) {
+    const separator = value.indexOf('=');
+    if (separator <= 0 || separator === value.length - 1) throw new Error(`${label} must use STORY-ID=VALUE`);
+    const storyId = value.slice(0, separator).trim();
+    const item = value.slice(separator + 1).trim();
+    if (!storyId || !item) throw new Error(`${label} must use STORY-ID=VALUE`);
+    (result[storyId] ??= []).push(item);
+  }
+  return result;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help') || argv.includes('-h')) {
+    usage();
+    return;
+  }
+  const source = option(argv, '--source');
+  if (!source) throw new Error('--source is required');
+  const output = option(argv, '--output');
+  const project = option(argv, '--project');
+  const repository = option(argv, '--repository');
+  const requiredGatesByStory = keyed(repeated(argv, '--required-gate'), '--required-gate');
+  const dependsOnByStory = keyed(repeated(argv, '--depends-on'), '--depends-on');
+  const { ingestBmadEpics, writeImportedEpics } = await loadIntegration();
+  if (output && !project) throw new Error('--project is required when --output is supplied');
+  const options = {
+    sourcePath: source,
+    projectRoot: project,
+    targetRepository: repository,
+    requiredGatesByStory,
+    dependsOnByStory
+  };
+  if (output) {
+    const result = await writeImportedEpics({ ...options, outputDirectory: output });
+    process.stdout.write(`${JSON.stringify({
+      status: 'ready',
+      source_kind: result.source_kind,
+      source_path: result.source_path,
+      source_sha256: result.source_sha256,
+      epic_count: result.epics.length,
+      story_count: result.stories.length,
+      card_count: result.outputs.length,
+      cards: result.outputs.map(({ story, cardPath, provenancePath, provenance }) => ({
+        story_id: story.id,
+        epic_id: story.epicId,
+        card_path: cardPath,
+        provenance_path: provenancePath,
+        card_sha256: provenance.card_sha256
+      }))
+    })}\n`);
+    return;
+  }
+  const result = await ingestBmadEpics(options);
+  process.stdout.write(`${JSON.stringify({
+    status: 'ingested',
+    source_kind: result.source_kind,
+    source_path: result.source_path,
+    source_sha256: result.source_sha256,
+    epic_count: result.epics.length,
+    story_count: result.stories.length,
+    stories: result.stories.map((story) => ({
+      epic_id: story.epicId,
+      epic_title: story.epicTitle,
+      story_id: story.id,
+      title: story.title,
+      status: story.status,
+      ingestion_ready: story.ingestionReady,
+      execution_ready: story.executionReady,
+      source_heading: story.sourceHeading,
+      source_range: story.sourceRange
+    }))
+  })}\n`);
+}
+
+// `mktemp`/system temporary roots on macOS are commonly reached through the
+// `/var` -> `/private/var` symlink.  Compare canonical paths so the installed
+// runtime CLI still runs when invoked from such a control workspace.
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main().catch((error) => {
+    process.stderr.write(`${error.code ? `${error.code}: ` : ''}${error.message}\n`);
+    process.exitCode = 2;
+  });
+}