@jstn-sdk/ma 0.1.12 → 0.1.13

package/src/runtime/workspace-virtualizer.js

@@ -0,0 +1,102 @@
+import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
+import { getRepoRoot, getRuntimeSubsystemPath } from "../paths.js";
+
+export const workspaceVirtualizerSchemaVersion = "0.1.0";
+
+export function getWorkspaceVirtualizerPath() {
+  return getRuntimeSubsystemPath("context", "workspace-virtualizer.json");
+}
+
+export function createDefaultWorkspaceVirtualizer() {
+  return {
+    schemaVersion: workspaceVirtualizerSchemaVersion,
+    product: "Meta-Architect",
+    purpose:
+      "Defines bounded synthetic workspace verification without replacing real source or production release evidence.",
+    evidence_boundary: {
+      records_as: "virtual_workspace_result",
+      never_records_as: "production_evidence",
+      production_promotion_requires: ["real_workspace_test", "release_issue_gate_proof"],
+    },
+    mutation_policy: {
+      default: "read_only",
+      may_mutate_source: false,
+      may_mutate_release_state: false,
+    },
+    applies_to: ["$build", "executor_roles", "verifier_roles"],
+  };
+}
+
+export function validateWorkspaceVirtualizer(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("workspace virtualizer must be an object");
+  }
+  if (value.schemaVersion !== workspaceVirtualizerSchemaVersion) {
+    throw new Error(`Unsupported workspace virtualizer schemaVersion: ${value.schemaVersion}`);
+  }
+  if (value.evidence_boundary?.records_as !== "virtual_workspace_result") {
+    throw new Error("workspace virtualizer must record as virtual_workspace_result");
+  }
+  if (value.evidence_boundary?.never_records_as !== "production_evidence") {
+    throw new Error("workspace virtualizer must not record as production_evidence");
+  }
+  if (value.mutation_policy?.may_mutate_source !== false) {
+    throw new Error("workspace virtualizer must not mutate source by default");
+  }
+  return value;
+}
+
+export async function seedWorkspaceVirtualizerArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("context"));
+  await writeFileIfMissing(
+    getWorkspaceVirtualizerPath(),
+    `${JSON.stringify(createDefaultWorkspaceVirtualizer(), null, 2)}\n`,
+  );
+}
+
+export async function loadWorkspaceVirtualizer() {
+  return validateWorkspaceVirtualizer(await readJson(getWorkspaceVirtualizerPath()));
+}
+
+export function createVirtualWorkspacePlan({
+  commands = [],
+  touchpoints = [],
+  root = getRepoRoot(),
+}) {
+  return {
+    record_type: "virtual_workspace_result",
+    root,
+    source_mutation_allowed: false,
+    production_evidence: false,
+    commands: commands.filter((command) => typeof command === "string" && command.trim()),
+    touchpoints: touchpoints.filter((filePath) => typeof filePath === "string" && filePath.trim()),
+    required_followup:
+      "Run the equivalent checks against the real workspace before production pass.",
+  };
+}
+
+export function createVirtualVerificationReceipt({ plan, commandResults = [] }) {
+  if (plan?.record_type !== "virtual_workspace_result") {
+    throw new Error("Virtual verification receipt requires a virtual workspace plan");
+  }
+
+  const normalizedResults = commandResults.map((result) => ({
+    command: `${result.command ?? ""}`.trim(),
+    exitCode: Number.isInteger(result.exitCode) ? result.exitCode : null,
+    outputPreview: `${result.outputPreview ?? ""}`.slice(0, 500),
+  }));
+  const passed =
+    normalizedResults.length > 0 &&
+    normalizedResults.every((result) => result.command && result.exitCode === 0);
+
+  return {
+    record_type: "virtual_verification_receipt",
+    records_as: "virtual_workspace_result",
+    passed,
+    production_evidence: false,
+    source_mutation_allowed: false,
+    commands: normalizedResults,
+    touchpoints: plan.touchpoints,
+    required_followup: plan.required_followup,
+  };
+}

package/src/runtime-artifacts.js

@@ -52,6 +52,36 @@ function renderRuntimeSummary(summary) {
     `- manager runs: ${summary.managerRunCount}`,
     `- active manager runs: ${summary.activeManagerRunCount}`,
     `- waiting-review manager runs: ${summary.waitingReviewManagerRunCount}`,
+    `- maestro global status: ${summary.maestroGlobalStatus}`,
+    `- maestro runtime tracks: ${summary.maestroTrackCount}`,
+    `- active autonomy ask-only reasons: ${summary.activeAutonomyAskOnlyCount}`,
+    `- active autonomy stall patterns: ${summary.activeAutonomyStallPatternCount}`,
+    `- active autonomy hook enabled: ${summary.activeAutonomyHookEnabled}`,
+    `- semantic recording layers: ${summary.semanticRecordingLayerCount}`,
+    `- default core capabilities: ${summary.semanticDefaultCoreCount}`,
+    `- learning loop domains: ${summary.learningLoopDomainCount}`,
+    `- learning loop records: ${summary.learningLoopRecordCount}`,
+    `- prompt strategy technique families: ${summary.promptStrategyTechniqueFamilyCount}`,
+    `- prompt strategy lane policies: ${summary.promptStrategyLaneCount}`,
+    `- context economy applies-to surfaces: ${summary.contextEconomyAppliesToCount}`,
+    `- context economy exact-preserve rules: ${summary.contextEconomyPreserveExactCount}`,
+    `- context economy safety valves: ${summary.contextEconomySafetyValveCount}`,
+    `- Obsidian bridge records as: ${summary.obsidianBridgeRecordsAs}`,
+    `- Obsidian bridge never records as: ${summary.obsidianBridgeNeverRecordsAs}`,
+    `- Obsidian queued plugin requests: ${summary.obsidianBridgeQueuedRequestCount}`,
+    `- Obsidian note selections: ${summary.obsidianBridgeNoteSelectionCount}`,
+    `- Obsidian tag graph claims: ${summary.obsidianBridgeTagGraphClaimCount}`,
+    `- workspace virtualizer records as: ${summary.workspaceVirtualizerRecordsAs}`,
+    `- code graph rehearse max steps: ${summary.codeGraphRehearseMaxSteps}`,
+    `- skills registry universal targets: ${summary.skillsRegistryUniversalTargetCount}`,
+    `- skills registry non-universal targets: ${summary.skillsRegistryNonUniversalTargetCount}`,
+    `- capability composition entries: ${summary.capabilityCompositionCount}`,
+    `- workspace context channels: ${summary.workspaceContextChannelCount}`,
+    `- workspace effectiveness ready: ${summary.workspaceEffectivenessReady}`,
+    `- workspace effectiveness checks: ${summary.workspaceEffectivenessCheckCount}`,
+    `- semantic receipts: ${summary.semanticReceiptCount}`,
+    `- Obsidian semantic role: ${summary.obsidianSemanticRole}`,
+    `- Obsidian records as: ${summary.obsidianRecordsAs}`,
     `- build status: ${summary.buildStatus}`,
     `- missing runtime artifacts: ${summary.missingArtifacts.length}`,
     `- invalid runtime artifacts: ${summary.invalidArtifacts.length}`,
@@ -59,6 +89,51 @@ function renderRuntimeSummary(summary) {
   ];
 }
 
+function renderListSection(title, items, fallback = "None.") {
+  return [
+    `## ${title}`,
+    "",
+    ...(items.length === 0 ? [fallback] : items.map((item) => `- ${item}`)),
+    "",
+  ];
+}
+
+function renderKeyValueSection(title, entries, fallback = "None.") {
+  const lines = [`## ${title}`, ""];
+  if (entries.length === 0) {
+    lines.push(fallback, "");
+    return lines;
+  }
+
+  for (const [label, value] of entries) {
+    lines.push(`- ${label}: ${value}`);
+  }
+  lines.push("");
+  return lines;
+}
+
+function renderSharedDecisionSections({
+  decision,
+  status,
+  evidence = [],
+  blockers = [],
+  nextAllowedTriggers = [],
+}) {
+  return [
+    "## Decision",
+    "",
+    decision,
+    "",
+    "## Status",
+    "",
+    status,
+    "",
+    ...renderListSection("Evidence", evidence),
+    ...renderListSection("Blockers", blockers),
+    ...renderListSection("Next Allowed Triggers", nextAllowedTriggers, "`$maestro`"),
+  ];
+}
+
 function formatManagerHelper(helper) {
   return `${helper.skill}: ${helper.objective} [${helper.status}]`;
 }
@@ -110,12 +185,49 @@ function renderManagerSection(managerRun) {
   return lines;
 }
 
+function renderBuildContextBoundaries(runtimeSummary) {
+  if (!runtimeSummary) {
+    return [];
+  }
+
+  return [
+    "## Context Boundaries",
+    "",
+    "- Virtual workspace output is context only; it must not be counted as production proof.",
+    `- virtual workspace records as: ${runtimeSummary.workspaceVirtualizerRecordsAs}`,
+    `- virtual workspace never records as: ${runtimeSummary.workspaceVirtualizerNeverRecordsAs}`,
+    `- virtual workspace source mutation allowed: ${runtimeSummary.workspaceVirtualizerSourceMutationAllowed}`,
+    "- Code-graph rehearsal is a bounded read-only preview; it must not unlock source mutation or release promotion.",
+    `- code graph rehearsal records as: ${runtimeSummary.codeGraphRehearseRecordsAs}`,
+    `- code graph rehearsal max steps: ${runtimeSummary.codeGraphRehearseMaxSteps}`,
+    `- code graph rehearsal source mutation allowed: ${runtimeSummary.codeGraphRehearseSourceMutationAllowed}`,
+    "- Exported skills are compatibility payloads; canonical authority stays with `$maestro` or the owning lane.",
+    `- skills registry canonical dir: ${runtimeSummary.skillsRegistryCanonicalDir}`,
+    `- exported skills may mutate release state: ${runtimeSummary.skillsRegistryReleaseMutationAllowed}`,
+    `- Obsidian context records as: ${runtimeSummary.obsidianRecordsAs}`,
+    `- Obsidian bridge records as: ${runtimeSummary.obsidianBridgeRecordsAs}`,
+    "- Obsidian/vault-derived claims are brain context, not build evidence.",
+    "",
+  ];
+}
+
 function renderArchitectureSpec({ idea, blueprint, runtimeSummary }) {
+  const evidence = blueprint.evidence ?? [
+    `Workload assumptions: ${(blueprint.workloadAssumptions ?? []).join(", ") || "baseline assumptions only"}`,
+    `Suggested stack count: ${blueprint.suggestedStack.length}`,
+  ];
   return [
     "# Architecture Spec",
     "",
     `Updated: ${new Date().toISOString()}`,
     "",
+    ...renderSharedDecisionSections({
+      decision: blueprint.decision ?? "Approve the first bounded architecture direction.",
+      status: blueprint.status ?? "APPROVED",
+      evidence,
+      blockers: blueprint.blockers ?? [],
+      nextAllowedTriggers: blueprint.nextAllowedTriggers ?? ["`$sage`"],
+    }),
     "## Problem Statement",
     "",
     idea,
@@ -128,32 +240,42 @@ function renderArchitectureSpec({ idea, blueprint, runtimeSummary }) {
     "",
     ...blueprint.suggestedStack.map((item) => `- ${item}`),
     "",
+    ...renderListSection("Rejected Alternatives", blueprint.rejectedAlternatives ?? []),
     "## Intended Outcome",
     "",
     blueprint.outcome,
     "",
     ...renderRuntimeSummary(runtimeSummary),
-    "## Next Recommended Trigger",
-    "",
-    "`$sage`",
-    "",
   ].join("\n");
 }
 
 function renderEvidenceSpec({ idea, sourceEntries, verified, blockers, runtimeSummary }) {
   const status = verified ? "VERIFIED" : sourceEntries.length > 0 ? "PARTIAL" : "MISSING";
+  const evidenceGrade = verified ? "VERIFIED" : sourceEntries.length > 0 ? "PARTIAL" : "MISSING";
   const lines = [
     "# Evidence Spec",
     "",
     `Updated: ${new Date().toISOString()}`,
     "",
+    ...renderSharedDecisionSections({
+      decision: verified
+        ? "Approve the current source-backed stack direction."
+        : "Evidence remains incomplete; keep the recommendation conditional.",
+      status,
+      evidence: sourceEntries.map((source) => `${source.repo} (${source.category})`),
+      blockers,
+      nextAllowedTriggers: verified ? ["`$flow`"] : ["`$sage`"],
+    }),
     "## Probe Basis",
     "",
     idea,
     "",
-    "## Evidence Status",
+    ...renderKeyValueSection("Evidence Grade", [["grade", evidenceGrade]]),
+    "## Exact Upstream Mapping",
     "",
-    status,
+    ...(sourceEntries.length === 0
+      ? ["No upstream mappings recorded."]
+      : sourceEntries.map((source) => `- ${source.repo} -> ${source.endpoint}`)),
     "",
     "## Sources",
     "",
@@ -176,15 +298,7 @@ function renderEvidenceSpec({ idea, sourceEntries, verified, blockers, runtimeSu
     lines.push("");
   }
 
-  lines.push("## Blockers", "");
-  if (blockers.length === 0) {
-    lines.push("None.", "");
-  } else {
-    lines.push(...blockers.map((blocker) => `- ${blocker}`), "");
-  }
-
   lines.push(...renderRuntimeSummary(runtimeSummary));
-  lines.push("## Next Recommended Trigger", "", verified ? "`$flow`" : "`$sage`", "");
   return lines.join("\n");
 }
 
@@ -194,22 +308,17 @@ function renderLogicSpec(logicMap) {
     "",
     `Updated: ${new Date().toISOString()}`,
     "",
-    ...(logicMap.actors
-      ? ["## Actors", "", ...logicMap.actors.map((actor) => `- ${actor}`), ""]
-      : []),
-    "## States",
-    "",
-    ...logicMap.states.map((state) => `- ${state}`),
-    "",
+    ...renderSharedDecisionSections({
+      decision:
+        logicMap.decision ?? "Validate the current behavioral model before later gates proceed.",
+      status: logicMap.status ?? (logicMap.blockers.length === 0 ? "GREEN" : "RED"),
+      evidence: logicMap.evidence ?? logicMap.actors.map((actor) => `actor: ${actor}`),
+      blockers: logicMap.blockers,
+      nextAllowedTriggers: logicMap.nextAllowedTriggers ?? [logicMap.nextTrigger ?? "`$vet`"],
+    }),
+    ...renderListSection("State Map", logicMap.stateMap ?? logicMap.states),
+    ...renderListSection("Failure Flows", logicMap.failureFlows ?? []),
     ...(logicMap.runtimeSummary ? renderRuntimeSummary(logicMap.runtimeSummary) : []),
-    "## Blockers",
-    "",
-    ...(logicMap.blockers.length === 0 ? ["None."] : logicMap.blockers.map((item) => `- ${item}`)),
-    "",
-    "## Next Recommended Trigger",
-    "",
-    logicMap.nextTrigger ?? "`$vet`",
-    "",
   ].join("\n");
 }
 
@@ -225,22 +334,26 @@ function renderSecuritySpec({
     "",
     `Updated: ${new Date().toISOString()}`,
     "",
-    "## Latest Finding",
-    "",
-    `- severity: ${finding.severity}`,
-    `- summary: ${finding.summary}`,
-    `- unresolved: ${finding.unresolved}`,
-    "",
+    ...renderSharedDecisionSections({
+      decision:
+        finding.unresolved === false
+          ? "Security posture is acceptable for the current bounded release step."
+          : "Security review remains provisional until explicit approval evidence exists.",
+      status: finding.unresolved === false ? "GREEN" : "PENDING",
+      evidence: [`severity: ${finding.severity}`, `summary: ${finding.summary}`],
+      blockers: finding.unresolved
+        ? ["Security review evidence has not been explicitly approved yet."]
+        : [],
+      nextAllowedTriggers: [nextTrigger],
+    }),
+    ...renderListSection("Trust Boundaries", finding.trustBoundaries ?? []),
+    ...renderListSection("Accepted Risks", finding.acceptedRisks ?? []),
     "## Evidence Files",
     "",
     `- audits logged: ${auditCount}`,
     `- cve entries logged: ${cveCount}`,
     "",
     ...renderRuntimeSummary(runtimeSummary),
-    "## Next Recommended Trigger",
-    "",
-    nextTrigger,
-    "",
   ].join("\n");
 }
 
@@ -250,20 +363,26 @@ function renderExperienceSpec({ note, outcomeCount, runtimeSummary, nextTrigger
     "",
     `Updated: ${new Date().toISOString()}`,
     "",
-    "## Latest Outcome",
-    "",
-    `- area: ${note.area}`,
-    `- summary: ${note.summary}`,
-    "",
+    ...renderSharedDecisionSections({
+      decision:
+        note.approved === true
+          ? "DX/UX friction is acceptable for the current bounded release step."
+          : "DX/UX review remains provisional until explicit approval evidence exists.",
+      status: note.approved === true ? "GREEN" : "PENDING",
+      evidence: [`area: ${note.area}`, `summary: ${note.summary}`],
+      blockers:
+        note.approved === true
+          ? []
+          : ["DX/UX review evidence has not been explicitly approved yet."],
+      nextAllowedTriggers: [nextTrigger],
+    }),
+    ...renderListSection("Operator Friction", note.operatorFriction ?? []),
+    ...renderListSection("User Friction", note.userFriction ?? []),
     "## Evidence Files",
     "",
     `- outcomes logged: ${outcomeCount}`,
     "",
     ...renderRuntimeSummary(runtimeSummary),
-    "## Next Recommended Trigger",
-    "",
-    nextTrigger,
-    "",
   ].join("\n");
 }
 
@@ -351,9 +470,14 @@ function renderMaestroPlan({
 
 function renderBuildPlan({
   allowed,
+  gateState = allowed ? "READY" : "LOCKED",
   blockers,
   nextTriggers,
   suggestedBranches = [],
+  buildSlice = [],
+  verificationPlan = [],
+  repairPath = [],
+  completionEvidence = [],
   runtimeSummary = null,
 }) {
   const lines = [
@@ -361,27 +485,48 @@ function renderBuildPlan({
     "",
     `Updated: ${new Date().toISOString()}`,
     "",
+    ...renderSharedDecisionSections({
+      decision:
+        gateState === "DONE"
+          ? "Complete the current bounded build slice and proceed to merge."
+          : gateState === "RUNNING"
+            ? "Continue the active bounded build execution substep."
+            : gateState === "READY"
+              ? "Prepare and begin the next bounded build execution substep."
+              : "Build execution remains locked under the current runtime and release state.",
+      status: gateState,
+      evidence: completionEvidence,
+      blockers,
+      nextAllowedTriggers: nextTriggers,
+    }),
     "## Gate State",
     "",
-    allowed ? "READY" : "LOCKED",
-    "",
-    "## Blockers",
+    gateState,
     "",
   ];
 
-  if (blockers.length === 0) {
-    lines.push("None.", "");
-  } else {
-    lines.push(...blockers.map((blocker) => `- ${blocker}`), "");
+  lines.push(...renderRuntimeSummary(runtimeSummary));
+  lines.push(...renderBuildContextBoundaries(runtimeSummary));
+
+  if (buildSlice.length > 0) {
+    lines.push("## Build Slice", "");
+    lines.push(...buildSlice.map((item) => `- ${item}`), "");
   }
 
-  lines.push(...renderRuntimeSummary(runtimeSummary));
+  if (verificationPlan.length > 0) {
+    lines.push("## Verification Plan", "");
+    lines.push(...verificationPlan.map((item) => `- ${item}`), "");
+  }
 
-  lines.push("## Next Allowed Triggers", "");
-  lines.push(
-    ...(nextTriggers.length === 0 ? ["- $build"] : nextTriggers.map((item) => `- ${item}`)),
-    "",
-  );
+  if (repairPath.length > 0) {
+    lines.push("## Repair Path", "");
+    lines.push(...repairPath.map((item) => `- ${item}`), "");
+  }
+
+  if (completionEvidence.length > 0) {
+    lines.push("## Completion Evidence", "");
+    lines.push(...completionEvidence.map((item) => `- ${item}`), "");
+  }
 
   if (suggestedBranches.length > 0) {
     lines.push(
@@ -422,6 +567,8 @@ function renderRunbook() {
     "- `.ma/specs/experience.md`",
     "- `.ma/plans/implementation.md`",
     "- `.ma/plans/build.md`",
+    "- `.ma/state/manager-runs.json`",
+    "- `.ma/state/maestro-state.json`",
     "- `.ma/decisions.json`",
     "- `.ma/release.json`",
     "",
@@ -540,14 +687,30 @@ export async function writeExperienceSpec({
 
 export async function writeBuildPlanArtifact({
   allowed,
+  gateState = allowed ? "READY" : "LOCKED",
   blockers,
   nextTriggers,
   suggestedBranches = [],
+  buildSlice = [],
+  verificationPlan = [],
+  repairPath = [],
+  completionEvidence = [],
   runtimeSummary = null,
 }) {
   await writeArtifact(
     "plans/build.md",
-    renderBuildPlan({ allowed, blockers, nextTriggers, suggestedBranches, runtimeSummary }),
+    renderBuildPlan({
+      allowed,
+      gateState,
+      blockers,
+      nextTriggers,
+      suggestedBranches,
+      buildSlice,
+      verificationPlan,
+      repairPath,
+      completionEvidence,
+      runtimeSummary,
+    }),
   );
 }