@jstn-sdk/ma 0.1.12 → 0.1.13

package/src/runtime/active-autonomy-core.js

@@ -0,0 +1,208 @@
+import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const activeAutonomyCoreSchemaVersion = "0.1.0";
+
+export function getActiveAutonomyCorePath() {
+  return getRuntimeSubsystemPath("context", "active-autonomy-core.json");
+}
+
+export function createDefaultActiveAutonomyCore() {
+  return {
+    schemaVersion: activeAutonomyCoreSchemaVersion,
+    product: "Meta-Architect",
+    purpose:
+      "Canonical MA contract that prevents passive chatbot behavior across prompts, skills, runtime hooks, and contributor rules.",
+    autonomy_directive: {
+      placement: "top_of_workspace_contract_before_other_guidance",
+      text: [
+        "YOU ARE AN AUTONOMOUS META-ARCHITECT WORKSPACE AGENT.",
+        "EXECUTE CLEAR, SAFE, REVERSIBLE, ALREADY-REQUESTED WORK TO VERIFIED COMPLETION.",
+        "DO NOT ASK WHETHER TO PROCEED ON AUTO-CONTINUE BRANCHES.",
+        "ASK ONLY FOR DESTRUCTIVE, IRREVERSIBLE, CREDENTIAL-GATED, EXTERNAL-PRODUCTION, OR MATERIALLY SCOPE-CHANGING ACTIONS.",
+      ],
+    },
+    decision_rule: {
+      modes: ["AUTO-CONTINUE", "ASK"],
+      auto_continue_when: [
+        "clear_user_requested_work",
+        "local_or_workspace_scoped",
+        "low_risk",
+        "reversible",
+        "non_destructive",
+        "verification_path_available",
+      ],
+      ask_only_when: [
+        "destructive_action",
+        "irreversible_action",
+        "credential_gated_action",
+        "external_production_side_effect",
+        "material_scope_change",
+        "missing_authority_blocks_progress",
+      ],
+      banned_auto_continue_phrasing: [
+        "Should I proceed?",
+        "Would you like me to continue?",
+        "If you want, I can",
+        "If you'd like, I can",
+        "Tell me if you want me to",
+        "I can continue if you want",
+      ],
+    },
+    completion_loop_contract: {
+      required_for: [
+        "$maestro",
+        "$build",
+        "ralph_execution_core",
+        "executor_roles",
+        "team_workers",
+      ],
+      stop_conditions: [
+        "verified_complete",
+        "user_cancelled",
+        "closed_ask_condition_requires_user_input",
+        "same_blocker_repeated_three_times_with_no_safe_alternative",
+      ],
+      completion_requires: [
+        "fresh_verification_evidence",
+        "explicit_outcome",
+        "changed_artifacts_or_no_change_reason",
+        "known_gaps_or_none",
+      ],
+      terminal_outcomes: ["finished", "blocked", "failed", "cancelled", "askuserQuestion"],
+    },
+    runtime_enforcement: {
+      hook_layer: "active_autonomy_runtime",
+      stall_patterns: [
+        "should i proceed",
+        "would you like me to continue",
+        "if you want, i can",
+        "if you'd like, i can",
+        "tell me if you want me to",
+        "i can continue if you want",
+        "let me know if you want me to continue",
+      ],
+      default_response:
+        "AUTO-CONTINUE: continue the current safe branch, execute the next reversible step, then verify before reporting.",
+      native_stop_policy: "block_passive_permission_handoff_when_auto_continue_applies",
+    },
+    contributor_contract: {
+      required_surfaces: [
+        "workspace_contract",
+        "role_prompts",
+        "skill_contracts",
+        "runtime_hook_policy",
+        "docs",
+        "tests",
+      ],
+      regression_targets: [
+        "closed_ask_list_present",
+        "auto_continue_mode_present",
+        "permission_handoff_banned",
+        "completion_requires_fresh_evidence",
+        "terminal_outcome_required",
+        "hook_stall_patterns_present",
+      ],
+    },
+    hard_rules: [
+      "Prompt instructions alone are insufficient; runtime hook policy must backstop passive handoffs.",
+      "AUTO-CONTINUE branches must state next action or evidence-backed result, not request permission.",
+      "ASK branches must name the exact closed-list reason that requires the user.",
+      "Completion claims require fresh verification evidence or an explicit validation gap.",
+      "Contributor edits must preserve anti-passive prompt patterns and hook policy.",
+    ],
+  };
+}
+
+export function validateActiveAutonomyCore(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("active autonomy core must be an object");
+  }
+  if (value.schemaVersion !== activeAutonomyCoreSchemaVersion) {
+    throw new Error(`Unsupported active autonomy core schemaVersion: ${value.schemaVersion}`);
+  }
+  if (!value.decision_rule || typeof value.decision_rule !== "object") {
+    throw new Error("active autonomy core requires decision_rule");
+  }
+  if (!value.decision_rule.modes?.includes("AUTO-CONTINUE")) {
+    throw new Error("active autonomy core requires AUTO-CONTINUE mode");
+  }
+  if (!value.decision_rule.modes?.includes("ASK")) {
+    throw new Error("active autonomy core requires ASK mode");
+  }
+  if (
+    !Array.isArray(value.decision_rule.ask_only_when) ||
+    value.decision_rule.ask_only_when.length === 0
+  ) {
+    throw new Error("active autonomy core requires closed ask_only_when list");
+  }
+  if (!value.runtime_enforcement?.stall_patterns?.includes("should i proceed")) {
+    throw new Error("active autonomy core requires passive stall pattern coverage");
+  }
+  if (
+    !value.completion_loop_contract?.completion_requires?.includes("fresh_verification_evidence")
+  ) {
+    throw new Error("active autonomy core requires fresh verification evidence");
+  }
+  if (JSON.stringify(value).includes(".omx")) {
+    throw new Error("active autonomy core must not expose OMX runtime paths");
+  }
+  return value;
+}
+
+export function classifyAutonomyBranch({ core, requested = true, riskSignals = [] }) {
+  const policy = validateActiveAutonomyCore(core);
+  const signals = new Set(riskSignals.map((signal) => `${signal}`.toLowerCase()));
+  const askReason = policy.decision_rule.ask_only_when.find((reason) =>
+    signals.has(reason.toLowerCase()),
+  );
+
+  if (!requested) {
+    return {
+      mode: "ASK",
+      reason: "missing_authority_blocks_progress",
+      permission_handoff_allowed: true,
+    };
+  }
+
+  if (askReason) {
+    return {
+      mode: "ASK",
+      reason: askReason,
+      permission_handoff_allowed: true,
+    };
+  }
+
+  return {
+    mode: "AUTO-CONTINUE",
+    reason: "clear_safe_reversible_requested_work",
+    permission_handoff_allowed: false,
+    next_action_contract:
+      "state the next safe action or evidence-backed result; do not ask whether to proceed",
+  };
+}
+
+export function detectPassivePermissionHandoff(text, core = createDefaultActiveAutonomyCore()) {
+  const policy = validateActiveAutonomyCore(core);
+  const normalized = `${text}`.toLowerCase();
+  return policy.decision_rule.banned_auto_continue_phrasing.some((phrase) =>
+    normalized.includes(
+      phrase
+        .toLowerCase()
+        .replace(/\.\.\.$/, "")
+        .trim(),
+    ),
+  );
+}
+
+export async function seedActiveAutonomyCoreArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("context"));
+  await writeFileIfMissing(
+    getActiveAutonomyCorePath(),
+    `${JSON.stringify(createDefaultActiveAutonomyCore(), null, 2)}\n`,
+  );
+}
+
+export async function loadActiveAutonomyCore() {
+  return validateActiveAutonomyCore(await readJson(getActiveAutonomyCorePath()));
+}

package/src/runtime/alignment-sentinel.js

@@ -0,0 +1,165 @@
+import { readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeStatePath } from "../paths.js";
+
+const driftRuleDefinitions = [
+  {
+    skill: "$arch",
+    expectedDecisionStatus: "APPROVED",
+    releaseField: "architecture_status",
+    allowedReleaseValues: ["APPROVED"],
+    findingCode: "architecture_status_regressed",
+  },
+  {
+    skill: "$sage",
+    expectedDecisionStatus: "VERIFIED",
+    releaseField: "evidence_status",
+    allowedReleaseValues: ["VERIFIED"],
+    findingCode: "evidence_status_regressed",
+  },
+  {
+    skill: "$flow",
+    expectedDecisionStatus: "GREEN",
+    releaseField: "logic_status",
+    allowedReleaseValues: ["GREEN"],
+    findingCode: "logic_status_regressed",
+  },
+  {
+    skill: "$vet",
+    expectedDecisionStatus: "GREEN",
+    releaseField: "security_status",
+    allowedReleaseValues: ["GREEN"],
+    findingCode: "security_status_regressed",
+  },
+  {
+    skill: "$vibe",
+    expectedDecisionStatus: "GREEN",
+    releaseField: "experience_status",
+    allowedReleaseValues: ["GREEN", "WAIVED"],
+    findingCode: "experience_status_regressed",
+  },
+  {
+    skill: "$build",
+    expectedDecisionStatus: "DONE",
+    releaseField: "build_status",
+    allowedReleaseValues: ["DONE"],
+    findingCode: "build_status_regressed",
+  },
+];
+
+export function getAlignmentSentinelPath() {
+  return getRuntimeStatePath("alignment-sentinel.json");
+}
+
+export function createDefaultAlignmentSentinelReport() {
+  return {
+    schemaVersion: "0.1.0",
+    lastRunAt: null,
+    driftStatus: "CLEAR",
+    rebootPlanned: false,
+    rebootReason: null,
+    resumeTrigger: "$maestro",
+    baselineArtifacts: [
+      ".ma/release.json",
+      ".ma/decisions.json",
+      ".ma/state/manager-runs.json",
+      ".ma/state/maestro-state.json",
+    ],
+    findings: [],
+  };
+}
+
+export async function seedAlignmentSentinelArtifacts() {
+  await writeFileIfMissing(
+    getAlignmentSentinelPath(),
+    `${JSON.stringify(createDefaultAlignmentSentinelReport(), null, 2)}\n`,
+  );
+}
+
+export async function loadAlignmentSentinelReportOrDefault() {
+  try {
+    return await readJson(getAlignmentSentinelPath());
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return createDefaultAlignmentSentinelReport();
+    }
+
+    throw error;
+  }
+}
+
+export async function saveAlignmentSentinelReport(report) {
+  await writeJson(getAlignmentSentinelPath(), report);
+  return report;
+}
+
+function getLatestDecisionBySkill(decisions = []) {
+  const latestBySkill = new Map();
+  for (const decision of decisions) {
+    if (!decision?.skill) {
+      continue;
+    }
+
+    latestBySkill.set(decision.skill, decision);
+  }
+  return latestBySkill;
+}
+
+export function evaluateAlignmentDrift({ releaseState, decisionLog }) {
+  const latestDecisions = getLatestDecisionBySkill(decisionLog?.decisions ?? []);
+  const findings = [];
+
+  for (const rule of driftRuleDefinitions) {
+    const latestDecision = latestDecisions.get(rule.skill);
+    if (!latestDecision || latestDecision.status !== rule.expectedDecisionStatus) {
+      continue;
+    }
+
+    const actualReleaseValue = releaseState?.[rule.releaseField];
+    if (rule.allowedReleaseValues.includes(actualReleaseValue)) {
+      continue;
+    }
+
+    findings.push({
+      severity: "blocking",
+      findingCode: rule.findingCode,
+      skill: rule.skill,
+      expectedDecisionStatus: rule.expectedDecisionStatus,
+      releaseField: rule.releaseField,
+      expectedReleaseValues: rule.allowedReleaseValues,
+      actualReleaseValue,
+      decisionTimestamp: latestDecision.timestamp ?? null,
+      decisionSummary: latestDecision.decision ?? null,
+    });
+  }
+
+  return {
+    driftStatus: findings.length > 0 ? "DRIFTED" : "CLEAR",
+    rebootPlanned: findings.length > 0,
+    rebootReason:
+      findings.length > 0
+        ? "Release state drifted from the latest approved lane-owned decisions."
+        : null,
+    resumeTrigger: "$maestro",
+    findings,
+  };
+}
+
+export function createAlignmentRecoveryPlan(report) {
+  const findings = report?.findings ?? [];
+  return {
+    record_type: "alignment_recovery_plan",
+    driftStatus: report?.driftStatus ?? (findings.length > 0 ? "DRIFTED" : "CLEAR"),
+    rebootPlanned: findings.length > 0,
+    resumeTrigger: report?.resumeTrigger ?? "$maestro",
+    requiredActions: findings.map((finding) => ({
+      skill: finding.skill,
+      repairField: finding.releaseField,
+      expectedValues: finding.expectedReleaseValues,
+      actualValue: finding.actualReleaseValue,
+      action:
+        "Rehydrate from baseline runtime artifacts, then rerun the owning lane or restore lane-owned release state before worker dispatch resumes.",
+    })),
+    mayDispatchWorkers: findings.length === 0,
+    mayMutateReleaseStateDirectly: false,
+  };
+}

package/src/runtime/architect-review.js

@@ -0,0 +1,88 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import { readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeStatePath } from "../paths.js";
+import { redactProviderBoundText, seedRedactionVault } from "./redaction-gateway.js";
+
+export function getArchitectReviewPath() {
+  return getRuntimeStatePath("architect-review.json");
+}
+
+export function createDefaultArchitectReview() {
+  return {
+    schemaVersion: "0.1.0",
+    verdict: "NOT_RUN",
+    reviewer: null,
+    summary: null,
+    findings: [],
+    reviewedAt: null,
+  };
+}
+
+export async function seedArchitectReviewArtifacts() {
+  await writeFileIfMissing(
+    getArchitectReviewPath(),
+    `${JSON.stringify(createDefaultArchitectReview(), null, 2)}\n`,
+  );
+}
+
+export async function loadArchitectReviewOrDefault() {
+  try {
+    return await readJson(getArchitectReviewPath());
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return createDefaultArchitectReview();
+    }
+
+    throw error;
+  }
+}
+
+export async function saveArchitectReview(review) {
+  await writeJson(getArchitectReviewPath(), review);
+  return review;
+}
+
+export async function runExternalArchitectReview({ prompt = "" } = {}) {
+  const command = process.env.MA_ARCHITECT_REVIEW_CMD?.trim();
+  if (!command) {
+    throw new Error("External architect review is not configured. Set MA_ARCHITECT_REVIEW_CMD.");
+  }
+
+  await seedRedactionVault();
+  const redactedPrompt = await redactProviderBoundText(prompt, {
+    kind: "architect-review-prompt",
+  });
+  const promptPath = getRuntimeStatePath("architect-review.prompt.md");
+  const outputPath = getRuntimeStatePath("architect-review.output.json");
+  await fs.writeFile(promptPath, `${redactedPrompt.sanitizedText.trimEnd()}\n`, "utf8");
+
+  const result = spawnSync("/bin/sh", ["-lc", command], {
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      MA_ARCHITECT_REVIEW_PROMPT: redactedPrompt.sanitizedText,
+      MA_ARCHITECT_REVIEW_PROMPT_FILE: promptPath,
+      MA_ARCHITECT_REVIEW_OUTPUT: outputPath,
+    },
+    encoding: "utf8",
+  });
+
+  if (result.status !== 0) {
+    throw new Error(
+      result.stderr?.trim() || result.stdout?.trim() || "External architect review failed",
+    );
+  }
+
+  const parsed = JSON.parse(await fs.readFile(outputPath, "utf8"));
+  const review = {
+    schemaVersion: "0.1.0",
+    verdict: parsed.verdict ?? "UNKNOWN",
+    reviewer: parsed.reviewer ?? "external",
+    summary: parsed.summary ?? null,
+    findings: Array.isArray(parsed.findings) ? parsed.findings : [],
+    reviewedAt: new Date().toISOString(),
+  };
+  await saveArchitectReview(review);
+  return review;
+}

package/src/runtime/build-readiness.js

@@ -4,27 +4,51 @@ import {
   formatNextAllowedTriggers,
 } from "../build-gate.js";
 
-export function evaluateRuntimeBuildReadiness(releaseState, runtimeSummary) {
+export function evaluateRuntimeBuildReadiness(releaseState, runtimeSummary, options = {}) {
+  const enforceIssueGates = options.enforceIssueGates === true;
   const releaseEvaluation = evaluateBuildGate(releaseState);
+  const missingArtifacts = runtimeSummary.missingArtifacts.filter(
+    (artifact) => enforceIssueGates || artifact !== "release.issueGates",
+  );
   const controlPlaneBlockers = [
     ...runtimeSummary.invalidArtifacts.filter((artifact) =>
       ["runtime.release", "runtime.decisions"].includes(artifact),
     ),
-    ...runtimeSummary.missingArtifacts.filter(
+    ...missingArtifacts.filter(
       (artifact) => artifact === "runtime.release" || artifact === "runtime.decisions",
     ),
   ];
   const runtimeBlockers = [
     ...runtimeSummary.invalidArtifacts.map((artifact) => `runtime artifact ${artifact} is invalid`),
-    ...runtimeSummary.missingArtifacts.map((artifact) => `runtime artifact ${artifact} is missing`),
+    ...missingArtifacts.map((artifact) => `runtime artifact ${artifact} is missing`),
     ...(runtimeSummary.pendingMailboxCount > 0
       ? ["pending mailbox proposals require leader review"]
       : []),
+    ...(runtimeSummary.criticalPackageExposureCount > 0
+      ? [
+          `critical package exposure findings require $vet remediation (${runtimeSummary.criticalPackageExposureCount} active)`,
+        ]
+      : []),
+    ...(runtimeSummary.mcpPolicyViolationCount > 0
+      ? [
+          `MCP policy validation findings require $vet remediation (${runtimeSummary.mcpPolicyViolationCount} active)`,
+        ]
+      : []),
+    ...(enforceIssueGates && runtimeSummary.releaseIssueGateBlockerCount > 0
+      ? [
+          `release issue gates require implementation proof (${runtimeSummary.releaseIssueGatePassed}/${runtimeSummary.releaseIssueGateTotal} passed)`,
+        ]
+      : []),
   ];
   const releaseBlockers = formatBuildBlockers(releaseEvaluation);
   const nextTriggers =
     releaseEvaluation.allowed && runtimeBlockers.length > 0
-      ? ["repair runtime artifacts"]
+      ? runtimeSummary.criticalPackageExposureCount > 0 ||
+        runtimeSummary.mcpPolicyViolationCount > 0
+        ? ["$vet"]
+        : enforceIssueGates && runtimeSummary.releaseIssueGateBlockerCount > 0
+          ? ["implement release issue gates"]
+          : ["repair runtime artifacts"]
       : formatNextAllowedTriggers(releaseEvaluation);
 
   return {

package/src/runtime/code-graph-rehearse.js

@@ -0,0 +1,113 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const codeGraphRehearseSchemaVersion = "0.1.0";
+const defaultMaxSteps = 12;
+
+export function getCodeGraphRehearsePath() {
+  return getRuntimeSubsystemPath("context", "code-graph-rehearse.json");
+}
+
+export function createDefaultCodeGraphRehearse() {
+  return {
+    schemaVersion: codeGraphRehearseSchemaVersion,
+    product: "Meta-Architect",
+    purpose:
+      "Provides a bounded read-only trajectory preview over likely code touchpoints before execution.",
+    max_steps: defaultMaxSteps,
+    mutation_policy: {
+      may_mutate_source: false,
+      may_mutate_release_state: false,
+    },
+    evidence_boundary: {
+      records_as: "rehearsal_trace",
+      never_records_as: "implementation_evidence",
+      does_not_unlock: ["source_mutation", "production_release"],
+    },
+    applies_to: ["$arch", "$flow", "$build", "executor_roles"],
+  };
+}
+
+export function validateCodeGraphRehearse(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("code graph rehearse must be an object");
+  }
+  if (value.schemaVersion !== codeGraphRehearseSchemaVersion) {
+    throw new Error(`Unsupported code graph rehearse schemaVersion: ${value.schemaVersion}`);
+  }
+  if (!Number.isInteger(value.max_steps) || value.max_steps <= 0) {
+    throw new Error("code graph rehearse requires positive max_steps");
+  }
+  if (value.mutation_policy?.may_mutate_source !== false) {
+    throw new Error("code graph rehearse must not mutate source");
+  }
+  if (value.evidence_boundary?.records_as !== "rehearsal_trace") {
+    throw new Error("code graph rehearse must record as rehearsal_trace");
+  }
+  return value;
+}
+
+export async function seedCodeGraphRehearseArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("context"));
+  await writeFileIfMissing(
+    getCodeGraphRehearsePath(),
+    `${JSON.stringify(createDefaultCodeGraphRehearse(), null, 2)}\n`,
+  );
+}
+
+export async function loadCodeGraphRehearse() {
+  return validateCodeGraphRehearse(await readJson(getCodeGraphRehearsePath()));
+}
+
+export function createCodeGraphTouchpoint(filePath, imports = []) {
+  return {
+    path: filePath,
+    extension: path.extname(filePath),
+    imports: imports.filter((entry) => typeof entry === "string" && entry.trim()),
+  };
+}
+
+export function extractStaticImports(sourceText) {
+  const imports = new Set();
+  const patterns = [
+    /import\s+(?:[^'"]+\s+from\s+)?["']([^"']+)["']/g,
+    /export\s+[^'"]+\s+from\s+["']([^"']+)["']/g,
+    /await\s+import\(["']([^"']+)["']\)/g,
+    /import\(["']([^"']+)["']\)/g,
+    /require\(["']([^"']+)["']\)/g,
+  ];
+
+  for (const pattern of patterns) {
+    for (const match of sourceText.matchAll(pattern)) {
+      if (match[1]) {
+        imports.add(match[1]);
+      }
+    }
+  }
+
+  return [...imports].sort();
+}
+
+export async function createCodeGraphTouchpointFromFile(filePath) {
+  const sourceText = await fs.readFile(filePath, "utf8");
+  return createCodeGraphTouchpoint(filePath, extractStaticImports(sourceText));
+}
+
+export function createRehearsalTrace({ story, touchpoints = [], plannedSteps = [], maxSteps }) {
+  const limit = Number.isInteger(maxSteps) && maxSteps > 0 ? maxSteps : defaultMaxSteps;
+  const boundedSteps = plannedSteps.slice(0, limit);
+  return {
+    record_type: "rehearsal_trace",
+    story,
+    bounded: plannedSteps.length <= limit,
+    truncated: plannedSteps.length > limit,
+    max_steps: limit,
+    steps: boundedSteps,
+    touchpoints,
+    source_mutation_allowed: false,
+    production_evidence: false,
+    does_not_unlock: ["source_mutation", "production_release"],
+  };
+}