@jstn-sdk/ma 0.1.11 → 0.1.13

package/src/release-issue-gates.js

@@ -0,0 +1,190 @@
+const ALLOWED_STATUSES = new Set(["pending", "in_progress", "blocked", "failed", "passed"]);
+const REQUIRED_PROOF_FIELDS = [
+  "implementationEvidence",
+  "verificationEvidence",
+  "productionEvidence",
+];
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function hasStringItems(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(isNonEmptyString);
+}
+
+export function validateReleaseIssueGates(document, options = {}) {
+  const version = options.version;
+  const requirePassed = options.requirePassed ?? true;
+  const errors = [];
+
+  if (!document || typeof document !== "object" || Array.isArray(document)) {
+    return {
+      valid: false,
+      errors: ["release issue gate document must be an object"],
+    };
+  }
+
+  const expectedTag = version ? `v${version}` : document.releaseTag;
+
+  if (document.schemaVersion !== "1.0.0") {
+    errors.push("schemaVersion must be 1.0.0");
+  }
+
+  if (version && document.releaseVersion !== version) {
+    errors.push(`releaseVersion must match package version ${version}`);
+  }
+
+  if (!isNonEmptyString(document.releaseTag)) {
+    errors.push("releaseTag is required");
+  } else if (expectedTag && document.releaseTag !== expectedTag) {
+    errors.push(`releaseTag must be ${expectedTag}`);
+  }
+
+  if (document.passContract?.allIssuesMustPassProduction !== true) {
+    errors.push("passContract.allIssuesMustPassProduction must be true");
+  }
+
+  if (document.passContract?.allIssuesMustHaveLabels !== true) {
+    errors.push("passContract.allIssuesMustHaveLabels must be true");
+  }
+
+  if (!Array.isArray(document.issues) || document.issues.length === 0) {
+    errors.push("issues must be a non-empty array");
+    return { valid: errors.length === 0, errors };
+  }
+
+  const seen = new Set();
+  for (const issue of document.issues) {
+    const issueLabel = Number.isInteger(issue?.number) ? `#${issue.number}` : "<unknown issue>";
+
+    if (!Number.isInteger(issue?.number) || issue.number <= 0) {
+      errors.push(`${issueLabel}: number must be a positive integer`);
+      continue;
+    }
+
+    if (seen.has(issue.number)) {
+      errors.push(`${issueLabel}: duplicate issue number`);
+    }
+    seen.add(issue.number);
+
+    if (!isNonEmptyString(issue.title)) {
+      errors.push(`${issueLabel}: title is required`);
+    }
+
+    if (!isNonEmptyString(issue.url) || !issue.url.includes(`/issues/${issue.number}`)) {
+      errors.push(`${issueLabel}: url must reference the GitHub issue`);
+    }
+
+    if (issue.releaseVersion !== document.releaseVersion) {
+      errors.push(`${issueLabel}: releaseVersion must match document releaseVersion`);
+    }
+
+    if (issue.releaseTag !== document.releaseTag) {
+      errors.push(`${issueLabel}: releaseTag must match document releaseTag`);
+    }
+
+    if (issue.milestone !== document.releaseTag) {
+      errors.push(`${issueLabel}: milestone must match document releaseTag`);
+    }
+
+    if (!ALLOWED_STATUSES.has(issue.status)) {
+      errors.push(`${issueLabel}: invalid status ${issue.status}`);
+    }
+
+    if (document.passContract?.allIssuesMustHaveLabels === true && !hasStringItems(issue.labels)) {
+      errors.push(`${issueLabel}: labels must contain at least one issue label`);
+    }
+
+    if (!hasStringItems(issue.requiredProof)) {
+      errors.push(`${issueLabel}: requiredProof must contain at least one proof requirement`);
+    }
+
+    if (!isNonEmptyString(issue.loopAction)) {
+      errors.push(`${issueLabel}: loopAction is required until production proof passes`);
+    }
+
+    const proof = issue.proof;
+    if (!proof || typeof proof !== "object" || Array.isArray(proof)) {
+      errors.push(`${issueLabel}: proof object is required`);
+      continue;
+    }
+
+    for (const field of REQUIRED_PROOF_FIELDS) {
+      if (!Array.isArray(proof[field])) {
+        errors.push(`${issueLabel}: proof.${field} must be an array`);
+      }
+    }
+
+    if (issue.status === "passed") {
+      for (const field of REQUIRED_PROOF_FIELDS) {
+        if (!hasStringItems(proof[field])) {
+          errors.push(`${issueLabel}: status passed requires non-empty proof.${field}`);
+        }
+      }
+    }
+
+    if (requirePassed && issue.status !== "passed") {
+      errors.push(`${issueLabel}: status is ${issue.status}; continue loopAction before release`);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+export function summarizeReleaseIssueGateStatus(document, options = {}) {
+  const structural = validateReleaseIssueGates(document, {
+    ...options,
+    requirePassed: false,
+  });
+
+  if (!structural.valid) {
+    return {
+      valid: false,
+      total: 0,
+      passed: 0,
+      pending: 0,
+      inProgress: 0,
+      blocked: 0,
+      failed: 0,
+      blockers: structural.errors,
+    };
+  }
+
+  const summary = {
+    valid: true,
+    total: document.issues.length,
+    passed: 0,
+    pending: 0,
+    inProgress: 0,
+    blocked: 0,
+    failed: 0,
+    blockers: [],
+  };
+
+  for (const issue of document.issues) {
+    if (issue.status === "passed") {
+      summary.passed += 1;
+      continue;
+    }
+
+    if (issue.status === "pending") {
+      summary.pending += 1;
+    } else if (issue.status === "in_progress") {
+      summary.inProgress += 1;
+    } else if (issue.status === "blocked") {
+      summary.blocked += 1;
+    } else if (issue.status === "failed") {
+      summary.failed += 1;
+    }
+
+    summary.blockers.push(
+      `#${issue.number}: ${issue.status}; ${issue.loopAction || "continue implementation loop"}`,
+    );
+  }
+
+  return summary;
+}

package/src/release-state.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import { writeJson } from "./fs-utils.js";
 import { getRuntimeReadPath, getRuntimeWritePath } from "./paths.js";
 
-const allowedStatuses = {
+export const allowedStatuses = {
   idea_status: ["DRAFT", "CLEAR", "BLOCKED"],
   architecture_status: ["DRAFT", "REVIEWED", "APPROVED"],
   evidence_status: ["MISSING", "PARTIAL", "VERIFIED"],
@@ -27,6 +27,23 @@ function validateWaiver(state) {
   }
 }
 
+export function createDefaultReleaseState() {
+  return {
+    schemaVersion: "0.1.0",
+    idea_status: "DRAFT",
+    architecture_status: "DRAFT",
+    evidence_status: "MISSING",
+    logic_status: "PENDING",
+    security_status: "PENDING",
+    experience_status: "PENDING",
+    build_status: "LOCKED",
+    merge_status: "LOCKED",
+    release_status: "LOCKED",
+    waiver: null,
+    updatedAt: null,
+  };
+}
+
 export function validateReleaseState(state) {
   if (!state || typeof state !== "object" || Array.isArray(state)) {
     throw new Error("Release state must be an object");
@@ -48,6 +65,18 @@ export async function loadReleaseState() {
   return validateReleaseState(parsed);
 }
 
+export async function loadReleaseStateOrDefault() {
+  try {
+    return await loadReleaseState();
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return createDefaultReleaseState();
+    }
+
+    throw error;
+  }
+}
+
 export async function saveReleaseState(state) {
   validateReleaseState(state);
   const next = {

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;
+}