@jstn-sdk/ma 0.1.12 → 0.1.13

package/src/runtime/learning-loop-core.js

@@ -0,0 +1,238 @@
+import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const learningLoopCoreSchemaVersion = "0.1.0";
+
+export const learningLoopDomains = [
+  "core_orchestration",
+  "memory_knowledge",
+  "intelligence_learning",
+  "code_quality_testing",
+  "security_compliance",
+  "architecture_methodology",
+  "devops_observability",
+  "extensibility",
+  "domain_specific",
+];
+
+export function getLearningLoopCorePath() {
+  return getRuntimeSubsystemPath("context", "learning-loop-core.json");
+}
+
+export function createDefaultLearningLoopCore() {
+  return {
+    schemaVersion: learningLoopCoreSchemaVersion,
+    product: "Meta-Architect",
+    purpose:
+      "First-party learning loop that turns verified workspace outcomes into durable, lane-aware improvements over time.",
+    loop: {
+      cadence: "every_verified_workflow_or_release_gate",
+      sequence: [
+        "observe_runtime_outcome",
+        "classify_learning_domain",
+        "record_semantic_receipt",
+        "promote_verified_learning",
+        "apply_to_next_run",
+        "verify_effectiveness_delta",
+      ],
+      fail_closed_rule:
+        "Unverified observations stay as candidate learnings and must not change gates, release state, or durable policy.",
+    },
+    domains: [
+      {
+        id: "core_orchestration",
+        label: "Core & Orchestration",
+        learns_from: ["maestro_runs", "lane_handoffs", "manager_events"],
+        writes_to: [".ma/state/manager-runs.json", ".ma/context/workspace-effectiveness.json"],
+        promotion_gate: "handoff_replay_or_release_check_passed",
+      },
+      {
+        id: "memory_knowledge",
+        label: "Memory & Knowledge",
+        learns_from: ["memory_notes", "obsidian_vault_context", "semantic_receipts"],
+        writes_to: [".ma/memory/notes.md", ".ma/memory/index.json", ".ma/context/project.md"],
+        promotion_gate: "source_provenance_and_authority_boundary_verified",
+      },
+      {
+        id: "intelligence_learning",
+        label: "Intelligence & Learning",
+        learns_from: ["prompt_strategy_results", "context_budget_outcomes", "rehearsal_traces"],
+        writes_to: [".ma/context/prompt-strategy-core.json", ".ma/context/learning-loop-core.json"],
+        promotion_gate: "strategy_result_has_verification_delta",
+      },
+      {
+        id: "code_quality_testing",
+        label: "Code Quality & Testing",
+        learns_from: ["test_failures", "lint_results", "build_results", "ralph_progress"],
+        writes_to: [".ma/specs/logic.md", ".ma/plans/build.md"],
+        promotion_gate: "fresh_test_or_build_evidence_passed",
+      },
+      {
+        id: "security_compliance",
+        label: "Security & Compliance",
+        learns_from: ["vet_findings", "exposure_catalog", "redaction_receipts"],
+        writes_to: [".ma/specs/security.md", ".ma/evidence/audits.json"],
+        promotion_gate: "security_review_passed_or_blocker_preserved",
+      },
+      {
+        id: "architecture_methodology",
+        label: "Architecture & Methodology",
+        learns_from: ["architecture_decisions", "methodology_reviews", "tradeoff_outcomes"],
+        writes_to: [".ma/specs/architecture.md", ".ma/decisions.json"],
+        promotion_gate: "architecture_review_accepts_reusable_pattern",
+      },
+      {
+        id: "devops_observability",
+        label: "DevOps & Observability",
+        learns_from: ["release_checks", "package_smokes", "runtime_traces", "hook_audits"],
+        writes_to: [".ma/runbook.md", ".ma/logs/", ".ma/hooks/audit.log"],
+        promotion_gate: "release_or_smoke_gate_passed",
+      },
+      {
+        id: "extensibility",
+        label: "Extensibility",
+        learns_from: ["skill_exports", "plugin_installs", "mcp_policy_results", "host_payloads"],
+        writes_to: [".ma/context/skills-registry-export.json", "mcp/servers.json"],
+        promotion_gate: "compatibility_matrix_verified",
+      },
+      {
+        id: "domain_specific",
+        label: "Domain-Specific",
+        learns_from: ["workspace_stack", "project_domain_notes", "trusted_sources"],
+        writes_to: [
+          ".ma/context/workspace-context-pack.json",
+          ".ma/evidence/semantic-receipts.json",
+        ],
+        promotion_gate: "domain_claim_has_source_or_user_authority",
+      },
+    ],
+    learning_record_schema: {
+      domain: "one_of_learningLoopDomains",
+      claim: "string",
+      source: "path_or_runtime_surface",
+      evidence: ["path_or_command_or_receipt"],
+      status: "candidate | verified | rejected | superseded",
+      applies_to: ["agent_or_role_or_lane"],
+      cannot_mutate: ["release_state_without_owning_lane", "source_evidence", "security_boundary"],
+      next_verification: "string",
+    },
+    hard_rules: [
+      "Learning records require domain, claim, source, evidence, status, applies_to, and next_verification.",
+      "Candidate learnings can inform context but cannot mutate gates, release state, or durable policy.",
+      "Verified learnings must preserve lane authority and semantic channel boundaries.",
+      "Obsidian and memory context can inform planning but do not become build evidence without owning-lane promotion.",
+      "Security, compliance, redaction, and irreversible-action warnings must not be compressed or auto-promoted.",
+    ],
+    records: [],
+  };
+}
+
+export function validateLearningLoopCore(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("learning loop core must be an object");
+  }
+  if (value.schemaVersion !== learningLoopCoreSchemaVersion) {
+    throw new Error(`Unsupported learning loop core schemaVersion: ${value.schemaVersion}`);
+  }
+  if (!Array.isArray(value.domains) || value.domains.length !== learningLoopDomains.length) {
+    throw new Error("learning loop core must include every required learning domain");
+  }
+  const ids = new Set(value.domains.map((domain) => domain.id));
+  for (const required of learningLoopDomains) {
+    if (!ids.has(required)) {
+      throw new Error(`learning loop core missing domain: ${required}`);
+    }
+  }
+  for (const domain of value.domains) {
+    if (
+      typeof domain.label !== "string" ||
+      !Array.isArray(domain.learns_from) ||
+      !Array.isArray(domain.writes_to) ||
+      typeof domain.promotion_gate !== "string"
+    ) {
+      throw new Error(
+        "learning loop domains require label, learns_from, writes_to, and promotion_gate",
+      );
+    }
+  }
+  if (!Array.isArray(value.records)) {
+    throw new Error("learning loop core requires records array");
+  }
+  if (JSON.stringify(value).includes(".omx")) {
+    throw new Error("learning loop core must not expose OMX runtime paths");
+  }
+  return value;
+}
+
+export function createLearningRecord({
+  domain,
+  claim,
+  source,
+  evidence = [],
+  status = "candidate",
+  appliesTo = ["all_applicable_agents", "all_applicable_roles"],
+  nextVerification,
+}) {
+  if (!learningLoopDomains.includes(domain)) {
+    throw new Error(`Unsupported learning domain: ${domain}`);
+  }
+  if (!claim || !source || !nextVerification) {
+    throw new Error("Learning record requires domain, claim, source, and nextVerification");
+  }
+  return {
+    domain,
+    claim,
+    source,
+    evidence: evidence.filter((entry) => typeof entry === "string" && entry.trim()),
+    status,
+    applies_to: appliesTo.filter((entry) => typeof entry === "string" && entry.trim()),
+    cannot_mutate: ["release_state_without_owning_lane", "source_evidence", "security_boundary"],
+    next_verification: nextVerification,
+    created_at: new Date().toISOString(),
+  };
+}
+
+export function addLearningRecord(core, record) {
+  const validated = validateLearningLoopCore(core);
+  if (!learningLoopDomains.includes(record.domain)) {
+    throw new Error(`Unsupported learning domain: ${record.domain}`);
+  }
+  if (!["candidate", "verified", "rejected", "superseded"].includes(record.status)) {
+    throw new Error(`Unsupported learning record status: ${record.status}`);
+  }
+  return validateLearningLoopCore({
+    ...validated,
+    records: [...validated.records, record],
+  });
+}
+
+export function evaluateLearningLoopReadiness(core) {
+  const validated = validateLearningLoopCore(core);
+  const coveredDomains = new Set(validated.domains.map((domain) => domain.id));
+  const verifiedDomains = new Set(
+    validated.records
+      .filter((record) => record.status === "verified")
+      .map((record) => record.domain),
+  );
+
+  return {
+    record_type: "learning_loop_readiness",
+    ready: learningLoopDomains.every((domain) => coveredDomains.has(domain)),
+    domains: learningLoopDomains.length,
+    verified_domains: verifiedDomains.size,
+    candidate_records: validated.records.filter((record) => record.status === "candidate").length,
+    promotion_rule: validated.loop.fail_closed_rule,
+  };
+}
+
+export async function seedLearningLoopCoreArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("context"));
+  await writeFileIfMissing(
+    getLearningLoopCorePath(),
+    `${JSON.stringify(createDefaultLearningLoopCore(), null, 2)}\n`,
+  );
+}
+
+export async function loadLearningLoopCore() {
+  return validateLearningLoopCore(await readJson(getLearningLoopCorePath()));
+}

package/src/runtime/maestro-events.js

@@ -0,0 +1,18 @@
+import fs from "node:fs/promises";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export function getMaestroEventsPath() {
+  return getRuntimeSubsystemPath("logs", "maestro-events.ndjson");
+}
+
+export async function appendMaestroEvent(record) {
+  const event = {
+    schemaVersion: "0.1.0",
+    timestamp: new Date().toISOString(),
+    ...record,
+  };
+  const target = getMaestroEventsPath();
+  await fs.mkdir(getRuntimeSubsystemPath("logs"), { recursive: true });
+  await fs.appendFile(target, `${JSON.stringify(event)}\n`, "utf8");
+  return event;
+}

package/src/runtime/maestro-manager.js

@@ -524,6 +524,25 @@ export function chooseMaestroManagerAction({
     };
   }
 
+  if (["READY", "RUNNING"].includes(releaseState.build_status)) {
+    return {
+      mode: "helper+gated",
+      nextAction: "dispatch-gated",
+      dispatchPlan: {
+        helpers: [],
+        gated: [
+          createGatedPlan(
+            "$build",
+            "Advance the bounded build execution substep and persist lane-owned build evidence.",
+            { prerequisites: ["build_status=READY|RUNNING"] },
+          ),
+        ],
+        team: null,
+      },
+      reason: recommendation?.why ?? "The build lane still owns the next bounded execution step.",
+    };
+  }
+
   if (releaseState.merge_status !== "MERGED_TO_DEVELOPMENT") {
     return {
       mode: "team",

package/src/runtime/maestro-state.js

@@ -0,0 +1,125 @@
+import { randomUUID } from "node:crypto";
+import { readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeStatePath } from "../paths.js";
+
+const defaultDependencyGraph = {
+  description: "Topological map of gate execution dependencies.",
+  nodes: {
+    $arch: { dependencies: [] },
+    $sage: { dependencies: ["$arch"] },
+    $flow: { dependencies: ["$sage"] },
+    $vet: { dependencies: ["$sage"] },
+    $vibe: { dependencies: ["$sage"] },
+    $build: { dependencies: ["$flow", "$vet", "$vibe"] },
+  },
+};
+
+const validGlobalStatuses = new Set([
+  "IDLE",
+  "READY",
+  "RUNNING",
+  "COMPLETED",
+  "DEGRADED_HEALING",
+  "LOCKED",
+]);
+
+export function getMaestroStatePath() {
+  return getRuntimeStatePath("maestro-state.json");
+}
+
+export function createDefaultMaestroState() {
+  return {
+    schemaVersion: "0.1.0",
+    orchestration_id: null,
+    timestamp: null,
+    global_status: "IDLE",
+    configuration: {
+      auto_heal: false,
+      max_healing_attempts: 2,
+      concurrency_limit: 4,
+    },
+    dependency_graph: defaultDependencyGraph,
+    runtime_tracks: {},
+    downstream_lock_table: {},
+  };
+}
+
+export function validateMaestroState(state) {
+  if (!state || typeof state !== "object" || Array.isArray(state)) {
+    throw new Error("Maestro state must be an object");
+  }
+  if (state.schemaVersion !== "0.1.0") {
+    throw new Error(`Unsupported maestro state schemaVersion: ${state.schemaVersion}`);
+  }
+  if (!(state.orchestration_id === null || typeof state.orchestration_id === "string")) {
+    throw new Error("maestro_state.orchestration_id must be null or a string");
+  }
+  if (!(state.timestamp === null || typeof state.timestamp === "string")) {
+    throw new Error("maestro_state.timestamp must be null or a string");
+  }
+  if (!validGlobalStatuses.has(state.global_status)) {
+    throw new Error(`Unsupported maestro_state.global_status: ${state.global_status}`);
+  }
+  if (!state.configuration || typeof state.configuration !== "object") {
+    throw new Error("maestro_state.configuration must be an object");
+  }
+  if (!state.dependency_graph || typeof state.dependency_graph !== "object") {
+    throw new Error("maestro_state.dependency_graph must be an object");
+  }
+  if (!state.runtime_tracks || typeof state.runtime_tracks !== "object") {
+    throw new Error("maestro_state.runtime_tracks must be an object");
+  }
+  if (!state.downstream_lock_table || typeof state.downstream_lock_table !== "object") {
+    throw new Error("maestro_state.downstream_lock_table must be an object");
+  }
+
+  return state;
+}
+
+export async function seedMaestroStateArtifacts() {
+  await writeFileIfMissing(
+    getMaestroStatePath(),
+    `${JSON.stringify(createDefaultMaestroState(), null, 2)}\n`,
+  );
+}
+
+export async function loadMaestroState() {
+  return validateMaestroState(await readJson(getMaestroStatePath()));
+}
+
+export async function loadMaestroStateOrDefault() {
+  try {
+    return await loadMaestroState();
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return createDefaultMaestroState();
+    }
+
+    throw error;
+  }
+}
+
+export async function saveMaestroState(state) {
+  validateMaestroState(state);
+  await writeJson(getMaestroStatePath(), state);
+  return state;
+}
+
+export function beginMaestroOrchestration(state, { globalStatus, configuration = null } = {}) {
+  const next = structuredClone(state);
+  if (
+    next.orchestration_id === null ||
+    ["IDLE", "COMPLETED", "LOCKED"].includes(next.global_status)
+  ) {
+    next.orchestration_id = `ma_run_${Date.now()}_${randomUUID().slice(0, 8)}`;
+  }
+  next.timestamp = new Date().toISOString();
+  next.global_status = globalStatus;
+  if (configuration) {
+    next.configuration = {
+      ...next.configuration,
+      ...configuration,
+    };
+  }
+  return next;
+}

package/src/runtime/mcp-policy.js

@@ -0,0 +1,192 @@
+import path from "node:path";
+import { readJson } from "../fs-utils.js";
+import {
+  getMcpLocalCapabilitiesPath,
+  getMcpServersPath,
+  getRuntimeMcpPolicyPath,
+} from "../paths.js";
+
+const allowedExecutionModes = new Set(["READ_ONLY", "SANDBOX_MUTABLE"]);
+const hardenedProfiles = new Set(["project", "deep", "hardened"]);
+
+function createFinding({ sourcePath, severity = "high", diagnostic, recommendedAction }) {
+  return {
+    record_type: "policy:mcp_validation",
+    severity,
+    confidence: "high",
+    source_path: sourcePath,
+    diagnostic,
+    recommended_action: recommendedAction,
+  };
+}
+
+function isSafeRelativePath(value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    return false;
+  }
+  if (path.isAbsolute(value)) {
+    return false;
+  }
+  const normalized = path.normalize(value);
+  return normalized !== ".." && !normalized.startsWith(`..${path.sep}`);
+}
+
+function normalizeArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+export function validateRuntimeMcpPolicy({
+  policy,
+  localCapabilities,
+  servers,
+  activeProfile = "project",
+  sourcePath = ".ma/.mcp.json",
+} = {}) {
+  const findings = [];
+  const supportedCapabilities = new Set(
+    normalizeArray(localCapabilities?.capabilities).map((descriptor) => descriptor.capability),
+  );
+  const approvedEndpoints = new Set(
+    normalizeArray(servers?.servers)
+      .map((server) => server.endpoint)
+      .filter(Boolean),
+  );
+  const addFinding = (finding) => findings.push(createFinding({ sourcePath, ...finding }));
+
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+    addFinding({
+      diagnostic: "Runtime-local MCP policy must be a JSON object.",
+      recommendedAction: "Replace .ma/.mcp.json with an object that narrows repo-owned MCP access.",
+    });
+    return findings;
+  }
+
+  if (policy.schemaVersion !== undefined && policy.schemaVersion !== "0.1.0") {
+    addFinding({
+      severity: "warning",
+      diagnostic: `Unsupported runtime-local MCP policy schemaVersion: ${policy.schemaVersion}.`,
+      recommendedAction:
+        "Use schemaVersion 0.1.0 or omit schemaVersion until the contract changes.",
+    });
+  }
+
+  const policyMode = policy.executionMode ?? policy.execution_mode ?? "READ_ONLY";
+  if (!allowedExecutionModes.has(policyMode)) {
+    addFinding({
+      diagnostic: `Runtime-local MCP policy requests unsupported execution mode '${policyMode}'.`,
+      recommendedAction:
+        "Use READ_ONLY, or SANDBOX_MUTABLE only for explicitly permitted non-hardened runs.",
+    });
+  } else if (hardenedProfiles.has(activeProfile) && policyMode !== "READ_ONLY") {
+    addFinding({
+      diagnostic: `Runtime-local MCP policy cannot use ${policyMode} while profile '${activeProfile}' is hardened.`,
+      recommendedAction:
+        "Switch the runtime-local policy to READ_ONLY for project/deep/hardened profiles.",
+    });
+  }
+
+  for (const capability of normalizeArray(policy.capabilities)) {
+    const capabilityName = capability.capability ?? capability.name;
+    if (!supportedCapabilities.has(capabilityName)) {
+      addFinding({
+        diagnostic: `Runtime-local MCP policy references unsupported capability '${capabilityName ?? "(missing)"}'.`,
+        recommendedAction:
+          "Keep runtime-local capability entries as a subset of mcp/local-capabilities.json.",
+      });
+    }
+
+    const modulePath = capability.module;
+    if (modulePath !== undefined && !isSafeRelativePath(modulePath)) {
+      addFinding({
+        diagnostic: `Runtime-local MCP policy capability '${capabilityName ?? "(missing)"}' uses unsafe module path '${modulePath}'.`,
+        recommendedAction:
+          "Use safe repo-relative paths only; reject absolute paths and traversal.",
+      });
+    }
+
+    const capabilityMode = capability.executionMode ?? capability.execution_mode;
+    if (capabilityMode !== undefined && !allowedExecutionModes.has(capabilityMode)) {
+      addFinding({
+        diagnostic: `Runtime-local MCP policy capability '${capabilityName ?? "(missing)"}' requests unsupported execution mode '${capabilityMode}'.`,
+        recommendedAction:
+          "Use READ_ONLY, or SANDBOX_MUTABLE only where the active profile allows it.",
+      });
+    } else if (
+      capabilityMode !== undefined &&
+      hardenedProfiles.has(activeProfile) &&
+      capabilityMode !== "READ_ONLY"
+    ) {
+      addFinding({
+        diagnostic: `Runtime-local MCP policy capability '${capabilityName ?? "(missing)"}' cannot use ${capabilityMode} while profile '${activeProfile}' is hardened.`,
+        recommendedAction: "Switch capability execution to READ_ONLY for hardened profiles.",
+      });
+    }
+  }
+
+  for (const allowedPath of normalizeArray(policy.allowedPaths ?? policy.allowed_paths)) {
+    if (!isSafeRelativePath(allowedPath)) {
+      addFinding({
+        diagnostic: `Runtime-local MCP policy contains unsafe allowed path '${allowedPath}'.`,
+        recommendedAction: "Use safe repo-relative allowed paths only.",
+      });
+    }
+  }
+
+  for (const endpoint of normalizeArray(policy.evidenceSources ?? policy.evidence_sources)) {
+    if (!approvedEndpoints.has(endpoint)) {
+      addFinding({
+        diagnostic: `Runtime-local MCP policy references unapproved evidence source '${endpoint}'.`,
+        recommendedAction:
+          "Keep runtime-local evidence sources as a subset of mcp/servers.json exact GitMCP endpoints.",
+      });
+    }
+  }
+
+  const envAllowlist =
+    policy.envAllowlist ?? policy.env_allowlist ?? policy.env?.allowlist ?? policy.env?.allow;
+  if (envAllowlist !== undefined) {
+    if (!Array.isArray(envAllowlist)) {
+      addFinding({
+        diagnostic: "Runtime-local MCP policy env allowlist must be an array.",
+        recommendedAction: "Use an explicit array of environment variable names.",
+      });
+    } else {
+      for (const entry of envAllowlist) {
+        if (
+          typeof entry !== "string" ||
+          entry.trim() === "" ||
+          entry === "*" ||
+          entry.includes("*")
+        ) {
+          addFinding({
+            diagnostic: `Runtime-local MCP policy env allowlist contains unsafe entry '${entry}'.`,
+            recommendedAction:
+              "List exact environment variable names only; wildcard env access is not allowed.",
+          });
+        }
+      }
+    }
+  }
+
+  return findings;
+}
+
+export async function validateRuntimeMcpPolicyFile({ activeProfile = "project" } = {}) {
+  let policy;
+  try {
+    policy = await readJson(getRuntimeMcpPolicyPath());
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+
+  return validateRuntimeMcpPolicy({
+    policy,
+    localCapabilities: await readJson(getMcpLocalCapabilitiesPath()),
+    servers: await readJson(getMcpServersPath()),
+    activeProfile,
+    sourcePath: getRuntimeMcpPolicyPath(),
+  });
+}