role-os 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.7.0
+
+### Added
+
+#### Completion Proof (Phase R)
+- `roleos artifacts` CLI command: list, show, validate, chain subcommands
+- 13 new CLI integration tests for artifact inspection
+- Real task completion missions through the full stack
+
+#### Completion Proof Evidence
+- R1-1 Feature mission: `roleos artifacts` command shipped through feature pack
+  - Pack: feature (high confidence, correct)
+  - Chain: 5 roles, 0 escalations, 1 minor correction
+  - Artifact contracts: all 4 used and valid
+- R1-2 Bugfix mission: README.zh.md npm anomaly
+  - Diagnosed correctly: npm auto-includes README* regardless of files field
+  - Escalated honestly: fix requires structural decision (translation file organization)
+  - Not force-closed: deferred to treatment pass
+
+### Evidence
+- 398 tests, zero failures
+- 3 missions run through the full stack
+- Completion metrics recorded per mission
+
 ## 1.6.0
 
 ### Added

package/README.md

@@ -192,7 +192,8 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 - v1.3.0: Outcome calibration, mixed-task decomposition, composite execution, adaptive replanning. 317 tests.
 - v1.4.0: Session spine — `roleos init claude`, `roleos doctor`, route cards, /roleos-route + /roleos-review + /roleos-status commands. 335 tests.
 - v1.5.0: Hook spine — 5 lifecycle hooks for runtime enforcement. 358 tests.
-- **v1.6.0**: Artifact spine — 20 per-role artifact contracts, 7 pack handoff contracts, structural validation, chain completeness checks. 385 tests.
+- v1.6.0: Artifact spine — 20 per-role artifact contracts, 7 pack handoff contracts, structural validation. 385 tests.
+- **v1.7.0**: Completion proof — real tasks run through the full stack. `roleos artifacts` CLI. Honest escalation on structural fixes. 398 tests.
 
 ## License
 

package/bin/roleos.mjs

@@ -10,6 +10,7 @@ import { reviewCommand } from "../src/review.mjs";
 import { statusCommand } from "../src/status.mjs";
 import { packsCommand } from "../src/packs-cmd.mjs";
 import { scaffoldClaude, doctor, formatDoctor } from "../src/session.mjs";
+import { artifactsCommand } from "../src/artifacts-cmd.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
@@ -30,6 +31,10 @@ Usage:
   roleos packs list                  List all available team packs
   roleos packs suggest <packet-file> Suggest a pack for a packet
   roleos packs show <pack-key>       Show full detail for a named pack
+  roleos artifacts                   List all role artifact contracts
+  roleos artifacts show <role>       Show artifact contract for a role
+  roleos artifacts validate <role> <file>  Validate a file against a contract
+  roleos artifacts chain <pack>      Show pack handoff flow
   roleos doctor                      Verify repo is wired for Role OS sessions
   roleos help                        Show this help
 
@@ -103,6 +108,9 @@ try {
     case "packs":
       await packsCommand(args);
       break;
+    case "artifacts":
+      await artifactsCommand(args);
+      break;
     case "help":
     case "--help":
     case "-h":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "role-os",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Role OS — a multi-Claude operating system where 31 specialized roles execute work through contracts, conflict detection, escalation, and structured evidence. 7 proven team packs for common task families.",
   "homepage": "https://mcp-tool-shop-org.github.io/role-os/",
   "bugs": {

package/src/artifacts-cmd.mjs

@@ -0,0 +1,180 @@
+/**
+ * CLI surface for artifact contracts — roleos artifacts
+ *
+ * Subcommands:
+ * - artifacts (bare) — list all roles with contracts
+ * - artifacts show <role> — display artifact contract
+ * - artifacts validate <role> <file> — validate file against contract
+ * - artifacts chain <pack> — show pack handoff flow
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import {
+  ROLE_ARTIFACT_CONTRACTS,
+  PACK_HANDOFF_CONTRACTS,
+  validateArtifact,
+  getArtifactContract,
+  getHandoffContract,
+  formatArtifactValidation,
+  formatPackChain,
+  validatePackChain,
+} from "./artifacts.mjs";
+
+/**
+ * Main command handler.
+ * @param {string[]} args
+ */
+export async function artifactsCommand(args) {
+  const sub = args[0];
+
+  if (!sub || sub === "list") {
+    runList();
+  } else if (sub === "show") {
+    runShow(args.slice(1));
+  } else if (sub === "validate") {
+    runValidate(args.slice(1));
+  } else if (sub === "chain") {
+    runChain(args.slice(1));
+  } else {
+    const err = new Error(`Unknown artifacts subcommand: "${sub}"`);
+    err.exitCode = 1;
+    err.hint = "Valid subcommands: list, show <role>, validate <role> <file>, chain <pack>";
+    throw err;
+  }
+}
+
+function runList() {
+  const roles = Object.entries(ROLE_ARTIFACT_CONTRACTS);
+  console.log(`\nRole artifact contracts (${roles.length} roles)\n`);
+  console.log(`${"Role".padEnd(25)} ${"Artifact Type".padEnd(22)} ${"Required".padEnd(8)} Consumed By`);
+  console.log(`${"─".repeat(25)} ${"─".repeat(22)} ${"─".repeat(8)} ${"─".repeat(30)}`);
+
+  for (const [role, contract] of roles) {
+    const consumers = contract.consumedBy.length > 0 ? contract.consumedBy.join(", ") : "terminal";
+    console.log(
+      `${role.padEnd(25)} ${contract.artifactType.padEnd(22)} ${String(contract.requiredSections.length).padEnd(8)} ${consumers}`
+    );
+  }
+}
+
+function runShow(args) {
+  if (args.length === 0) {
+    const err = new Error("Missing role name.");
+    err.exitCode = 1;
+    err.hint = "Usage: roleos artifacts show <role-name>";
+    throw err;
+  }
+
+  const input = args.join(" ");
+  const roleName = resolveRoleName(input);
+  if (!roleName) {
+    const err = new Error(`No artifact contract for role "${input}".`);
+    err.exitCode = 1;
+    err.hint = `Available roles: ${Object.keys(ROLE_ARTIFACT_CONTRACTS).join(", ")}`;
+    throw err;
+  }
+
+  const contract = getArtifactContract(roleName);
+
+  console.log(`\nArtifact Contract — ${roleName}\n`);
+  console.log(`Type: ${contract.artifactType}`);
+  console.log(`Required sections: ${contract.requiredSections.join(", ")}`);
+  if (contract.optionalSections.length > 0) {
+    console.log(`Optional sections: ${contract.optionalSections.join(", ")}`);
+  }
+  if (contract.requiredEvidence.length > 0) {
+    console.log(`Required evidence: ${contract.requiredEvidence.join(", ")}`);
+  }
+  console.log(`Consumed by: ${contract.consumedBy.length > 0 ? contract.consumedBy.join(", ") : "terminal (no downstream consumer)"}`);
+  console.log(`Completion rule: ${contract.completionRule}`);
+}
+
+function runValidate(args) {
+  if (args.length < 2) {
+    const err = new Error("Missing arguments.");
+    err.exitCode = 1;
+    err.hint = "Usage: roleos artifacts validate <role-name> <file-path>";
+    throw err;
+  }
+
+  // Last arg is the file, everything before is the role name
+  const filePath = args[args.length - 1];
+  const roleArgs = args.slice(0, -1);
+  const roleName = resolveRoleName(roleArgs.join(" "));
+
+  if (!roleName) {
+    const err = new Error(`Unknown role: "${roleArgs.join(" ")}".`);
+    err.exitCode = 1;
+    err.hint = `Available roles: ${Object.keys(ROLE_ARTIFACT_CONTRACTS).join(", ")}`;
+    throw err;
+  }
+
+  if (!existsSync(filePath)) {
+    const err = new Error(`File not found: "${filePath}".`);
+    err.exitCode = 1;
+    err.hint = "Provide a path to the artifact file to validate.";
+    throw err;
+  }
+
+  const content = readFileSync(filePath, "utf-8");
+  const validation = validateArtifact(roleName, content);
+  console.log(formatArtifactValidation(roleName, validation));
+
+  if (!validation.valid) {
+    process.exitCode = 1;
+  }
+}
+
+function runChain(args) {
+  const packName = args[0];
+  if (!packName) {
+    const err = new Error("Missing pack name.");
+    err.exitCode = 1;
+    err.hint = `Usage: roleos artifacts chain <pack-name>. Available: ${Object.keys(PACK_HANDOFF_CONTRACTS).join(", ")}`;
+    throw err;
+  }
+
+  const contract = getHandoffContract(packName);
+  if (!contract) {
+    const err = new Error(`No handoff contract for pack "${packName}".`);
+    err.exitCode = 1;
+    err.hint = `Available packs: ${Object.keys(PACK_HANDOFF_CONTRACTS).join(", ")}`;
+    throw err;
+  }
+
+  console.log(`\nHandoff Contract — ${packName} pack\n`);
+  console.log(`${"Step".padEnd(5)} ${"Role".padEnd(25)} ${"Produces".padEnd(22)} Consumed By`);
+  console.log(`${"─".repeat(5)} ${"─".repeat(25)} ${"─".repeat(22)} ${"─".repeat(25)}`);
+
+  contract.flow.forEach((step, i) => {
+    const consumer = step.consumedBy || "terminal";
+    console.log(
+      `${String(i + 1).padEnd(5)} ${step.role.padEnd(25)} ${step.produces.padEnd(22)} ${consumer}`
+    );
+  });
+}
+
+/**
+ * Resolve a role name from user input.
+ * Handles both exact names ("Product Strategist") and slug forms ("product-strategist").
+ */
+function resolveRoleName(input) {
+  if (!input || !input.trim()) return null;
+  const trimmed = input.trim();
+
+  // Exact match
+  if (ROLE_ARTIFACT_CONTRACTS[trimmed]) return trimmed;
+
+  // Case-insensitive match
+  for (const role of Object.keys(ROLE_ARTIFACT_CONTRACTS)) {
+    if (role.toLowerCase() === trimmed.toLowerCase()) return role;
+  }
+
+  // Slug match (product-strategist → Product Strategist)
+  const slugToName = trimmed.replace(/-/g, " ");
+  for (const role of Object.keys(ROLE_ARTIFACT_CONTRACTS)) {
+    if (role.toLowerCase() === slugToName.toLowerCase()) return role;
+  }
+
+  return null;
+}