@jstn-sdk/ma 0.1.11 → 0.1.13

package/bin/ma.js

@@ -1,11 +1,6 @@
 #!/usr/bin/env node
 
 import { runBootstrap, runDoctor } from "../src/bootstrap.js";
-import {
-  evaluateBuildGate,
-  formatBuildBlockers,
-  formatNextAllowedTriggers,
-} from "../src/build-gate.js";
 import { appendDecision } from "../src/decision-log.js";
 import { runCodex, shouldDelegateToCodex } from "../src/launcher.js";
 import {
@@ -15,7 +10,20 @@ import {
   validateReleaseOrigin,
 } from "../src/policy.js";
 import { loadReleaseState } from "../src/release-state.js";
-import { writeBuildPlanArtifact } from "../src/runtime-artifacts.js";
+import { runExternalArchitectReview } from "../src/runtime/architect-review.js";
+import { evaluateRuntimeBuildReadiness } from "../src/runtime/build-readiness.js";
+import { ingestCoreSources } from "../src/runtime/core-source-ingest.js";
+import {
+  appendObsidianOperationReceipt,
+  createObsidianNote,
+  deleteObsidianNote,
+  listObsidianNotes,
+  readObsidianNote,
+  updateObsidianNote,
+  writeObsidianVaultIndex,
+} from "../src/runtime/obsidian-integration-core.js";
+import { installObsidianPlugin } from "../src/runtime/obsidian-plugin-bridge.js";
+import { createRuntimeSummary, loadRuntimeSnapshot } from "../src/runtime/runtime-state.js";
 import {
   ensureSkillsInstalled,
   ensureSupportBundleInstalled,
@@ -24,6 +32,7 @@ import {
 import {
   listSkills,
   runArch,
+  runBuildLane,
   runFlow,
   runIdea,
   runInit,
@@ -43,14 +52,20 @@ function printUsage() {
   console.error("  ma init");
   console.error('  ma idea "..."');
   console.error("  ma skills");
+  console.error("  ma core-ingest [--refresh]");
+  console.error("  ma obsidian-index [vault-path]");
+  console.error(
+    "  ma obsidian list|read|create|update|delete|plugin-install <vault-path> [note-path] [content]",
+  );
   console.error("  ma sdk-path");
-  console.error("  ma status");
-  console.error("  ma run $maestro|$arch|$sage|$flow|$vet|$vibe|$build");
+  console.error("  ma status [--maestro-view]");
+  console.error("  ma verify --architect");
+  console.error("  ma run $maestro|$arch|$sage|$flow|$vet|$vibe|$build [--auto-heal] [--parallel]");
   console.error("  ma merge <source-branch> <target-branch>");
   console.error("  ma release <origin-branch> <target-branch>");
 }
 
-function printStatus(releaseState) {
+async function printStatus(releaseState) {
   console.log("Meta-Architect Status");
   console.log("=====================");
   console.log(`Idea: ${releaseState.idea_status}`);
@@ -61,9 +76,23 @@ function printStatus(releaseState) {
   console.log(`Experience: ${releaseState.experience_status}`);
   console.log(`Build: ${releaseState.build_status}`);
 
-  const evaluation = evaluateBuildGate(releaseState);
+  const runtimeSummary = createRuntimeSummary(await loadRuntimeSnapshot());
+  console.log(
+    `Core source snapshots: ${runtimeSummary.coreSourceIngestCount} (${runtimeSummary.coreSourceIngestStatus})`,
+  );
+  console.log(`Obsidian vault notes: ${runtimeSummary.obsidianVaultNoteCount}`);
+  console.log(`Obsidian CRUD receipts: ${runtimeSummary.obsidianVaultOperationCount}`);
+  if (
+    releaseState.build_status === "DONE" &&
+    releaseState.merge_status !== "MERGED_TO_DEVELOPMENT"
+  ) {
+    console.log("Next allowed triggers:");
+    console.log("ma merge <feature/*> development");
+    return;
+  }
+  const evaluation = evaluateRuntimeBuildReadiness(releaseState, runtimeSummary);
   console.log("Next allowed triggers:");
-  const triggers = formatNextAllowedTriggers(evaluation);
+  const triggers = evaluation.nextTriggers;
   if (triggers.length === 0) {
     console.log("$build");
     return;
@@ -74,71 +103,78 @@ function printStatus(releaseState) {
   }
 }
 
-async function runBuild(releaseState) {
-  const evaluation = evaluateBuildGate(releaseState);
+async function printMaestroView() {
+  const snapshot = await loadRuntimeSnapshot();
+  const trackEntries = Object.entries(snapshot.maestroState.runtime_tracks);
+  console.log("Maestro View");
+  console.log("============");
+  console.log(`Global status: ${snapshot.maestroState.global_status}`);
+  console.log(`Orchestration id: ${snapshot.maestroState.orchestration_id ?? "not started"}`);
+  console.log("Runtime tracks:");
+  if (trackEntries.length === 0) {
+    console.log("- none");
+  } else {
+    for (const [trackId, track] of trackEntries) {
+      console.log(`- ${trackId}: ${track.active_gate} [${track.status}]`);
+      if (Array.isArray(track.blockers) && track.blockers.length > 0) {
+        console.log(`  blockers: ${track.blockers.join("; ")}`);
+      }
+    }
+  }
 
-  if (!evaluation.allowed) {
-    const blockers = formatBuildBlockers(evaluation);
-    await writeBuildPlanArtifact({
-      allowed: false,
-      blockers,
-      nextTriggers: formatNextAllowedTriggers(evaluation),
-    });
-    await appendDecision({
-      decision: "Blocked build execution",
-      status: "BLOCKED",
-      evidence: [
-        {
-          kind: "release-state",
-          path: ".ma/release.json",
-        },
-      ],
-      blockers,
-      next_allowed_triggers: formatNextAllowedTriggers(evaluation),
-    });
+  const lockEntries = Object.entries(snapshot.maestroState.downstream_lock_table);
+  console.log("Downstream locks:");
+  if (lockEntries.length === 0) {
+    console.log("- none");
+    return;
+  }
 
+  for (const [gate, lock] of lockEntries) {
+    console.log(`- ${gate}: ${lock.is_locked ? "locked" : "unlocked"}`);
+    if (Array.isArray(lock.locked_by) && lock.locked_by.length > 0) {
+      console.log(`  locked by: ${lock.locked_by.join(", ")}`);
+    }
+    if (lock.unlock_criteria) {
+      console.log(`  unlock criteria: ${lock.unlock_criteria}`);
+    }
+  }
+}
+
+async function runBuild() {
+  const result = await runBuildLane();
+  if (result.status === "BLOCKED") {
     console.error("Build is locked.");
-    for (const blocker of blockers) {
+    for (const blocker of result.blockers) {
       console.error(`- ${blocker}`);
     }
     process.exitCode = 1;
     return;
   }
 
-  const suggestedBranches = ["feature/ui", "feature/api"];
-  await writeBuildPlanArtifact({
-    allowed: true,
-    blockers: [],
-    nextTriggers: ["$build"],
-    suggestedBranches,
-  });
-  await appendDecision({
-    kind: "skill",
-    skill: "$build",
-    decision: "Build gate ready",
-    status: "READY",
-    evidence: [
-      {
-        kind: "release-state",
-        path: ".ma/release.json",
-      },
-      {
-        branches: ["feature/ui", "feature/api"],
-      },
-    ],
-    blockers: [],
-    next_allowed_triggers: ["$build"],
-  });
+  if (result.status === "READY") {
+    const suggestedBranches = result.suggestedBranches ?? [];
+    console.log("Build gate is ready.");
+    console.log("Suggested branches:");
+    for (const branch of suggestedBranches) {
+      console.log(`- ${branch}`);
+    }
+    console.log("Optional worktree commands:");
+    console.log("git worktree add ../implementation feature/implementation");
+    console.log("git worktree add ../verification feature/verification");
+    console.log("Run `ma run '$build'` again to start the bounded build execution substep.");
+    return;
+  }
 
-  await syncStatusUpdates({ build_status: "READY" });
+  if (result.status === "RUNNING") {
+    console.log("Build gate is running the bounded execution substep.");
+    console.log(
+      "Run `ma run '$build'` again to finalize the substep and persist completion evidence.",
+    );
+    return;
+  }
 
-  console.log("Build gate is green.");
-  console.log("Suggested branches:");
-  console.log(`- ${suggestedBranches[0]}`);
-  console.log(`- ${suggestedBranches[1]}`);
-  console.log("Optional worktree commands:");
-  console.log("git worktree add ../ui feature/ui");
-  console.log("git worktree add ../api feature/api");
+  console.log("Build gate completed the bounded execution substep.");
+  console.log("Next step: ma merge <feature/*> development");
 }
 
 async function runMerge(sourceBranch, targetBranch) {
@@ -149,7 +185,7 @@ async function runMerge(sourceBranch, targetBranch) {
   }
 
   if (!canMarkBuildDone(releaseState)) {
-    throw new Error("Merge is blocked until build status is READY or RUNNING");
+    throw new Error("Merge is blocked until build status is DONE");
   }
 
   await appendDecision({
@@ -162,7 +198,6 @@ async function runMerge(sourceBranch, targetBranch) {
   });
 
   await syncStatusUpdates({
-    build_status: "DONE",
     merge_status: "MERGED_TO_DEVELOPMENT",
   });
 
@@ -259,6 +294,111 @@ async function main() {
     return;
   }
 
+  if (command === "core-ingest") {
+    await runInit();
+    const manifest = await ingestCoreSources({ refresh: rest.includes("--refresh") });
+    console.log("Core sources ingested");
+    console.log(`Status: ${manifest.status}`);
+    console.log(`Runtime fetch required: ${manifest.runtime_fetch_required}`);
+    for (const source of manifest.sources) {
+      console.log(`${source.id}: ${source.status} ${source.local_path ?? source.repo}`);
+    }
+    if (manifest.errors?.length > 0) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (command === "obsidian-index") {
+    const vaultPath = arg ?? process.env.MA_OBSIDIAN_VAULT;
+    if (!vaultPath) {
+      throw new Error("Obsidian vault path required: ma obsidian-index <vault-path>");
+    }
+    await runInit();
+    const index = await writeObsidianVaultIndex({ vaultPath });
+    console.log("Obsidian vault indexed");
+    console.log(`Vault: ${index.vault_path}`);
+    console.log(`Notes: ${index.note_count}`);
+    console.log(`Tags: ${index.tags.length}`);
+    console.log(`Unresolved links: ${index.unresolved_links.length}`);
+    return;
+  }
+
+  if (command === "obsidian") {
+    const [action, vaultPath, notePath, ...contentParts] = rest;
+    if (!action || !vaultPath) {
+      throw new Error(
+        "Usage: ma obsidian list|read|create|update|delete|plugin-install <vault-path> [note-path] [content]",
+      );
+    }
+    await runInit();
+    if (action === "plugin-install") {
+      const receipt = await installObsidianPlugin({ vaultPath });
+      await appendObsidianOperationReceipt({
+        record_type: "obsidian_vault_operation",
+        operation: "plugin_install",
+        records_as: "vault_context",
+        build_evidence: false,
+        authority_boundary: "$maestro_or_owning_lane",
+        vault_path: receipt.vault_path,
+        relative_path: ".obsidian/plugins/meta-architect",
+        content_sha256: "0".repeat(64),
+        char_count: receipt.installed_files.join("\n").length,
+        performed_at: new Date().toISOString(),
+      });
+      console.log("Obsidian plugin installed");
+      console.log(`Vault: ${receipt.vault_path}`);
+      console.log(`Plugin: ${receipt.plugin_path}`);
+      console.log(`Enabled: ${receipt.enabled}`);
+      console.log(`Files: ${receipt.installed_files.join(", ")}`);
+      return;
+    }
+    if (action === "list") {
+      const list = await listObsidianNotes({ vaultPath });
+      console.log(`Obsidian notes: ${list.notes.length}`);
+      for (const note of list.notes) {
+        console.log(note);
+      }
+      return;
+    }
+    if (action === "read") {
+      const note = await readObsidianNote({ vaultPath, notePath });
+      console.log(`Obsidian note: ${note.relative_path}`);
+      console.log(note.content);
+      return;
+    }
+    if (action === "create") {
+      const receipt = await createObsidianNote({
+        vaultPath,
+        notePath,
+        content: contentParts.join(" "),
+      });
+      await appendObsidianOperationReceipt(receipt);
+      await writeObsidianVaultIndex({ vaultPath });
+      console.log(`Obsidian note created: ${receipt.relative_path}`);
+      return;
+    }
+    if (action === "update") {
+      const receipt = await updateObsidianNote({
+        vaultPath,
+        notePath,
+        content: contentParts.join(" "),
+      });
+      await appendObsidianOperationReceipt(receipt);
+      await writeObsidianVaultIndex({ vaultPath });
+      console.log(`Obsidian note updated: ${receipt.relative_path}`);
+      return;
+    }
+    if (action === "delete") {
+      const receipt = await deleteObsidianNote({ vaultPath, notePath });
+      await appendObsidianOperationReceipt(receipt);
+      await writeObsidianVaultIndex({ vaultPath });
+      console.log(`Obsidian note deleted: ${receipt.relative_path}`);
+      return;
+    }
+    throw new Error(`Unknown Obsidian action: ${action}`);
+  }
+
   if (command === "sdk-path") {
     process.stdout.write(`${getSupportBundleRoot()}\n`);
     return;
@@ -266,7 +406,22 @@ async function main() {
 
   if (command === "status") {
     const releaseState = await loadReleaseState();
-    printStatus(releaseState);
+    await printStatus(releaseState);
+    if (rest.includes("--maestro-view")) {
+      await printMaestroView();
+    }
+    return;
+  }
+
+  if (command === "verify" && rest.includes("--architect")) {
+    const review = await runExternalArchitectReview({
+      prompt:
+        "Review the current Meta-Architect runtime and release-state outputs for architectural soundness.",
+    });
+    console.log(`Architect verdict: ${review.verdict}`);
+    if (review.summary) {
+      console.log(review.summary);
+    }
     return;
   }
 
@@ -283,14 +438,20 @@ async function main() {
   }
 
   if (command === "run" && arg === "$maestro") {
-    await runMaestro();
+    await runMaestro({
+      autoHeal: rest.includes("--auto-heal"),
+      parallel: rest.includes("--parallel"),
+    });
     console.log("$maestro complete");
     return;
   }
 
+  if (command === "run" && arg === "$meta-architect") {
+    throw new Error("$meta-architect has been removed as a separate surface; use $maestro");
+  }
+
   if (command === "run" && arg === "$build") {
-    const releaseState = await loadReleaseState();
-    await runBuild(releaseState);
+    await runBuild();
     return;
   }
 

package/data/clone-data.ledger.json

@@ -0,0 +1,41 @@
+{
+  "schemaVersion": "1.0.0",
+  "record_type": "clone_data_ledger",
+  "product": "Meta-Architect",
+  "package": "@jstn-sdk/ma",
+  "release_version": "0.1.13",
+  "records_as": "production_evidence",
+  "build_evidence": true,
+  "entries": [
+    {
+      "id": "clone-data-proof",
+      "path": "data/clone-data.proof.json",
+      "type": "proof",
+      "purpose": "Records the clone-data proof claims and verification commands.",
+      "required": true
+    },
+    {
+      "id": "clone-data-ledger",
+      "path": "data/clone-data.ledger.json",
+      "type": "ledger",
+      "purpose": "Tracks clone-data artifact inventory and package visibility.",
+      "required": true
+    },
+    {
+      "id": "clone-data-rvf",
+      "path": "data/clone-data.rvf",
+      "type": "runtime_verification_file",
+      "purpose": "Defines pass/fail verification criteria for clone-data artifacts.",
+      "required": true
+    }
+  ],
+  "package_visibility": {
+    "package_json_files_entry": "data/",
+    "pack_dry_run_required": true
+  },
+  "integrity_policy": {
+    "empty_files_allowed": false,
+    "placeholder_claims_allowed": false,
+    "must_reference_real_paths": true
+  }
+}

package/data/clone-data.proof.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": "1.0.0",
+  "record_type": "clone_data_proof",
+  "product": "Meta-Architect",
+  "package": "@jstn-sdk/ma",
+  "release_version": "0.1.13",
+  "records_as": "production_evidence",
+  "build_evidence": true,
+  "subject": "clone data install and package proof contract",
+  "claims": [
+    {
+      "id": "jsdelivr_posix_installer",
+      "claim": "The recommended POSIX CLI install path is backed by a repository script addressable through jsDelivr.",
+      "evidence": [
+        "scripts/install.sh",
+        "README.md",
+        "docs/getting-started.md",
+        "docs/onboarding.md",
+        "docs/skills.md",
+        "plugins/meta-architect/README.md",
+        "docs/release-spec.md"
+      ]
+    },
+    {
+      "id": "clone_data_artifacts",
+      "claim": "Clone-data proof, ledger, and RVF artifacts exist as package-visible data files.",
+      "evidence": [
+        "data/clone-data.proof.json",
+        "data/clone-data.ledger.json",
+        "data/clone-data.rvf",
+        "package.json files includes data/"
+      ]
+    },
+    {
+      "id": "release_gate_contract",
+      "claim": "Release verification must preserve the jsDelivr installer and canonical npm install command in public install docs.",
+      "evidence": ["scripts/release-verify.js", "npm run release:check"]
+    }
+  ],
+  "verification_commands": [
+    "sh -n scripts/install.sh",
+    "node scripts/release-verify.js",
+    "node --test test/clone-data-artifacts.test.js",
+    "npm run release:check"
+  ],
+  "authority_boundary": {
+    "may_mutate_release_state": false,
+    "authoritative_changes_return_through": "$maestro_or_owning_lane"
+  }
+}

package/data/clone-data.rvf

@@ -0,0 +1,37 @@
+# Clone Data RVF
+
+schemaVersion: 1.0.0
+record_type: clone_data_runtime_verification_file
+product: Meta-Architect
+package: @jstn-sdk/ma
+release_version: 0.1.13
+
+## Purpose
+
+This RVF defines the pass criteria for the clone-data proof and ledger artifacts.
+
+## Required Artifacts
+
+- `data/clone-data.proof.json`
+- `data/clone-data.ledger.json`
+- `data/clone-data.rvf`
+
+## Pass Criteria
+
+- Proof JSON has `record_type: clone_data_proof`.
+- Ledger JSON has `record_type: clone_data_ledger`.
+- Both JSON files use `schemaVersion: 1.0.0`.
+- Both JSON files record as `production_evidence`.
+- Ledger entries reference all required clone-data artifacts.
+- `package.json` includes `data/` so clone-data artifacts are visible in package dry-runs.
+- `scripts/install.sh` remains POSIX-shell syntax valid.
+- Public install docs preserve the jsDelivr one-line installer.
+
+## Verification Commands
+
+```bash
+sh -n scripts/install.sh
+node scripts/release-verify.js
+node --test test/clone-data-artifacts.test.js
+npm run release:check
+```

package/docs/README.md

@@ -5,19 +5,25 @@ Meta-Architect documentation is organized by operator task.
 ## Start here
 
 - [Getting Started](./getting-started.md)
+- [Production Demo Guide](../DEMO.md)
+- [Coverage Matrix](../COVERAGE.md)
 - [Release Spec](./release-spec.md)
 - [Skills Reference](./skills.md)
+- umbrella, gated lanes, and helper skill distinctions live in the Skills Reference
 - [Installed Support Bundle](./installed-sdk.md)
 
 ## Packaging and installation
 
 - [Skills Publishing](./skills-publishing.md)
+- published helper-skill and plugin-mirror expectations live in Skills Publishing
+- Linux-native distro package expectations live in the Release Spec and release-readiness docs
 - [MCP Setup](./mcp-setup.md)
 - [Plugin Bundle](../plugins/meta-architect/README.md)
 
 ## QA and readiness
 
-- [Release Readiness 0.1.11](./qa/release-readiness-0.1.11.md)
+- [Release Readiness 0.1.13](./qa/release-readiness-0.1.13.md)
+- [Release Issue Gates 0.1.13](./qa/release-issue-gates-0.1.13.json)
 
 ## Repo structure references