role-os 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 1.9.0
+
+### Added
+
+#### Unified Entry Path (Phase T)
+- `roleos start <task>` — auto-decides mission vs pack vs free routing
+- Three-level fallback ladder with confidence scores and alternatives
+- Composite task detection warns when a task should be decomposed
+- `--json` flag for machine-readable entry decisions
+- 46 new tests: entry engine, comparison trials, CLI integration
+
+#### Handbook Updates
+- New Missions handbook page with full mission documentation
+- Updated Getting Started to lead with `roleos start`
+- Updated Reference with all CLI commands (start, mission, packs, artifacts, status, doctor)
+- Updated handbook index with entry levels and 9 operating layers
+
+#### README Overhaul
+- "How it works" section leads with `roleos start` examples
+- Quick Start updated with mission and start commands
+- Added 6 Missions table
+- Updated project structure with all 18 source modules
+- Updated status history through v1.9.0
+
+### Evidence
+- 527 tests, zero failures (46 new)
+- Entry path trials validated against 20+ real task descriptions
+- Fallback ladder tested: mission, pack, free-routing, composite, empty input
+
+## 1.8.0
+
+### Added
+
+#### Mission Library (Phase S — Mission Hardening)
+- 6 named, repeatable mission types: feature-ship, bugfix, treatment, docs-release, security-hardening, research-launch
+- Each mission declares: pack, role chain, artifact flow, escalation branches, honest-partial definition, stop conditions, dispatch defaults, trial evidence
+- Mission runner: create → step through → complete/fail → generate completion report
+- Completion proof reporter with honest-partial and formatted text output
+- `roleos mission list` — list all missions
+- `roleos mission show <key>` — full mission detail
+- `roleos mission suggest <text>` — signal-based mission suggestion
+- `roleos mission validate [key]` — validate mission wiring against packs/roles
+
+#### Mission Runner Engine
+- `createRun()` — instantiate a mission with tracked steps
+- `startNextStep()` / `completeStep()` / `failStep()` — step lifecycle
+- `recordEscalation()` — re-opens completed steps on escalation loops
+- `getRunPosition()` / `getArtifactChain()` — run introspection
+- `generateCompletionReport()` / `formatCompletionReport()` — honest outcome reporting
+
+### Evidence
+- 465 tests, zero failures (67 new)
+- All 6 missions validate against live pack/role catalog
+- Full lifecycle tests: end-to-end runs, escalation loops, partial completions, failure reporting
+
 ## 1.7.0
 
 ### Added

package/README.md

@@ -28,12 +28,35 @@ Role OS is the professional way to use multi-Claude. It prevents the specific fa
 
 ## How it works
 
-1. **Create a packet** — define what needs to exist when the work is done
-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
+Describe your task. Role OS decides the right level of orchestration automatically.
+
+```bash
+roleos start "fix the crash in save handler"
+# → MISSION: Bugfix & Diagnosis (70% confidence)
+#   Chain: Repo Researcher → Backend Engineer → Test Engineer → Critic Reviewer
+
+roleos start "add a new export command"
+# → PACK: Feature Build (50% confidence)
+#   Roles: Orchestrator, Product Strategist, Spec Writer, Backend Engineer, Test Engineer, Critic Reviewer
+
+roleos start "something completely novel"
+# → FREE-ROUTING (10% confidence)
+#   Hint: Create a packet and run `roleos route` for role-level routing
+```
+
+**The fallback ladder:**
+
+1. **Mission** — when the task matches a proven recurring workflow (bugfix, treatment, feature-ship, docs, security, research). Known role chain, artifact flow, escalation branches, and honest-partial definitions.
+2. **Pack** — when the task is a known family but not a full mission shape. 7 calibrated team packs with auto-selection and mismatch guards.
+3. **Free routing** — when the task is novel, mixed, or uncertain. Scores all 31 roles against packet content and assembles a dynamic chain.
+
+The system never forces work through the wrong abstraction. It explains why it chose each level and offers alternatives.
+
+**Once routed:**
+
+1. **Each role produces a handoff** — structured output with evidence items that reduce ambiguity for the next role
+2. **Critic reviews against contract** — accepts, rejects, or blocks based on structured evidence, not impression
+3. **Recovery routes automatically** — blocked or rejected work gets routed to the right resolver with a reason, recovery type, and required artifact
 
 ## Org rollout state
 
@@ -73,11 +96,20 @@ Every role has a full contract: mission, use when, do not use when, expected inp
 ```bash
 npx role-os init
 
-# Fill context/ files for your project, then:
+# Describe what you need — Role OS picks the right level:
+roleos start "fix the crash in save handler"
+
+# Or go manual:
 roleos packet new feature
 roleos route .claude/packets/my-feature.md
 roleos review .claude/packets/my-feature.md accept
 roleos status
+
+# Explore missions and packs:
+roleos mission list
+roleos mission show bugfix
+roleos packs list
+roleos packs show feature
 ```
 
 ## When not to use Role OS
@@ -132,30 +164,26 @@ These are non-negotiable. If a change weakens any of them, reject it.
 role-os/
   bin/roleos.mjs               ← CLI entrypoint
   src/
+    entry.mjs                  ← Unified entry: mission → pack → free routing
+    entry-cmd.mjs              ← `roleos start` CLI command
+    mission.mjs                ← 6 named mission types (feature, bugfix, treatment, docs, security, research)
+    mission-run.mjs            ← Mission runner: create → step → complete → report
+    mission-cmd.mjs            ← `roleos mission` CLI commands
     route.mjs                  ← 31-role routing + dynamic chain builder
+    packs.mjs                  ← 7 calibrated team packs + auto-selection
     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 rules, permissions, escalation, done
-    workflows/                 ← Ship feature, fix bug, launch update, full treatment
-    context/                   ← Fill these for your repo
-    trials/                    ← Execution trial packets + results
+    artifacts.mjs              ← 20 per-role artifact contracts + 7 pack handoffs
+    decompose.mjs              ← Composite task detection + splitting
+    composite.mjs              ← Dependency-ordered execution + recovery
+    replan.mjs                 ← Mid-run adaptive replanning
+    calibration.mjs            ← Outcome recording + weight tuning
+    hooks.mjs                  ← 5 lifecycle hooks for runtime enforcement
+    session.mjs                ← Session scaffolding + doctor
+  test/                        ← 527 tests across 20 test files
+  starter-pack/                ← Drop-in role contracts, policies, schemas, workflows
 ```
 
 ## Security
@@ -181,6 +209,22 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 | **Session spine** | `roleos init claude` scaffolds CLAUDE.md, /roleos-route, /roleos-review, /roleos-status. `roleos doctor` verifies wiring. Route cards prove engagement. | ✓ Shipped |
 | **Hook spine** | 5 lifecycle hooks (SessionStart, PromptSubmit, PreToolUse, SubagentStart, Stop). Advisory enforcement: route card reminders, write-tool gating, subagent role injection, completion audit. | ✓ Shipped |
 | **Artifact spine** | 20 per-role artifact contracts. 7 pack handoff contracts. Structural validation. Chain completeness checks. Downstream roles never guess what they received. | ✓ Shipped |
+| **Mission library** | 6 named missions (feature-ship, bugfix, treatment, docs-release, security-hardening, research-launch). Each declares pack, role chain, artifact flow, escalation branches, honest-partial definition. All 6 trial-run and hardened. | ✓ Shipped |
+| **Mission runner** | Create runs, step through with tracked state, complete/fail with honest reporting. Blocked-step propagation, out-of-chain escalation warnings, last-step re-opening. | ✓ Shipped |
+| **Unified entry** | `roleos start` decides mission vs pack vs free routing automatically. Fallback ladder with confidence scores, alternatives, and composite detection. | ✓ Shipped |
+
+## 6 missions
+
+| Mission | Pack | Roles | When to use |
+|---------|------|-------|-------------|
+| `feature-ship` | feature | 5 | Full feature delivery: scope → spec → implement → test → review |
+| `bugfix` | bugfix | 4 | Diagnose root cause, fix, test, verify |
+| `treatment` | treatment | 4 | Shipcheck + polish + docs + CI verify + review |
+| `docs-release` | docs | 2 | Write/update documentation, release notes |
+| `security-hardening` | security | 4 | Threat model, audit, fix vulnerabilities, re-audit, verify |
+| `research-launch` | research | 4 | Frame question, research, document findings, decide |
+
+Each mission includes honest-partial definitions — when work stalls, the system documents what was completed and what remains instead of bluffing completion.
 
 ## Status
 
@@ -193,7 +237,9 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 - 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. 385 tests.
-- **v1.7.0**: Completion proof — real tasks run through the full stack. `roleos artifacts` CLI. Honest escalation on structural fixes. 398 tests.
+- v1.7.0: Completion proof — real tasks run through the full stack. `roleos artifacts` CLI. Honest escalation on structural fixes. 398 tests.
+- v1.8.0: Mission library (Phase S) — 6 named missions, runner engine, completion reports. Hardened from 6 real trial runs. 481 tests.
+- **v1.9.0**: Unified entry path (Phase T) — `roleos start` auto-decides mission vs pack vs free routing. Fallback ladder, composite detection, entry-path comparison trials. 527 tests.
 
 ## License
 

package/bin/roleos.mjs

@@ -11,6 +11,8 @@ 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";
+import { missionCommand } from "../src/mission-cmd.mjs";
+import { startCommand } from "../src/entry-cmd.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8")).version;
@@ -20,6 +22,7 @@ function printHelp() {
 roleos v${VERSION} — Role OS bootstrap CLI
 
 Usage:
+  roleos start <task>                 Decide entry path: mission, pack, or free routing
   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)
@@ -35,6 +38,10 @@ Usage:
   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 mission list                List all missions
+  roleos mission show <key>          Show full mission detail
+  roleos mission suggest <text>      Suggest a mission for a task
+  roleos mission validate [key]      Validate mission wiring
   roleos doctor                      Verify repo is wired for Role OS sessions
   roleos help                        Show this help
 
@@ -70,6 +77,9 @@ const args = process.argv.slice(3);
 
 try {
   switch (command) {
+    case "start":
+      await startCommand(args);
+      break;
     case "init":
       if (args[0] === "claude") {
         const force = args.includes("--force");
@@ -111,6 +121,9 @@ try {
     case "artifacts":
       await artifactsCommand(args);
       break;
+    case "mission":
+      await missionCommand(args);
+      break;
     case "help":
     case "--help":
     case "-h":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "role-os",
-  "version": "1.7.0",
+  "version": "1.9.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/entry-cmd.mjs

@@ -0,0 +1,59 @@
+/**
+ * Entry CLI — Phase T (v1.9.0)
+ *
+ * roleos start <task description>     Decide best entry path automatically
+ * roleos start --json <text>          Output as JSON
+ */
+
+import { decideEntry, formatEntryDecision } from "./entry.mjs";
+
+/**
+ * @param {string[]} args
+ */
+export async function startCommand(args) {
+  const isJson = args.includes("--json");
+  const textArgs = args.filter(a => a !== "--json");
+  const text = textArgs.join(" ").trim();
+
+  if (!text) {
+    const err = new Error(
+      "Usage: roleos start <task description>\n" +
+      "  Decides whether to route through a mission, pack, or free routing.\n\n" +
+      "Examples:\n" +
+      '  roleos start "fix the crash in save handler"\n' +
+      '  roleos start "add a new export command"\n' +
+      '  roleos start "run the full treatment before publishing"'
+    );
+    err.exitCode = 1;
+    err.hint = "Describe the task you want to accomplish.";
+    throw err;
+  }
+
+  const decision = decideEntry(text);
+
+  if (isJson) {
+    console.log(JSON.stringify(decision, null, 2));
+  } else {
+    console.log("");
+    console.log(formatEntryDecision(decision));
+    console.log("");
+
+    // Action guidance
+    if (decision.level === "mission") {
+      console.log("Next steps:");
+      console.log(`  1. roleos mission show ${decision.mission.key}     # review the mission`);
+      console.log(`  2. Create a packet and start working through the mission steps`);
+      console.log(`  3. Use the mission runner to track progress and artifacts`);
+    } else if (decision.level === "pack") {
+      console.log("Next steps:");
+      console.log(`  1. roleos packs show ${decision.pack.key}          # review the pack`);
+      console.log(`  2. roleos packet new feature                       # create a packet`);
+      console.log(`  3. roleos route <packet> --pack=${decision.pack.key}   # route with pack`);
+    } else {
+      console.log("Next steps:");
+      console.log("  1. roleos packet new feature                       # create a packet");
+      console.log("  2. roleos route <packet>                           # free routing");
+    }
+    console.log("");
+  }
+}

package/src/entry.mjs

@@ -0,0 +1,357 @@
+/**
+ * Unified Entry Path — Phase T (v1.9.0)
+ *
+ * When a user brings Role-OS a task, the system decides the best
+ * abstraction level automatically:
+ *
+ *   1. MISSION — when the task matches a proven recurring workflow
+ *   2. PACK — when the task is a known family but not a full mission shape
+ *   3. FREE ROUTING — when the task is novel, mixed, or uncertain
+ *
+ * The entry path is honest: it explains WHY it chose each level,
+ * and never forces work through the wrong abstraction.
+ */
+
+import { suggestMission, getMission, MISSIONS } from "./mission.mjs";
+import { suggestPack, getPack, checkPackMismatch, TEAM_PACKS } from "./packs.mjs";
+import { detectComposite } from "./decompose.mjs";
+import { ROLE_CATALOG } from "./route.mjs";
+
+// ── Entry levels ────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {"mission"|"pack"|"free-routing"} EntryLevel
+ */
+
+/**
+ * @typedef {Object} EntryDecision
+ * @property {EntryLevel} level - Which abstraction level was chosen
+ * @property {string} reason - Human-readable explanation
+ * @property {number} confidence - 0-1 confidence in this choice
+ * @property {object|null} mission - Mission details (when level=mission)
+ * @property {object|null} pack - Pack details (when level=pack)
+ * @property {object|null} freeRouting - Routing hints (when level=free-routing)
+ * @property {object|null} alternative - Next-best option if operator disagrees
+ * @property {boolean} isComposite - Whether the task looks like multiple jobs
+ * @property {string[]} warnings - Any concerns about the choice
+ */
+
+// ── Confidence thresholds ───────────────────────────────────────────────────
+
+const MISSION_HIGH_THRESHOLD = 0.7;   // strong mission match → use mission
+const MISSION_MEDIUM_THRESHOLD = 0.4; // decent match → mission if pack also agrees
+const PACK_HIGH_THRESHOLD = 0.6;      // strong pack match → use pack
+const PACK_MEDIUM_THRESHOLD = 0.3;    // decent match → use pack as fallback
+
+// ── Core entry function ─────────────────────────────────────────────────────
+
+/**
+ * Decide the best entry path for a task description.
+ *
+ * The fallback ladder:
+ *   mission (when fit is strong)
+ *   → pack (when mission fit is weak but task family is clear)
+ *   → free routing (when the task is novel or mixed)
+ *
+ * @param {string} taskDescription
+ * @returns {EntryDecision}
+ */
+export function decideEntry(taskDescription) {
+  if (!taskDescription || taskDescription.trim().length === 0) {
+    return {
+      level: "free-routing",
+      reason: "No task description provided — defaulting to free routing.",
+      confidence: 0,
+      mission: null,
+      pack: null,
+      freeRouting: { hint: "Provide a task description for better routing." },
+      alternative: null,
+      isComposite: false,
+      warnings: ["Empty task description"],
+    };
+  }
+
+  const text = taskDescription.trim();
+  const warnings = [];
+
+  // Step 1: Check for composite tasks (multi-job detection)
+  const composite = detectComposite(text);
+  const isComposite = composite.isComposite;
+  if (isComposite) {
+    warnings.push(
+      `Task looks composite (${composite.detectedCategories.map(c => c.category).join(" + ")}). ` +
+      `Consider decomposing before routing.`
+    );
+  }
+
+  // Step 2: Try mission suggestion
+  const missionSuggestion = suggestMission(text);
+  const missionScore = scoreMissionFit(missionSuggestion);
+
+  // Step 3: Try pack suggestion
+  const packSuggestion = suggestPack(text);
+  const packScore = scorePackFit(packSuggestion);
+
+  // Step 4: Check agreement (mission and pack point to the same family)
+  const agreement = checkAgreement(missionSuggestion, packSuggestion);
+
+  // Step 5: Apply the fallback ladder
+  return applyLadder(text, missionSuggestion, missionScore, packSuggestion, packScore, agreement, isComposite, composite, warnings);
+}
+
+// ── Scoring helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Normalize mission suggestion into a 0-1 score.
+ */
+function scoreMissionFit(suggestion) {
+  if (!suggestion) return 0;
+  switch (suggestion.confidence) {
+    case "high": return 0.9;
+    case "medium": return 0.55;
+    case "low": return 0.25;
+    default: return 0;
+  }
+}
+
+/**
+ * Normalize pack suggestion into a 0-1 score.
+ */
+function scorePackFit(suggestion) {
+  if (!suggestion) return 0;
+  switch (suggestion.confidence) {
+    case "high": return 0.85;
+    case "medium": return 0.5;
+    case "low": return 0.2;
+    default: return 0;
+  }
+}
+
+/**
+ * Check if mission and pack suggestions agree (point to same family).
+ */
+function checkAgreement(missionSuggestion, packSuggestion) {
+  if (!missionSuggestion || !packSuggestion) return false;
+  const mission = getMission(missionSuggestion.mission);
+  if (!mission) return false;
+  return mission.pack === packSuggestion.pack;
+}
+
+// ── Fallback ladder ─────────────────────────────────────────────────────────
+
+function applyLadder(text, missionSug, missionScore, packSug, packScore, agreement, isComposite, composite, warnings) {
+  // ── MISSION: strong match, or medium match with pack agreement ──────────
+  if (missionScore >= MISSION_HIGH_THRESHOLD) {
+    const mission = getMission(missionSug.mission);
+    return {
+      level: "mission",
+      reason: `Strong mission match: "${mission.name}" (${missionSug.confidence} confidence, ${missionSug.reason}). ` +
+              `This is a proven recurring workflow with known role chain, artifact flow, and escalation branches.`,
+      confidence: missionScore,
+      mission: {
+        key: missionSug.mission,
+        name: mission.name,
+        pack: mission.pack,
+        roleChain: mission.roleChain,
+        entryPath: mission.entryPath,
+        stepCount: mission.artifactFlow.length,
+      },
+      pack: null,
+      freeRouting: null,
+      alternative: packSug ? {
+        level: "pack",
+        key: packSug.pack,
+        name: TEAM_PACKS[packSug.pack]?.name,
+        confidence: packScore,
+      } : null,
+      isComposite,
+      warnings,
+    };
+  }
+
+  if (missionScore >= MISSION_MEDIUM_THRESHOLD && agreement) {
+    const mission = getMission(missionSug.mission);
+    return {
+      level: "mission",
+      reason: `Mission match: "${mission.name}" (${missionSug.confidence} confidence). ` +
+              `Pack suggestion agrees (${packSug.pack}), reinforcing the mission choice.`,
+      confidence: Math.min(missionScore + 0.15, 0.85), // boost from agreement
+      mission: {
+        key: missionSug.mission,
+        name: mission.name,
+        pack: mission.pack,
+        roleChain: mission.roleChain,
+        entryPath: mission.entryPath,
+        stepCount: mission.artifactFlow.length,
+      },
+      pack: null,
+      freeRouting: null,
+      alternative: {
+        level: "pack",
+        key: packSug.pack,
+        name: TEAM_PACKS[packSug.pack]?.name,
+        confidence: packScore,
+      },
+      isComposite,
+      warnings,
+    };
+  }
+
+  // ── PACK: strong pack match but mission doesn't fit well ─────────────────
+  if (packScore >= PACK_HIGH_THRESHOLD) {
+    const pack = TEAM_PACKS[packSug.pack];
+    return {
+      level: "pack",
+      reason: `Task family match: "${pack.name}" pack (${packSug.confidence} confidence). ` +
+              (missionScore > 0
+                ? `Mission "${getMission(missionSug.mission)?.name}" was considered but fit was weak (${missionSug.confidence}).`
+                : `No mission matched — task family is clear but not a full recurring workflow.`),
+      confidence: packScore,
+      mission: null,
+      pack: {
+        key: packSug.pack,
+        name: pack.name,
+        roles: pack.roles,
+        chainOrder: pack.chainOrder,
+        description: pack.description,
+      },
+      freeRouting: null,
+      alternative: missionSug ? {
+        level: "mission",
+        key: missionSug.mission,
+        name: getMission(missionSug.mission)?.name,
+        confidence: missionScore,
+      } : null,
+      isComposite,
+      warnings,
+    };
+  }
+
+  if (packScore >= PACK_MEDIUM_THRESHOLD) {
+    const pack = TEAM_PACKS[packSug.pack];
+    return {
+      level: "pack",
+      reason: `Weak task family match: "${pack.name}" pack (${packSug.confidence} confidence). ` +
+              `Using pack as starting point — operator may want to adjust.`,
+      confidence: packScore,
+      mission: null,
+      pack: {
+        key: packSug.pack,
+        name: pack.name,
+        roles: pack.roles,
+        chainOrder: pack.chainOrder,
+        description: pack.description,
+      },
+      freeRouting: null,
+      alternative: {
+        level: "free-routing",
+        confidence: 0,
+      },
+      isComposite,
+      warnings: [...warnings, "Low pack confidence — consider free routing if this doesn't fit"],
+    };
+  }
+
+  // ── FREE ROUTING: novel, mixed, or uncertain ─────────────────────────────
+  const freeHints = buildFreeRoutingHints(text, missionSug, packSug, isComposite, composite);
+
+  return {
+    level: "free-routing",
+    reason: freeHints.reason,
+    confidence: 0.1,
+    mission: null,
+    pack: null,
+    freeRouting: freeHints,
+    alternative: missionSug ? {
+      level: "mission",
+      key: missionSug.mission,
+      name: getMission(missionSug.mission)?.name,
+      confidence: missionScore,
+    } : packSug ? {
+      level: "pack",
+      key: packSug.pack,
+      name: TEAM_PACKS[packSug.pack]?.name,
+      confidence: packScore,
+    } : null,
+    isComposite,
+    warnings: [...warnings, "Free routing selected — task will be scored against all 31 roles"],
+  };
+}
+
+function buildFreeRoutingHints(text, missionSug, packSug, isComposite, composite) {
+  let reason;
+  if (isComposite) {
+    reason = `Task looks composite (${composite.detectedCategories.map(c => c.category).join(" + ")}). ` +
+             `No single mission or pack covers all parts — use free routing with decomposition.`;
+  } else if (!missionSug && !packSug) {
+    reason = "No mission or pack matched. Task is novel — free routing will score all 31 roles.";
+  } else {
+    reason = "Mission and pack matches were too weak to commit. Free routing will let role scoring decide.";
+  }
+
+  return {
+    reason,
+    hint: isComposite
+      ? "Consider running `roleos route` on a packet for each sub-task."
+      : "Create a packet with `roleos packet new` and run `roleos route` for role-level routing.",
+    suggestedRoleCount: isComposite ? composite.detectedCategories.length * 3 : null,
+  };
+}
+
+// ── Format for display ──────────────────────────────────────────────────────
+
+/**
+ * Format an entry decision as human-readable text.
+ * @param {EntryDecision} decision
+ * @returns {string}
+ */
+export function formatEntryDecision(decision) {
+  const lines = [];
+  const conf = Math.round(decision.confidence * 100);
+
+  lines.push(`Entry Decision: ${decision.level.toUpperCase()} (${conf}% confidence)`);
+  lines.push("");
+  lines.push(`Reason: ${decision.reason}`);
+
+  if (decision.level === "mission" && decision.mission) {
+    lines.push("");
+    lines.push(`Mission: ${decision.mission.name} (${decision.mission.key})`);
+    lines.push(`Pack: ${decision.mission.pack}`);
+    lines.push(`Entry: ${decision.mission.entryPath}`);
+    lines.push(`Chain: ${decision.mission.roleChain.join(" → ")}`);
+    lines.push(`Steps: ${decision.mission.stepCount}`);
+  }
+
+  if (decision.level === "pack" && decision.pack) {
+    lines.push("");
+    lines.push(`Pack: ${decision.pack.name} (${decision.pack.key})`);
+    lines.push(`Roles: ${decision.pack.roles.join(", ")}`);
+    lines.push(`Chain: ${decision.pack.chainOrder}`);
+  }
+
+  if (decision.level === "free-routing" && decision.freeRouting) {
+    lines.push("");
+    lines.push(`Hint: ${decision.freeRouting.hint}`);
+  }
+
+  if (decision.alternative) {
+    lines.push("");
+    const altConf = Math.round((decision.alternative.confidence || 0) * 100);
+    lines.push(`Alternative: ${decision.alternative.level}${decision.alternative.name ? ` (${decision.alternative.name})` : ""} at ${altConf}% confidence`);
+  }
+
+  if (decision.isComposite) {
+    lines.push("");
+    lines.push(`Note: This task looks composite — consider decomposing before proceeding.`);
+  }
+
+  if (decision.warnings.length > 0) {
+    lines.push("");
+    lines.push("Warnings:");
+    for (const w of decision.warnings) {
+      lines.push(`  - ${w}`);
+    }
+  }
+
+  return lines.join("\n");
+}