role-os 1.0.0

package/src/review.mjs

@@ -0,0 +1,94 @@
+import { resolve, dirname, basename } from "node:path";
+import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
+import { askRequired, askWithDefault, closePrompts } from "./prompts.mjs";
+
+const VERDICTS = ["accept", "accept-with-notes", "reject", "blocked"];
+
+export async function reviewCommand(args) {
+  const packetFile = args[0];
+  const verdict = args[1];
+
+  if (!packetFile || !verdict) {
+    const err = new Error(`Usage: roleos review <packet-file> <verdict>\nVerdicts: ${VERDICTS.join(" | ")}`);
+    err.exitCode = 1;
+    err.hint = "Provide a packet file and a verdict.";
+    throw err;
+  }
+
+  if (!VERDICTS.includes(verdict)) {
+    const err = new Error(`Unknown verdict: ${verdict}\nVerdicts: ${VERDICTS.join(" | ")}`);
+    err.exitCode = 1;
+    err.hint = `Valid verdicts: ${VERDICTS.join(", ")}`;
+    throw err;
+  }
+
+  const content = readFileSafe(packetFile);
+  if (content === null) {
+    const err = new Error(`Packet not found: ${packetFile}`);
+    err.exitCode = 1;
+    err.hint = "Check the file path and try again.";
+    throw err;
+  }
+
+  // Extract task ID from the packet
+  const taskIdMatch = content.match(/## Task ID\n(.+)/);
+  const taskId = taskIdMatch ? taskIdMatch[1].trim() : basename(packetFile, ".md");
+
+  console.log(`\nroleos review — ${verdict}\n`);
+  console.log(`Packet: ${packetFile}`);
+  console.log(`Task ID: ${taskId}\n`);
+
+  const reviewer = await askWithDefault("Reviewer role", "Critic Reviewer");
+  const reason = await askRequired("Reason (tied to contract/evidence)");
+
+  let corrections = "";
+  if (verdict === "reject" || verdict === "accept-with-notes") {
+    corrections = await askRequired("Required corrections");
+  }
+
+  const nextOwner = await askWithDefault("Next owner", verdict === "accept" ? "None — done" : "");
+
+  // Contract check
+  console.log("\nContract check (y/n for each):");
+  const scopeRespected = await askWithDefault("  Scope respected?", "y");
+  const outputComplete = await askWithDefault("  Output shape complete?", "y");
+  const qualityMet = await askWithDefault("  Quality bar met?", "y");
+  const risksSurfaced = await askWithDefault("  Risks surfaced honestly?", "y");
+  const readyForNext = await askWithDefault("  Ready for next stage?", verdict === "accept" ? "y" : "n");
+
+  const verdictContent = `# Review Verdict
+
+## Reviewer
+${reviewer}
+
+## Task ID
+${taskId}
+
+## Verdict
+${verdict}
+
+## Why
+${reason}
+
+## Contract Check
+- Scope respected? ${scopeRespected}
+- Output shape complete? ${outputComplete}
+- Quality bar met? ${qualityMet}
+- Risks surfaced honestly? ${risksSurfaced}
+- Ready for next stage? ${readyForNext}
+
+${corrections ? `## Required Corrections\n${corrections}\n` : ""}## Next Owner
+${nextOwner}
+`;
+
+  closePrompts();
+
+  // Write verdict as companion file
+  const packetBase = basename(packetFile, ".md");
+  const verdictPath = resolve(dirname(packetFile), `${packetBase}.verdict.md`);
+
+  const wrote = writeFileSafe(verdictPath, verdictContent, { force: true });
+  if (wrote) {
+    console.log(`\nVerdict recorded: ${verdictPath}`);
+  }
+}

package/src/route.mjs

@@ -0,0 +1,169 @@
+import { existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { readFileSafe } from "./fs-utils.mjs";
+
+const ROLE_KEYWORDS = {
+  "Product Strategist": [
+    "product", "scope", "intent", "prioritize", "tradeoff", "framing",
+    "feature shaping", "user value",
+  ],
+  "UI Designer": [
+    "ui", "screen", "layout", "hierarchy", "interaction", "visual",
+    "design", "flow", "component",
+  ],
+  "Backend Engineer": [
+    "api", "server", "data", "persistence", "contract", "model",
+    "migration", "bridge", "wiring", "session", "state",
+  ],
+  "Frontend Developer": [
+    "frontend", "render", "component", "client", "tui", "display",
+    "view", "screen implementation",
+  ],
+  "Test Engineer": [
+    "test", "verify", "regression", "coverage", "assertion", "edge case",
+  ],
+  "Launch Copywriter": [
+    "release notes", "launch", "messaging", "copy", "positioning",
+    "announcement",
+  ],
+};
+
+const CHAINS = {
+  feature: [
+    "Orchestrator", "Product Strategist", "UI Designer",
+    "Backend Engineer", "Frontend Developer", "Test Engineer",
+    "Critic Reviewer",
+  ],
+  integration: [
+    "Orchestrator", "Backend Engineer", "Frontend Developer",
+    "Test Engineer", "Critic Reviewer",
+  ],
+  identity: [
+    "Orchestrator", "Product Strategist", "UI Designer",
+    "Frontend Developer", "Test Engineer", "Critic Reviewer",
+  ],
+};
+
+function detectType(content) {
+  const lower = content.toLowerCase();
+
+  const typeMatch = content.match(/## Packet Type\n(\w+)/);
+  if (typeMatch && CHAINS[typeMatch[1]]) {
+    return typeMatch[1];
+  }
+
+  if (lower.includes("contamination") || lower.includes("residue") || lower.includes("identity") || lower.includes("purge")) {
+    return "identity";
+  }
+  if (lower.includes("wiring") || lower.includes("bridge") || lower.includes("integration") || lower.includes("seam")) {
+    return "integration";
+  }
+  return "feature";
+}
+
+function scoreRoles(content) {
+  const lower = content.toLowerCase();
+  const scores = {};
+
+  for (const [role, keywords] of Object.entries(ROLE_KEYWORDS)) {
+    let score = 0;
+    for (const kw of keywords) {
+      if (lower.includes(kw)) score++;
+    }
+    if (score > 0) scores[role] = score;
+  }
+
+  return scores;
+}
+
+function recommendChain(type, scores) {
+  const base = CHAINS[type] || CHAINS.feature;
+  const relevant = new Set(Object.keys(scores));
+
+  // Always keep Orchestrator and Critic Reviewer
+  const chain = base.filter((role) => {
+    if (role === "Orchestrator" || role === "Critic Reviewer") return true;
+    if (relevant.has(role)) return true;
+    // Keep roles in the base chain even without keyword hits —
+    // the type-based chain is the proven default
+    return true;
+  });
+
+  return chain;
+}
+
+function extractFileRefs(content, packetDir) {
+  const refs = [];
+  const inputsMatch = content.match(/## Inputs\n([\s\S]*?)(?=\n## |\n---)/);
+  if (!inputsMatch) return refs;
+
+  const inputsSection = inputsMatch[1];
+  // Match file paths — look for patterns like path/to/file.ext or ./path/to/file
+  const pathPattern = /(?:^|\s|`)((?:\.\/|\.\.\/|[a-zA-Z][\w\-]*\/)[^\s`\n,)]+\.\w+)/gm;
+  let match;
+  while ((match = pathPattern.exec(inputsSection)) !== null) {
+    const ref = match[1];
+    const resolved = resolve(dirname(packetDir), "..", "..", ref);
+    refs.push({
+      ref,
+      resolved,
+      exists: existsSync(resolved),
+    });
+  }
+
+  return refs;
+}
+
+export async function routeCommand(args) {
+  const packetFile = args[0];
+
+  if (!packetFile) {
+    const err = new Error("Usage: roleos route <packet-file>");
+    err.exitCode = 1;
+    err.hint = "Provide the path to a packet file.";
+    throw err;
+  }
+
+  const content = readFileSafe(packetFile);
+  if (content === null) {
+    const err = new Error(`Packet not found: ${packetFile}`);
+    err.exitCode = 1;
+    err.hint = "Check the file path and try again.";
+    throw err;
+  }
+
+  const type = detectType(content);
+  const scores = scoreRoles(content);
+  const chain = recommendChain(type, scores);
+  const fileRefs = extractFileRefs(content, resolve(packetFile));
+
+  console.log(`\nroleos route — ${packetFile}\n`);
+  console.log(`Detected type: ${type}`);
+  console.log(`\nRecommended chain (${chain.length} roles):`);
+  chain.forEach((role, i) => {
+    console.log(`  ${i + 1}. ${role}`);
+  });
+
+  if (Object.keys(scores).length > 0) {
+    console.log(`\nRole signals:`);
+    for (const [role, score] of Object.entries(scores).sort((a, b) => b[1] - a[1])) {
+      console.log(`  ${role}: ${score} keyword hit${score > 1 ? "s" : ""}`);
+    }
+  }
+
+  if (fileRefs.length > 0) {
+    console.log(`\nDependency verification:`);
+    let hasIssues = false;
+    for (const ref of fileRefs) {
+      const status = ref.exists ? "OK" : "MISSING";
+      const marker = ref.exists ? "+" : "!";
+      console.log(`  ${marker} ${ref.ref} — ${status}`);
+      if (!ref.exists) hasIssues = true;
+    }
+    if (hasIssues) {
+      console.log(`\n  WARNING: Some referenced files are missing. Verify before proceeding.`);
+    }
+  }
+
+  console.log(`\nNext: assign roles and begin execution, or adjust the chain.`);
+}

package/src/status.mjs

@@ -0,0 +1,352 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
+
+// --- Parsers ---
+
+function parsePacket(filePath) {
+  const content = readFileSafe(filePath);
+  if (!content) return null;
+
+  const get = (heading) => {
+    const re = new RegExp(`## ${heading}\\n([\\s\\S]*?)(?=\\n## |\\n---|$)`);
+    const m = content.match(re);
+    return m ? m[1].trim() : null;
+  };
+
+  const taskId = get("Task ID");
+  const title = get("Title");
+  const type = get("Packet Type");
+  const openQuestions = get("Open Questions");
+  const assignedRole = get("Assigned Role");
+
+  const hasContent = taskId || title;
+  if (!hasContent) return { malformed: true, file: basename(filePath) };
+
+  // Check for companion verdict
+  const verdictPath = filePath.replace(/\.md$/, ".verdict.md");
+  const verdict = parseVerdict(verdictPath);
+
+  const hasBlockers = openQuestions &&
+    !openQuestions.startsWith("<!--") &&
+    openQuestions.length > 0;
+
+  return {
+    file: basename(filePath),
+    taskId: taskId || basename(filePath, ".md"),
+    title: title || "(untitled)",
+    type: type || "unknown",
+    assignedRole: assignedRole && !assignedRole.startsWith("<!--") ? assignedRole : null,
+    openQuestions: hasBlockers ? openQuestions : null,
+    verdict,
+    status: verdict ? (verdict.verdict === "accept" || verdict.verdict === "accept-with-notes" ? "completed" : verdict.verdict) : "active",
+  };
+}
+
+function parseVerdict(filePath) {
+  const content = readFileSafe(filePath);
+  if (!content) return null;
+
+  const get = (heading) => {
+    const re = new RegExp(`## ${heading}\\n([\\s\\S]*?)(?=\\n## |$)`);
+    const m = content.match(re);
+    return m ? m[1].trim() : null;
+  };
+
+  const verdict = get("Verdict");
+  const reviewer = get("Reviewer");
+  const why = get("Why");
+  const taskId = get("Task ID");
+  const nextOwner = get("Next Owner");
+
+  if (!verdict) return { malformed: true, file: basename(filePath) };
+
+  return {
+    file: basename(filePath),
+    taskId,
+    verdict,
+    reviewer: reviewer || "unknown",
+    why: why || "",
+    nextOwner: nextOwner || null,
+  };
+}
+
+// --- Data collection ---
+
+function collectPackets(claudeDir) {
+  const packetsDir = join(claudeDir, "packets");
+  if (!existsSync(packetsDir)) return [];
+
+  const files = readdirSync(packetsDir)
+    .filter((f) => f.endsWith(".md") && !f.endsWith(".verdict.md"))
+    .sort();
+
+  return files
+    .map((f) => parsePacket(join(packetsDir, f)))
+    .filter(Boolean);
+}
+
+function checkContextHealth(claudeDir) {
+  const contextFiles = [
+    "context/product-brief.md",
+    "context/repo-map.md",
+    "context/current-priorities.md",
+    "context/brand-rules.md",
+  ];
+
+  return contextFiles.map((f) => ({
+    file: f,
+    exists: existsSync(join(claudeDir, f)),
+  }));
+}
+
+function checkSpineHealth(claudeDir) {
+  const checks = [
+    "agents/core/orchestrator.md",
+    "agents/core/critic-reviewer.md",
+    "schemas/task-packet.md",
+    "policy/done-definition.md",
+    "workflows/ship-feature.md",
+  ];
+
+  return checks.map((f) => ({
+    file: f,
+    exists: existsSync(join(claudeDir, f)),
+  }));
+}
+
+// --- Health warnings ---
+
+function getWarnings(packets, contextHealth, spineHealth) {
+  const warnings = [];
+
+  // Missing context files
+  for (const c of contextHealth) {
+    if (!c.exists) warnings.push(`Missing context: ${c.file}`);
+  }
+
+  // Missing spine files
+  for (const s of spineHealth) {
+    if (!s.exists) warnings.push(`Missing spine: ${s.file}`);
+  }
+
+  // Malformed packets
+  for (const p of packets) {
+    if (p.malformed) warnings.push(`Malformed packet: ${p.file}`);
+  }
+
+  // Active packets with no review
+  const active = packets.filter((p) => !p.malformed && p.status === "active");
+  if (active.length > 3) {
+    warnings.push(`${active.length} active packets — consider reviewing before adding more`);
+  }
+
+  // Verdicts for missing packets (orphaned verdict files)
+  const packetsDir = join(".", ".claude", "packets");
+  if (existsSync(packetsDir)) {
+    const verdictFiles = readdirSync(packetsDir).filter((f) => f.endsWith(".verdict.md"));
+    for (const vf of verdictFiles) {
+      const packetFile = vf.replace(".verdict.md", ".md");
+      if (!existsSync(join(packetsDir, packetFile))) {
+        warnings.push(`Orphaned verdict: ${vf} (no matching packet)`);
+      }
+    }
+  }
+
+  // No work at all
+  if (packets.length === 0) {
+    warnings.push("No packets found — create one with 'roleos packet new feature'");
+  }
+
+  return warnings;
+}
+
+// --- Output formatters ---
+
+function formatTerminal(data) {
+  const lines = [];
+  lines.push("roleos status\n");
+
+  // Active packets
+  const active = data.packets.filter((p) => !p.malformed && p.status === "active");
+  lines.push(`Active packets: ${active.length}`);
+  if (active.length > 0) {
+    for (const p of active) {
+      const role = p.assignedRole ? ` [${p.assignedRole}]` : "";
+      lines.push(`  - ${p.title} (${p.type})${role}`);
+      if (p.openQuestions) {
+        lines.push(`    Open: ${p.openQuestions.split("\n")[0].slice(0, 80)}`);
+      }
+    }
+  }
+  lines.push("");
+
+  // Blocked/rejected
+  const blocked = data.packets.filter((p) => !p.malformed && (p.status === "blocked" || p.status === "reject"));
+  if (blocked.length > 0) {
+    lines.push(`Blocked/rejected: ${blocked.length}`);
+    for (const p of blocked) {
+      const why = p.verdict?.why ? ` — ${p.verdict.why.split("\n")[0].slice(0, 60)}` : "";
+      lines.push(`  - ${p.title}${why}`);
+    }
+    lines.push("");
+  }
+
+  // Recent verdicts
+  const withVerdicts = data.packets.filter((p) => !p.malformed && p.verdict && !p.verdict.malformed);
+  if (withVerdicts.length > 0) {
+    lines.push(`Recent verdicts: ${withVerdicts.length}`);
+    const recent = withVerdicts.slice(-5);
+    for (const p of recent) {
+      const v = p.verdict;
+      lines.push(`  - ${p.title}: ${v.verdict} (${v.reviewer})`);
+    }
+    lines.push("");
+  }
+
+  // Completed
+  const completed = data.packets.filter((p) => !p.malformed && p.status === "completed");
+  if (completed.length > 0) {
+    lines.push(`Completed: ${completed.length}`);
+    lines.push("");
+  }
+
+  // Context health
+  const missingContext = data.contextHealth.filter((c) => !c.exists);
+  if (missingContext.length > 0) {
+    lines.push(`Context: ${data.contextHealth.length - missingContext.length}/${data.contextHealth.length} present`);
+  } else {
+    lines.push(`Context: all ${data.contextHealth.length} files present`);
+  }
+  lines.push("");
+
+  // Warnings
+  if (data.warnings.length > 0) {
+    lines.push("Warnings:");
+    for (const w of data.warnings) {
+      lines.push(`  ! ${w}`);
+    }
+    lines.push("");
+  }
+
+  // Summary
+  const total = data.packets.filter((p) => !p.malformed).length;
+  lines.push(`Total: ${total} packet(s) — ${active.length} active, ${completed.length} completed, ${blocked.length} blocked/rejected`);
+
+  return lines.join("\n");
+}
+
+function formatMarkdown(data) {
+  const lines = [];
+  const ts = new Date().toISOString().replace("T", " ").split(".")[0] + " UTC";
+  lines.push(`# Status\n`);
+  lines.push(`Generated: ${ts}\n`);
+
+  // Active
+  const active = data.packets.filter((p) => !p.malformed && p.status === "active");
+  lines.push(`## Active Packets`);
+  if (active.length === 0) {
+    lines.push("None\n");
+  } else {
+    for (const p of active) {
+      const role = p.assignedRole ? ` — ${p.assignedRole}` : "";
+      lines.push(`- **${p.title}** (${p.type})${role}`);
+      if (p.openQuestions) {
+        lines.push(`  - Open: ${p.openQuestions.split("\n")[0]}`);
+      }
+    }
+    lines.push("");
+  }
+
+  // Blockers
+  const blocked = data.packets.filter((p) => !p.malformed && (p.status === "blocked" || p.status === "reject"));
+  lines.push(`## Blockers`);
+  if (blocked.length === 0) {
+    lines.push("None\n");
+  } else {
+    for (const p of blocked) {
+      const why = p.verdict?.why ? `: ${p.verdict.why.split("\n")[0]}` : "";
+      lines.push(`- **${p.title}**${why}`);
+    }
+    lines.push("");
+  }
+
+  // Recent verdicts
+  const withVerdicts = data.packets.filter((p) => !p.malformed && p.verdict && !p.verdict.malformed);
+  lines.push(`## Recent Verdicts`);
+  if (withVerdicts.length === 0) {
+    lines.push("None\n");
+  } else {
+    for (const p of withVerdicts.slice(-5)) {
+      lines.push(`- **${p.title}**: ${p.verdict.verdict} (${p.verdict.reviewer})`);
+    }
+    lines.push("");
+  }
+
+  // Completed
+  const completed = data.packets.filter((p) => !p.malformed && p.status === "completed");
+  lines.push(`## Completed`);
+  if (completed.length === 0) {
+    lines.push("None\n");
+  } else {
+    for (const p of completed) {
+      lines.push(`- ${p.title} (${p.type})`);
+    }
+    lines.push("");
+  }
+
+  // Context health
+  lines.push(`## Context Health`);
+  for (const c of data.contextHealth) {
+    lines.push(`- ${c.exists ? "+" : "!"} ${c.file}`);
+  }
+  lines.push("");
+
+  // Warnings
+  if (data.warnings.length > 0) {
+    lines.push(`## Warnings`);
+    for (const w of data.warnings) {
+      lines.push(`- ${w}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+// --- Command ---
+
+export async function statusCommand(args) {
+  const claudeDir = join(".", ".claude");
+
+  if (!existsSync(claudeDir)) {
+    const err = new Error("No .claude/ directory found. Run 'roleos init' first.");
+    err.exitCode = 1;
+    err.hint = "Run 'roleos init' to scaffold Role OS.";
+    throw err;
+  }
+
+  const packets = collectPackets(claudeDir);
+  const contextHealth = checkContextHealth(claudeDir);
+  const spineHealth = checkSpineHealth(claudeDir);
+  const warnings = getWarnings(packets, contextHealth, spineHealth);
+
+  const data = { packets, contextHealth, spineHealth, warnings };
+
+  const isJson = args.includes("--json");
+  const isWrite = args.includes("--write");
+
+  if (isJson) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  console.log(formatTerminal(data));
+
+  if (isWrite) {
+    const statusDir = join(claudeDir, "status");
+    const indexPath = join(statusDir, "index.md");
+    writeFileSafe(indexPath, formatMarkdown(data), { force: true });
+    console.log(`\nWritten: .claude/status/index.md`);
+  }
+}

package/starter-pack/.claude/workflows/full-treatment.md

@@ -0,0 +1,74 @@
+# Full Treatment
+
+Role OS does not own or redefine the full treatment protocol. The canonical protocol lives in Claude project memory (`memory/full-treatment.md`) and is a 7-phase polish + publish playbook.
+
+## Canonical source
+
+The full treatment is defined in Claude project memory as a 7-phase protocol:
+
+1. Pre-flight + finalize README + hand off translations
+2. Scaffold landing page (Astro site-theme)
+3. Handbook (Starlight docs)
+4. Repo metadata + coverage
+5. Repo Knowledge DB entry
+6. Commit and deploy
+7. Post-deploy verification
+
+Read `memory/full-treatment.md` and `memory/handbook-playbook.md` before starting.
+
+## Gate: Shipcheck runs first
+
+Full treatment does not start until shipcheck passes. Shipcheck is the 31-item quality gate (hard gates A-D block release). The canonical shipcheck reference lives in Claude project memory (`memory/shipcheck.md`).
+
+Order: `npx @mcptoolshop/shipcheck audit` → exits 0 → then full treatment.
+
+No v1.0.0 bump without passing hard gates A-D.
+
+## Role chain per phase
+
+Each treatment phase maps to specific roles:
+
+### Phase 1 — Pre-flight + README + translations
+- **Repo Researcher** — verify repo state, Pages config, package.json
+- **Brand Guardian** — verify logo, README identity, footer
+- **Repo Translator** — hand off and verify translations
+
+### Phase 2 — Scaffold landing page
+- **Docs Architect** — site-theme init, site-config.ts
+- **Frontend Developer** — landing page content and build
+- **Brand Guardian** — verify brand alignment
+
+### Phase 3 — Handbook (Starlight docs)
+- **Docs Architect** — Starlight setup, page structure, content
+- **Repo Translator** — docs translation if applicable
+
+### Phase 4 — Repo metadata + coverage
+- **Metadata Curator** — GitHub metadata, badges, manifest
+- **Coverage Auditor** — test coverage assessment, CI integration
+
+### Phase 5 — Repo Knowledge DB entry
+- **Repo Researcher** — thesis, architecture, relationships
+- **Metadata Curator** — verify entry completeness
+
+### Phase 6 — Commit and deploy
+- **Release Engineer** — staging, version, tag, push
+
+### Phase 7 — Post-deploy verification
+- **Deployment Verifier** — landing page, handbook, package, badges, translations
+
+### Final gate
+- **Critic Reviewer** — accept or reject treatment completeness
+
+## What Role OS adds
+
+- Explicit role ownership for each treatment phase
+- Structured handoffs between phases
+- Review gate on treatment completeness
+- Routing and escalation law
+
+## What Role OS does not own
+
+- The treatment protocol itself
+- The shipcheck gate
+- Claude project memory
+- Treatment history and repo facts (those live in Claude project memory)