role-os 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 1.1.0
+
+### Added
+
+#### Routing
+- Full 31-role catalog — all roles scored by keyword, trigger phrase, packet type bias, and deliverable affinity
+- Dynamic chain builder — phase-ordered assembly replacing static templates
+- Routing confidence assessment (high/medium/low)
+- `excludeWhen` enforcement — roles suppressed when exclusion patterns match packet content
+- `detectType` false-positive prevention — "integration testing" no longer triggers integration type
+- `--verbose` flag for `roleos route` — hides scoring noise by default
+
+#### Conflict Detection
+- 4-pass conflict engine: hard conflicts, sequence, redundancy, coverage gaps
+- Per-role constraint registry: lateOnly, requiresBeforePacks
+- Overlap pair detection
+- Repair suggestions on every finding
+
+#### Escalation Auto-Routing
+- Blocked/rejected/conflict/split work auto-routes to named resolver
+- Every escalation includes: target role, recovery type, required artifact, handoff context
+
+#### Structured Evidence
+- 12 evidence kinds, 4 statuses, closed 4-verdict enum (accept/accept-with-notes/reject/blocked)
+- Role-aware evidence requirements for 15 roles
+- Sufficiency checks with contradiction detection
+
+#### Runtime Dispatch
+- Execution manifests for multi-claude with per-role tool profiles and budgets
+- 8 execution states with auto-advance
+- Escalation packet generation for blocked/rejected steps
+
+#### Proven Team Packs
+- 7 battle-tested packs: feature, bugfix, security, docs, launch, research, treatment
+- `roleos packs list` — show all packs with role counts
+- `roleos packs suggest <packet>` — suggest best pack for a packet
+- `roleos packs show <name>` — show pack details (roles, artifacts, stop conditions)
+- Pack suggestion engine with confidence levels
+
+#### Trials
+- Full roster proven: 30/30 gold-task trials + 5/5 negative (wrong-task honesty) trials
+- 7 pack execution trials — all packs ran full chains with honest Critic verdicts
+- Trial framework: buildClusterTrials, evaluateTrialOutput, formatTrialReport
+
+### Changed
+- 32 → 31 roles: Information Architect merged into Docs Architect
+- Verdict vocabulary unified: evidence.mjs now uses accept/reject/blocked (matching review.mjs)
+- "worker" terminology replaced with "role" in dispatch.mjs
+
+### Fixed
+- `excludeWhen` was declared on 14 roles but never enforced — now active in scoreRole
+- `detectType` false-positived on "integration testing" — now uses word-boundary regex
+- "Not triggered: N roles" noise hidden by default (shown with --verbose)
+- Handbook: Team Packs page added, reference sidebar reordered
+
 ## 1.0.2
 
 ### Fixed

package/README.md

@@ -15,11 +15,11 @@
   <a href="https://mcp-tool-shop-org.github.io/role-os/"><img src="https://img.shields.io/badge/Landing_Page-live-brightgreen" alt="Landing Page"></a>
 </p>
 
-A portable, repo-native operating layer that routes work through role contracts, structured packets, review, and escalation so teams can do feature work, integration work, identity repair, and full repo treatment without drift, false completion, or vibes-based progress claims.
+A multi-Claude operating system that staffs, routes, validates, and runs work through 31 specialized role contracts. Creates task packets, assembles the right team from scored role matching, detects broken chains before execution, auto-routes recovery when work is blocked or rejected, and requires structured evidence in every verdict.
 
 ## What it does
 
-Role OS prevents the specific failures that generic AI workflows produce:
+Role OS is the professional way to use multi-Claude. It prevents the specific failures that generic AI workflows produce:
 
 - **Drift** — roles stay in lane. Product doesn't redesign. Frontend doesn't redefine scope. Backend doesn't invent product direction.
 - **False completion** — the done definition is concrete. Work that hides gaps, skips verification, or solves a different problem gets rejected.
@@ -29,9 +29,15 @@ Role OS prevents the specific failures that generic AI workflows produce:
 ## How it works
 
 1. **Create a packet** — define what needs to exist when the work is done
-2. **Route through a chain** — the smallest set of specialized roles needed
-3. **Each role produces a handoff** — structured output that reduces ambiguity for the next role
-4. **Critic reviews against contract** — accepts, rejects, or blocks based on evidence, not impression
+2. **Route through a chain** — `roleos route` scores all 31 roles against the packet content, assembles a dynamic chain ordered by work phase, and explains why each role was chosen
+3. **Validate the team** — 4-pass conflict detection catches hard conflicts, sequence errors, redundancy, and coverage gaps before execution starts
+4. **Each role produces a handoff** — structured output with evidence items that reduce ambiguity for the next role
+5. **Critic reviews against contract** — accepts, rejects, or blocks based on structured evidence, not impression
+6. **Recovery routes automatically** — blocked or rejected work gets routed to the right resolver with a reason, recovery type, and required artifact
+
+## Org rollout state
+
+Org-wide rollout state (queue, decisions, audit records, per-repo lock packets) lives in a separate private repo: [`role-os-rollout`](https://github.com/mcp-tool-shop-org/role-os-rollout). This repo is the product; that repo is operational state.
 
 ## Memory and continuity
 
@@ -47,7 +53,7 @@ Full treatment is a canonical 7-phase protocol defined in Claude project memory
 
 Order: Shipcheck first, then full treatment. No v1.0.0 without passing hard gates.
 
-## 32 roles across 8 packs
+## 31 roles across 8 packs
 
 | Pack | Roles |
 |------|-------|
@@ -56,11 +62,11 @@ Order: Shipcheck first, then full treatment. No v1.0.0 without passing hard gate
 | **Design** (2) | UI Designer, Brand Guardian |
 | **Marketing** (1) | Launch Copywriter |
 | **Treatment** (7) | Repo Researcher, Repo Translator, Docs Architect, Metadata Curator, Coverage Auditor, Deployment Verifier, Release Engineer |
-| **Product** (4) | Feedback Synthesizer, Roadmap Prioritizer, Spec Writer, Information Architect |
+| **Product** (3) | Feedback Synthesizer, Roadmap Prioritizer, Spec Writer |
 | **Research** (4) | UX Researcher, Competitive Analyst, Trend Researcher, User Interview Synthesizer |
 | **Growth** (4) | Launch Strategist, Content Strategist, Community Manager, Support Triage Lead |
 
-Every role has a full contract: mission, use when, do not use when, expected inputs, required outputs, quality bar, and escalation triggers.
+Every role has a full contract: mission, use when, do not use when, expected inputs, required outputs, quality bar, and escalation triggers. Every role is routable — `roleos route` can recommend any of them based on packet content.
 
 ## Quick start
 
@@ -124,32 +130,57 @@ These are non-negotiable. If a change weakens any of them, reject it.
 
 ```
 role-os/
-  README.md                    ← You are here
   bin/roleos.mjs               ← CLI entrypoint
-  src/                         ← CLI implementation
-  starter-pack/
-    handbook.md                ← How Role OS works
-    context/                   ← Fill these for your repo
-    examples/                  ← Feature, integration, identity packets
-    agents/                    ← 32 role contracts across 8 packs
+  src/
+    route.mjs                  ← 31-role routing + dynamic chain builder
+    conflicts.mjs              ← 4-pass conflict detection
+    escalation.mjs             ← Auto-routing for blocked/rejected/split
+    evidence.mjs               ← Structured evidence + role-aware requirements
+    dispatch.mjs               ← Runtime dispatch manifests for multi-claude
+    trial.mjs                  ← Role execution trial framework
+    packet.mjs                 ← Packet creation
+    review.mjs                 ← Verdict recording + escalation integration
+    status.mjs                 ← Active packet + verdict status
+  test/
+    route.test.mjs             ← 49 tests (routing + disambiguation)
+    conflicts.test.mjs         ← 13 tests (4 conflict types)
+    escalation.test.mjs        ← 22 tests (blocked/rejected/conflict/split)
+    evidence.test.mjs          ← 23 tests (schema + sufficiency)
+    dispatch.test.mjs          ← 21 tests (manifests + state + escalation packets)
+    trial.test.mjs             ← 12 tests (trial framework)
+    cli.test.mjs               ← 22 tests (CLI integration)
+  .claude/
+    agents/                    ← 31 role contracts across 8 packs
     schemas/                   ← Packet, handoff, verdict formats
-    policy/                    ← Routing, permissions, escalation, done
+    policy/                    ← Routing rules, permissions, escalation, done
     workflows/                 ← Ship feature, fix bug, launch update, full treatment
+    context/                   ← Fill these for your repo
+    trials/                    ← Execution trial packets + results
 ```
 
 ## Security
 
 Role OS operates **locally only**. It copies markdown templates and writes packet/verdict files to your repository's `.claude/` directory. It does not access the network, handle secrets, or collect telemetry. No dangerous operations — all file writes use skip-if-exists by default. See [SECURITY.md](SECURITY.md) for the full policy.
 
-## Status
+## The operating system
+
+| Layer | What it does | Status |
+|-------|-------------|--------|
+| **Routing** | Scores all 31 roles against packet content, explains recommendations, assesses confidence | ✓ Shipped |
+| **Chain builder** | Assembles phase-ordered chains from scored roles, packet-type biased not template-locked | ✓ Shipped |
+| **Conflict detection** | 4-pass validation: hard conflicts, sequence, redundancy, coverage gaps. Repair suggestions. | ✓ Shipped |
+| **Escalation** | Auto-routes blocked/rejected/split work to the right resolver with reason + required artifact | ✓ Shipped |
+| **Evidence** | Role-aware structured evidence in verdicts. Sufficiency checks. 12 evidence kinds. | ✓ Shipped |
+| **Dispatch** | Generates execution manifests for multi-claude. Per-role tool profiles, system prompts, budgets. | ✓ Shipped |
+| **Trials** | Full roster proven: 30/30 gold-task + 5/5 negative trials. 7 pack trials complete. | ✓ Complete |
+| **Team Packs** | 7 battle-tested packs for common task families. Pack suggestion engine. | ✓ Shipped |
 
-**v1.0.0 — Broad Surface, Same Laws**
+## Status
 
-- v0.1: Operational — 3 trials, 3 accepts, 0 role collisions
-- v0.2: Adoption — default workflow in anchor repo, portable to second repo
-- v0.3: Productization — starter pack, bootstrap CLI, evidence surface
-- v0.4: Treatment Pack — 8 treatment/identity roles, full treatment staffed, portable across 2 repos
-- v1.0.0: 32 roles across 8 packs, full CLI, proven treatment, multi-repo portability
+- v0.1–v0.4: Foundation — trials, adoption, treatment pack, starter pack
+- v1.0.0: 32 roles, full CLI, proven treatment, multi-repo portability
+- v1.0.2: Role OS lockdown (bootstrap truth fixes, init --force)
+- **v1.1.0**: 31 roles, full routing spine, conflict detection, escalation, evidence, dispatch, 7 proven team packs. 35 execution trials (30 gold + 5 negative). 212 tests.
 
 ## License
 

package/bin/roleos.mjs

@@ -8,6 +8,7 @@ import { packetCommand } from "../src/packet.mjs";
 import { routeCommand } from "../src/route.mjs";
 import { reviewCommand } from "../src/review.mjs";
 import { statusCommand } from "../src/status.mjs";
+import { packsCommand } from "../src/packs-cmd.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
@@ -20,11 +21,14 @@ Usage:
   roleos init                        Scaffold Role OS into .claude/
   roleos init --force                Update canonical files (protects context/)
   roleos packet new <type>           Create a new packet (feature|integration|identity)
-  roleos route <packet-file>         Recommend the smallest valid chain
+  roleos route <packet-file> [--verbose]  Recommend the smallest valid chain
   roleos review <packet-file> <verdict>  Record a review verdict
   roleos status                      Show active work, verdicts, and health
   roleos status --write              Write .claude/status/index.md
   roleos status --json               Output as JSON
+  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 help                        Show this help
 
 Verdicts: accept | accept-with-notes | reject | blocked
@@ -74,6 +78,9 @@ try {
     case "status":
       await statusCommand(args);
       break;
+    case "packs":
+      await packsCommand(args);
+      break;
     case "help":
     case "--help":
     case "-h":

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "role-os",
-  "version": "1.0.2",
-  "description": "Role OS — a repo-native operating layer where specialized roles execute work through contracts, handoffs, review, and escalation",
+  "version": "1.1.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": {
+    "url": "https://github.com/mcp-tool-shop-org/role-os/issues"
+  },
   "type": "module",
   "bin": {
     "roleos": "bin/roleos.mjs"
@@ -33,7 +37,13 @@
     "contracts",
     "handoffs",
     "review",
-    "workflow"
+    "workflow",
+    "multi-agent",
+    "ai-workflow",
+    "developer-tools",
+    "role-contracts",
+    "claude",
+    "multi-claude"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org"

package/src/conflicts.mjs

@@ -0,0 +1,217 @@
+/**
+ * Role conflict detection.
+ *
+ * Tells the operator when the staffed team is internally broken
+ * before work starts. Four passes: hard conflicts, sequence,
+ * redundancy, coverage gaps. Every finding includes a repair suggestion.
+ */
+
+// ── Per-role constraints ──────────────────────────────────────────────────────
+
+const ROLE_CONSTRAINTS = {
+  "Critic Reviewer": {
+    lateOnly: true,
+    requiresBeforePacks: ["engineering", "design", "treatment", "product"],
+    description: "review/gate role — needs something to review",
+  },
+  "Test Engineer": {
+    lateOnly: true,
+    requiresBeforePacks: ["engineering", "design"],
+    description: "test role — needs something to test",
+  },
+  "Coverage Auditor": {
+    lateOnly: true,
+    requiresBeforePacks: ["engineering"],
+    description: "coverage role — needs code to audit",
+  },
+  "Deployment Verifier": {
+    lateOnly: true,
+    requiresBeforePacks: ["engineering", "treatment"],
+    description: "verification role — needs something deployed to verify",
+  },
+  "Release Engineer": {
+    lateOnly: true,
+    requiresBeforePacks: ["engineering", "treatment"],
+    description: "release role — needs built or prepared artifacts to release",
+  },
+  "Launch Copywriter": {
+    requiresBeforePacks: ["engineering", "design", "product"],
+    description: "messaging role — needs product substance to write about",
+  },
+  "Launch Strategist": {
+    requiresBeforePacks: ["engineering", "design", "product"],
+    description: "launch role — needs product substance to plan launch around",
+  },
+  "Content Strategist": {
+    requiresBeforePacks: ["engineering", "design", "product"],
+    description: "content role — needs product substance for content planning",
+  },
+};
+
+// ── Overlap declarations ──────────────────────────────────────────────────────
+// Roles that produce similar artifacts and rarely both need to be in the same chain.
+
+const OVERLAP_PAIRS = [
+  ["Coverage Auditor", "Test Engineer", "both assess test quality — consider keeping only one unless scope is very large"],
+  ["Repo Researcher", "Docs Architect", "both map repo structure — Researcher maps truth, Architect builds docs from it"],
+  ["Launch Strategist", "Launch Copywriter", "both serve launches — Strategist plans, Copywriter writes. Both needed only for major launches"],
+  ["Competitive Analyst", "Trend Researcher", "both scan external landscape — consider whether one covers the need"],
+];
+
+// ── Builder packs (roles that produce primary artifacts) ──────────────────────
+
+const BUILDER_PACKS = new Set(["engineering", "design", "product", "treatment"]);
+
+// ── Pack limits ───────────────────────────────────────────────────────────────
+
+const MAX_SAME_PACK = 3;
+
+// ── Detection engine ──────────────────────────────────────────────────────────
+
+/**
+ * Detect conflicts in a staffed chain.
+ *
+ * @param {Array<{role: {name: string, pack: string, phase: number}}>} chainRoles
+ * @returns {Array<{type: string, severity: string, roles: string[], message: string, repair: string}>}
+ */
+export function detectConflicts(chainRoles) {
+  const findings = [];
+  const names = chainRoles.map(r => r.role.name);
+  const packs = chainRoles.map(r => r.role.pack);
+  const roles = chainRoles.map(r => r.role);
+
+  // ── Pass 1: Hard conflicts ──────────────────────────────────────────────
+
+  // Check if review/gate roles are the only non-Orchestrator roles (no builders)
+  const nonCore = roles.filter(r => r.name !== "Orchestrator" && r.name !== "Critic Reviewer");
+  const builders = nonCore.filter(r => BUILDER_PACKS.has(r.pack));
+
+  if (builders.length === 0 && nonCore.length > 0) {
+    const nonCoreNames = nonCore.map(r => r.name);
+    findings.push({
+      type: "blocking",
+      severity: "error",
+      roles: nonCoreNames,
+      message: `Chain has no builder roles (engineering, design, product, or treatment). Only gate/growth/research roles present: ${nonCoreNames.join(", ")}.`,
+      repair: "Add at least one role that produces a primary artifact (e.g., Backend Engineer, UI Designer, Spec Writer).",
+    });
+  }
+
+  // ── Pass 2: Sequence conflicts ──────────────────────────────────────────
+
+  for (const [roleName, constraints] of Object.entries(ROLE_CONSTRAINTS)) {
+    const roleIdx = names.indexOf(roleName);
+    if (roleIdx === -1) continue; // role not in chain
+
+    if (constraints.requiresBeforePacks) {
+      // Check if any role from the required packs appears BEFORE this role
+      const hasPriorBuilder = roles.slice(0, roleIdx).some(
+        r => constraints.requiresBeforePacks.includes(r.pack)
+      );
+
+      if (!hasPriorBuilder && builders.length > 0) {
+        // There ARE builders, but they're all AFTER this role
+        findings.push({
+          type: "sequence",
+          severity: "warning",
+          roles: [roleName],
+          message: `${roleName} (${constraints.description}) appears before any ${constraints.requiresBeforePacks.join("/")} role in the chain.`,
+          repair: `Move ${roleName} later in the chain, after the roles that produce what it needs.`,
+        });
+      }
+
+      if (builders.length === 0 && !constraints.lateOnly) {
+        // No builders at all — this was caught in Pass 1, skip double-reporting
+      }
+    }
+
+    if (constraints.lateOnly) {
+      // Check if this role appears in the first half of the chain (before most work)
+      const midpoint = Math.floor(chainRoles.length / 2);
+      if (roleIdx > 0 && roleIdx < midpoint && chainRoles.length > 3) {
+        findings.push({
+          type: "sequence",
+          severity: "warning",
+          roles: [roleName],
+          message: `${roleName} is a late-chain role but appears in the first half (position ${roleIdx + 1} of ${chainRoles.length}).`,
+          repair: `Move ${roleName} toward the end of the chain where it can act on completed work.`,
+        });
+      }
+    }
+  }
+
+  // ── Pass 3: Redundancy ──────────────────────────────────────────────────
+
+  // Pack density check
+  const packCounts = {};
+  for (const pack of packs) {
+    packCounts[pack] = (packCounts[pack] || 0) + 1;
+  }
+  for (const [pack, count] of Object.entries(packCounts)) {
+    if (pack === "core") continue; // Orchestrator + Critic are always present
+    if (count > MAX_SAME_PACK) {
+      const packRoles = roles.filter(r => r.pack === pack).map(r => r.name);
+      findings.push({
+        type: "redundancy",
+        severity: "warning",
+        roles: packRoles,
+        message: `${count} roles from the "${pack}" pack: ${packRoles.join(", ")}. This may indicate an oversized or overlapping team.`,
+        repair: `Review whether all ${count} ${pack} roles are needed. Consider splitting into sub-packets if scope is broad.`,
+      });
+    }
+  }
+
+  // Overlap pair check
+  for (const [roleA, roleB, note] of OVERLAP_PAIRS) {
+    if (names.includes(roleA) && names.includes(roleB)) {
+      findings.push({
+        type: "redundancy",
+        severity: "warning",
+        roles: [roleA, roleB],
+        message: `${roleA} and ${roleB} are both in the chain — ${note}.`,
+        repair: `Consider whether both are needed, or if one can cover the scope.`,
+      });
+    }
+  }
+
+  // ── Pass 4: Coverage gaps ───────────────────────────────────────────────
+
+  const engineeringCount = roles.filter(r => r.pack === "engineering").length;
+  const hasTestEngineer = names.includes("Test Engineer");
+  const hasCritic = names.includes("Critic Reviewer");
+
+  // Engineering-heavy with no tester
+  if (engineeringCount >= 2 && !hasTestEngineer) {
+    findings.push({
+      type: "coverage",
+      severity: "warning",
+      roles: roles.filter(r => r.pack === "engineering").map(r => r.name),
+      message: `Chain has ${engineeringCount} engineering roles but no Test Engineer. Code may ship without verification.`,
+      repair: "Add Test Engineer to verify the engineering output before review.",
+    });
+  }
+
+  // Builders present but no critic (defensive — should be caught by always-include)
+  if (builders.length > 0 && !hasCritic) {
+    findings.push({
+      type: "coverage",
+      severity: "error",
+      roles: builders.map(r => r.name),
+      message: "Chain has builder roles but no Critic Reviewer. Work cannot be accepted without a final gate.",
+      repair: "Add Critic Reviewer as the final role in the chain.",
+    });
+  }
+
+  // Large chain without Orchestrator (defensive)
+  if (chainRoles.length > 4 && !names.includes("Orchestrator")) {
+    findings.push({
+      type: "coverage",
+      severity: "warning",
+      roles: names,
+      message: "Chain has 5+ roles but no Orchestrator. Complex work needs coordination.",
+      repair: "Add Orchestrator at the start of the chain to decompose and sequence the work.",
+    });
+  }
+
+  return findings;
+}