@jstn-sdk/ma 0.1.12 → 0.1.13

package/src/runtime/prompt-strategy-core.js

@@ -0,0 +1,230 @@
+import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const promptStrategyCoreSchemaVersion = "0.1.0";
+
+export function getPromptStrategyCorePath() {
+  return getRuntimeSubsystemPath("context", "prompt-strategy-core.json");
+}
+
+export function createDefaultPromptStrategyCore() {
+  return {
+    schemaVersion: promptStrategyCoreSchemaVersion,
+    product: "Meta-Architect",
+    purpose:
+      "First-party MA policy for selecting prompt strategies across lanes, roles, workers, reviewers, and exported host payloads.",
+    evidence_source: {
+      kind: "gitmcp-evidence",
+      category: "prompt-techniques",
+      repo: "NirDiamant/Prompt_Engineering",
+      endpoint: "https://gitmcp.io/NirDiamant/Prompt_Engineering",
+      reference_path: "all_prompt_engineering_techniques",
+    },
+    technique_families: [
+      {
+        id: "clarity_control",
+        semantic_role: "ambiguity_reduction",
+        reference_topics: [
+          "ambiguity-clarity",
+          "basic-prompt-structures",
+          "instruction-engineering",
+          "specific-task-prompts",
+        ],
+        ma_use:
+          "Clarify task intent, output contract, constraints, and unknowns before lane execution.",
+      },
+      {
+        id: "decomposition_sequence",
+        semantic_role: "work_breakdown",
+        reference_topics: ["task-decomposition-prompts", "prompt-chaining-sequencing"],
+        ma_use:
+          "Break broad requests into lane-owned steps, PRD stories, and verification handoffs.",
+      },
+      {
+        id: "reasoning_validation",
+        semantic_role: "answer_quality_control",
+        reference_topics: [
+          "cot-prompting",
+          "self-consistency",
+          "evaluating-prompt-effectiveness",
+          "prompt-optimization-techniques",
+        ],
+        ma_use:
+          "Use structured reasoning and cross-checks internally, then emit evidence-backed conclusions rather than private reasoning traces.",
+      },
+      {
+        id: "generation_constraints",
+        semantic_role: "bounded_output_shape",
+        reference_topics: [
+          "constrained-guided-generation",
+          "negative-prompting",
+          "prompt-formatting-structure",
+          "prompt-templates-variables-jinja2",
+        ],
+        ma_use:
+          "Constrain lane artifacts, host payloads, semantic receipts, and compatibility exports.",
+      },
+      {
+        id: "context_and_examples",
+        semantic_role: "context_selection",
+        reference_topics: [
+          "zero-shot-prompting",
+          "few-shot-learning",
+          "role-prompting",
+          "prompt-length-complexity-management",
+          "multilingual-prompting",
+        ],
+        ma_use:
+          "Select minimal examples, role boundaries, language constraints, and context budgets for each workspace surface.",
+      },
+      {
+        id: "safety_integrity",
+        semantic_role: "prompt_safety",
+        reference_topics: ["prompt-security-and-safety", "ethical-prompt-engineering"],
+        ma_use:
+          "Preserve security warnings, redaction boundaries, authority semantics, and high-stakes safety language.",
+      },
+    ],
+    lane_policy: {
+      $maestro: ["clarity_control", "decomposition_sequence", "generation_constraints"],
+      $arch: ["clarity_control", "decomposition_sequence", "reasoning_validation"],
+      $sage: ["clarity_control", "generation_constraints", "safety_integrity"],
+      $flow: ["decomposition_sequence", "reasoning_validation", "generation_constraints"],
+      $vet: ["safety_integrity", "reasoning_validation", "generation_constraints"],
+      $vibe: ["clarity_control", "context_and_examples", "generation_constraints"],
+      $build: ["decomposition_sequence", "reasoning_validation", "safety_integrity"],
+      ralph_execution_core: [
+        "decomposition_sequence",
+        "generation_constraints",
+        "safety_integrity",
+      ],
+      exported_host_payloads: [
+        "generation_constraints",
+        "context_and_examples",
+        "safety_integrity",
+      ],
+      active_autonomy_core: [
+        "clarity_control",
+        "decomposition_sequence",
+        "generation_constraints",
+        "safety_integrity",
+      ],
+    },
+    role_policy: {
+      architect: ["clarity_control", "decomposition_sequence", "reasoning_validation"],
+      executor: ["decomposition_sequence", "generation_constraints", "safety_integrity"],
+      verifier: ["reasoning_validation", "generation_constraints", "safety_integrity"],
+      reviewer: ["reasoning_validation", "safety_integrity", "generation_constraints"],
+      worker: ["decomposition_sequence", "generation_constraints", "context_and_examples"],
+      writer: ["clarity_control", "context_and_examples", "generation_constraints"],
+      designer: ["clarity_control", "context_and_examples", "reasoning_validation"],
+    },
+    hard_rules: [
+      "Prompt Strategy Core is an internal MA policy, not a user-facing skill family.",
+      "Prompt techniques cannot override lane ownership, semantic receipts, redaction, or release-state authority.",
+      "Prompt techniques cannot weaken AUTO-CONTINUE / ASK rules or permission-handoff bans.",
+      "Reasoning techniques may structure internal work, but public artifacts report conclusions, evidence, and verification gaps rather than private deliberation traces.",
+      "Few-shot or template examples must be MA-owned and workspace-safe before export.",
+      "Safety and prompt-security rules cannot be compressed away by Context Economy Core.",
+    ],
+  };
+}
+
+export function validatePromptStrategyCore(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("prompt strategy core must be an object");
+  }
+  if (value.schemaVersion !== promptStrategyCoreSchemaVersion) {
+    throw new Error(`Unsupported prompt strategy core schemaVersion: ${value.schemaVersion}`);
+  }
+  if (value.evidence_source?.repo !== "NirDiamant/Prompt_Engineering") {
+    throw new Error("prompt strategy core requires the Prompt_Engineering evidence source");
+  }
+  if (!Array.isArray(value.technique_families) || value.technique_families.length === 0) {
+    throw new Error("prompt strategy core requires technique_families");
+  }
+  if (!value.lane_policy || typeof value.lane_policy !== "object") {
+    throw new Error("prompt strategy core requires lane_policy");
+  }
+  if (!value.role_policy || typeof value.role_policy !== "object") {
+    throw new Error("prompt strategy core requires role_policy");
+  }
+  if (JSON.stringify(value).includes(".omx")) {
+    throw new Error("prompt strategy core must not expose OMX runtime paths");
+  }
+  return value;
+}
+
+export function resolvePromptStrategyForSurface({ core, surface, risk = "standard" }) {
+  const policy = validatePromptStrategyCore(core);
+  const techniques = policy.lane_policy?.[surface] ?? policy.lane_policy?.exported_host_payloads;
+  if (!Array.isArray(techniques) || techniques.length === 0) {
+    throw new Error(`No prompt strategy policy for surface: ${surface}`);
+  }
+
+  const required = new Set(techniques);
+  if (["high", "security", "release"].includes(risk)) {
+    required.add("safety_integrity");
+    required.add("reasoning_validation");
+  }
+
+  return {
+    record_type: "prompt_strategy_resolution",
+    surface,
+    risk,
+    techniques: [...required],
+    evidence_source: policy.evidence_source,
+    authority_boundary: {
+      may_override_lane_authority: false,
+      may_remove_safety_language: false,
+      reports_private_reasoning: false,
+    },
+  };
+}
+
+export function resolvePromptStrategyForRole({
+  core,
+  role,
+  surface = "$maestro",
+  risk = "standard",
+} = {}) {
+  const policy = validatePromptStrategyCore(core);
+  const roleTechniques = policy.role_policy?.[role] ?? policy.role_policy?.worker;
+  if (!Array.isArray(roleTechniques) || roleTechniques.length === 0) {
+    throw new Error(`No prompt strategy policy for role: ${role}`);
+  }
+  const surfaceResolution = resolvePromptStrategyForSurface({ core: policy, surface, risk });
+  const techniques = new Set([...surfaceResolution.techniques, ...roleTechniques]);
+  if (role === "verifier" || role === "reviewer") {
+    techniques.add("reasoning_validation");
+    techniques.add("safety_integrity");
+  }
+
+  return {
+    record_type: "prompt_strategy_role_resolution",
+    role,
+    surface,
+    risk,
+    techniques: [...techniques],
+    evidence_source: policy.evidence_source,
+    authority_boundary: surfaceResolution.authority_boundary,
+    output_contract: {
+      outcome_first: true,
+      evidence_required: ["verifier", "reviewer", "executor"].includes(role),
+      private_reasoning_reported: false,
+      may_override_lane_authority: false,
+    },
+  };
+}
+
+export async function seedPromptStrategyCoreArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("context"));
+  await writeFileIfMissing(
+    getPromptStrategyCorePath(),
+    `${JSON.stringify(createDefaultPromptStrategyCore(), null, 2)}\n`,
+  );
+}
+
+export async function loadPromptStrategyCore() {
+  return validatePromptStrategyCore(await readJson(getPromptStrategyCorePath()));
+}

package/src/runtime/quorum-review.js

@@ -0,0 +1,90 @@
+export const quorumDecisions = {
+  APPROVED: "APPROVED",
+  REJECTED: "REJECTED",
+  INDETERMINATE: "INDETERMINATE",
+};
+
+function createFingerprintKey(fingerprint) {
+  if (!fingerprint || typeof fingerprint !== "object") {
+    return null;
+  }
+
+  return JSON.stringify(fingerprint);
+}
+
+export function evaluateQuorumVotes(votes = []) {
+  if (!Array.isArray(votes) || votes.length === 0) {
+    return {
+      decision: quorumDecisions.INDETERMINATE,
+      winningFingerprint: null,
+      blockers: ["No quorum votes were supplied."],
+    };
+  }
+
+  const tallies = new Map();
+  const majorityTarget = Math.floor(votes.length / 2) + 1;
+
+  for (const vote of votes) {
+    const fingerprintKey = createFingerprintKey(vote.fingerprint);
+    const key = `${vote.decision}::${fingerprintKey ?? "null"}`;
+    const tally = tallies.get(key) ?? {
+      decision: vote.decision,
+      fingerprint: vote.fingerprint ?? null,
+      count: 0,
+    };
+    tally.count += 1;
+    tallies.set(key, tally);
+  }
+
+  const winning = [...tallies.values()].find((entry) => entry.count >= majorityTarget);
+  if (!winning) {
+    return {
+      decision: quorumDecisions.INDETERMINATE,
+      winningFingerprint: null,
+      blockers: ["Quorum votes did not converge on a majority-compatible fingerprint."],
+    };
+  }
+
+  return {
+    decision: winning.decision,
+    winningFingerprint: winning.fingerprint,
+    blockers: [],
+  };
+}
+
+export function createQuorumReviewReceipt({ votes = [], evaluation }) {
+  const result = evaluation ?? evaluateQuorumVotes(votes);
+  const majorityFingerprint = result.winningFingerprint
+    ? JSON.stringify(result.winningFingerprint)
+    : null;
+  const minorityVotes = votes.filter((vote) => {
+    if (result.decision === quorumDecisions.INDETERMINATE) {
+      return true;
+    }
+    return (
+      vote.decision !== result.decision ||
+      JSON.stringify(vote.fingerprint ?? null) !== majorityFingerprint
+    );
+  });
+
+  return {
+    record_type: "quorum_review_receipt",
+    decision: result.decision,
+    winningFingerprint: result.winningFingerprint,
+    reviewer_count: votes.length,
+    minority_report: minorityVotes.map((vote) => ({
+      model_identifier: vote.model_identifier ?? "unknown",
+      decision: vote.decision,
+      fingerprint: vote.fingerprint ?? null,
+      blockers: vote.blockers ?? [],
+      rationale_summary: vote.rationale_summary ?? "",
+    })),
+    confidence_receipt: {
+      records_as: "verification_confidence",
+      production_evidence: false,
+      may_mark_build_done: result.decision === quorumDecisions.APPROVED,
+      requires_existing_build_gate_evidence: true,
+    },
+    blockers: result.blockers,
+  };
+}

package/src/runtime/ralph-execution-core.js

@@ -0,0 +1,217 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeJson } from "../fs-utils.js";
+import { getRuntimeWritePath } from "../paths.js";
+
+export const ralphPrdSchemaVersion = "0.1.0";
+
+export function getRalphPrdPath() {
+  return getRuntimeWritePath("plans", "prd.json");
+}
+
+export function getRalphProgressPath() {
+  return getRuntimeWritePath("plans", "progress.txt");
+}
+
+function slugify(value) {
+  return `${value}`
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function createRalphPrdContract({
+  project = "Meta-Architect-Build",
+  branchName = "ralph/meta-architect-build",
+  description = "Execute the current bounded Meta-Architect build slice under MA gates.",
+  buildSlice = [],
+  verificationPlan = [],
+  runtimeSummary = null,
+}) {
+  const safeProject = project.trim() || "Meta-Architect-Build";
+  const safeBranch = branchName.trim() || `ralph/${slugify(safeProject)}`;
+  const storyDescription =
+    buildSlice.length > 0
+      ? buildSlice.join(" ")
+      : "Implement one reversible, bounded story from the approved MA plan.";
+  const acceptanceCriteria = [
+    ...verificationPlan,
+    "Run the smallest relevant real-workspace verification before marking the story passed.",
+    "Preserve Obsidian/vault-derived context as vault_context, not build_evidence.",
+    "Preserve Context Economy safety valves for warnings, irreversible actions, failed checks, and known gaps.",
+    "Do not mutate .ma/release.json or .ma/decisions.json directly from the execution loop.",
+  ].filter((item, index, items) => item && items.indexOf(item) === index);
+
+  return validateRalphPrdContract({
+    schemaVersion: ralphPrdSchemaVersion,
+    product: "Meta-Architect",
+    project: safeProject,
+    branchName: safeBranch,
+    description,
+    authority: "$maestro_or_owning_lane_dispatch",
+    evidenceBoundary: {
+      obsidianRecordsAs: runtimeSummary?.obsidianRecordsAs ?? "vault_context",
+      virtualWorkspaceRecordsAs:
+        runtimeSummary?.workspaceVirtualizerRecordsAs ?? "virtual_workspace_result",
+      rehearsalRecordsAs: runtimeSummary?.codeGraphRehearseRecordsAs ?? "rehearsal_trace",
+      releaseStateMutationAllowed: false,
+    },
+    qualityGates: ["$arch", "$sage", "$flow", "$vet", "$vibe", "$build"],
+    userStories: [
+      {
+        id: "US-001",
+        title: "Execute bounded MA build slice",
+        description: storyDescription,
+        acceptanceCriteria,
+        priority: 1,
+        passes: false,
+        notes:
+          "Ralph Execution Core executes story-by-story after MA gates pass; $build owns final promotion readiness.",
+      },
+    ],
+  });
+}
+
+export function validateRalphPrdContract(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Ralph PRD contract must be an object");
+  }
+  if (value.schemaVersion !== ralphPrdSchemaVersion) {
+    throw new Error(`Unsupported Ralph PRD schemaVersion: ${value.schemaVersion}`);
+  }
+  if (!value.project || !value.branchName || !value.description) {
+    throw new Error("Ralph PRD contract requires project, branchName, and description");
+  }
+  if (value.authority !== "$maestro_or_owning_lane_dispatch") {
+    throw new Error("Ralph PRD authority must stay with $maestro or owning lane dispatch");
+  }
+  if (value.evidenceBoundary?.releaseStateMutationAllowed !== false) {
+    throw new Error("Ralph PRD must not allow direct release-state mutation");
+  }
+  if (value.evidenceBoundary?.obsidianRecordsAs !== "vault_context") {
+    throw new Error("Ralph PRD must preserve Obsidian as vault_context");
+  }
+  if (!Array.isArray(value.userStories) || value.userStories.length === 0) {
+    throw new Error("Ralph PRD requires at least one user story");
+  }
+  for (const story of value.userStories) {
+    if (!story.id || !story.title || !story.description) {
+      throw new Error("Ralph story requires id, title, and description");
+    }
+    if (!Array.isArray(story.acceptanceCriteria) || story.acceptanceCriteria.length === 0) {
+      throw new Error(`Ralph story ${story.id} requires acceptance criteria`);
+    }
+    if (story.passes !== false && story.passes !== true) {
+      throw new Error(`Ralph story ${story.id} requires boolean passes`);
+    }
+  }
+  return value;
+}
+
+export async function writeRalphExecutionContract(options) {
+  const prd = createRalphPrdContract(options);
+  const prdPath = getRalphPrdPath();
+  const progressPath = getRalphProgressPath();
+  await writeJson(prdPath, prd);
+  await fs.mkdir(path.dirname(progressPath), { recursive: true });
+  await fs.writeFile(
+    progressPath,
+    [
+      "# Ralph Execution Progress",
+      "",
+      `Initialized: ${new Date().toISOString()}`,
+      "",
+      "## Codebase Patterns",
+      "",
+      "No reusable execution learnings recorded yet.",
+      "",
+      "## Iterations",
+      "",
+      "- pending: US-001 awaits MA-gated execution and fresh verification evidence.",
+      "",
+    ].join("\n"),
+  );
+  return { prd, prdPath, progressPath };
+}
+
+export function completeRalphStory({ prd, storyId, verificationEvidence = [], notes = "" }) {
+  const next = validateRalphPrdContract(JSON.parse(JSON.stringify(prd)));
+  if (!Array.isArray(verificationEvidence) || verificationEvidence.length === 0) {
+    throw new Error("Ralph story completion requires fresh verification evidence");
+  }
+
+  const story = next.userStories.find((candidate) => candidate.id === storyId);
+  if (!story) {
+    throw new Error(`Ralph story not found: ${storyId}`);
+  }
+
+  story.passes = true;
+  story.notes = [story.notes, notes, `verification: ${verificationEvidence.join("; ")}`]
+    .filter(Boolean)
+    .join("\n");
+  return validateRalphPrdContract(next);
+}
+
+export function selectNextRalphStory({ prd } = {}) {
+  const contract = validateRalphPrdContract(prd);
+  const candidates = contract.userStories
+    .filter((story) => story.passes === false)
+    .sort((a, b) => Number(a.priority ?? 999) - Number(b.priority ?? 999));
+  return candidates[0] ?? null;
+}
+
+export function createRalphIterationPlan({ prd, progress = "", role = "executor" } = {}) {
+  const contract = validateRalphPrdContract(prd);
+  const story = selectNextRalphStory({ prd: contract });
+  if (!story) {
+    return {
+      record_type: "ralph_iteration_plan",
+      status: "complete",
+      records_as: "execution_plan",
+      build_evidence: false,
+      authority: contract.authority,
+      next_story: null,
+      instruction:
+        "All Ralph stories are passed. Return through $maestro or the owning lane with verification evidence.",
+    };
+  }
+
+  return {
+    record_type: "ralph_iteration_plan",
+    status: "ready",
+    records_as: "execution_plan",
+    build_evidence: false,
+    authority: contract.authority,
+    role,
+    next_story: {
+      id: story.id,
+      title: story.title,
+      description: story.description,
+      acceptanceCriteria: story.acceptanceCriteria,
+      priority: story.priority,
+    },
+    progress_excerpt: progress.slice(-1200),
+    required_gates: contract.qualityGates,
+    stop_conditions: [
+      "fresh_verification_evidence_missing",
+      "destructive_or_irreversible_action_required",
+      "credential_or_external_production_authority_missing",
+      "same_failure_repeats_three_times",
+    ],
+    loop_instruction:
+      "Execute exactly this story, run real verification, update progress, then mark passes only with fresh evidence.",
+  };
+}
+
+export function appendRalphProgressEntry({ current = "", storyId, status, evidence = [] }) {
+  if (!storyId || !status) {
+    throw new Error("Ralph progress entry requires storyId and status");
+  }
+
+  return [
+    current.trimEnd(),
+    `- ${new Date().toISOString()}: ${storyId} ${status}; evidence=${evidence.join(", ") || "none"}`,
+    "",
+  ].join("\n");
+}