role-os 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 1.6.0
+
+### Added
+
+#### Artifact Spine (Phase Q)
+- 20 per-role artifact contracts: each defines artifact type, required sections, evidence references, downstream consumers, and completion rules
+- `validateArtifact(role, content)` — structural validation against role contracts (missing sections, evidence references, content depth)
+- 7 pack-level handoff contracts: define the expected artifact flow between steps for each pack (e.g., strategy-brief → implementation-spec → change-plan → test-package → verdict)
+- `validatePackChain(pack, artifacts)` — validates an entire pack's artifact chain for completeness
+- `getArtifactContract(role)` / `getHandoffContract(pack)` — lookup APIs
+- `formatArtifactValidation()` / `formatPackChain()` — display formatters
+
+#### Artifact contract coverage
+- Product Strategist → strategy-brief (problem-framing, scope, non-goals, tradeoffs)
+- Spec Writer → implementation-spec (acceptance-criteria, edge-cases, interface-spec)
+- Backend/Frontend Engineer → change-plan (files-to-change, implementation-approach, risk-notes)
+- Test Engineer → test-package (test-plan, test-cases, false-confidence-assessment)
+- Security Reviewer → security-findings (findings, severity-assessment, recommendations)
+- Critic Reviewer → verdict (verdict, evidence, required-corrections)
+- And 14 more roles with full contracts
+
+### Evidence
+- 385 tests, zero failures
+- 27 new artifact tests
+
+## 1.5.0
+
+### Added
+
+#### Hook Spine / Runtime Enforcement (Phase R)
+- 5 lifecycle hooks: SessionStart, UserPromptSubmit, PreToolUse, SubagentStart, Stop
+- `scaffoldHooks()` generates all 5 hook scripts in .claude/hooks/
+- `roleos init claude` now scaffolds hooks + settings.local.json with hook config
+- `roleos doctor` now checks for hook scripts (check 7) and settings hooks (check 8)
+
+#### SessionStart hook
+- Establishes session contract on every new session
+- Records session ID, timestamp, initializes state tracking
+- Adds context reminding Claude to use /roleos-route for non-trivial tasks
+
+#### UserPromptSubmit hook
+- Classifies prompts as substantial (>50 chars + action verbs)
+- After 2+ substantial prompts without a route card, adds context reminder
+- Does not block — advisory enforcement
+
+#### PreToolUse hook
+- Records all tool usage in session state
+- Flags write tools (Bash, Write, Edit) used without route card after substantial work
+- Advisory, not blocking — preserves operator control
+
+#### SubagentStart hook
+- Injects active role contract into delegated agents
+- Ensures subagents inherit the Role OS session context
+
+#### Stop hook
+- Warns when substantial sessions end without route card or outcome artifact
+- Advisory — does not block session exit
+- Trivial sessions (< 2 substantial prompts) are exempt
+
+### Evidence
+- 358 tests, zero failures
+- 23 new hook tests covering all 5 lifecycle hooks
+
 ## 1.4.0
 
 ### Added

package/README.md

@@ -179,6 +179,8 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 | **Composite execution** | Runs child packets in dependency order with artifact passing, branch recovery, and synthesis. | ✓ Shipped |
 | **Adaptive replanning** | Mid-run scope changes, findings, or new requirements update the plan without restarting. | ✓ Shipped |
 | **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 |
 
 ## Status
 
@@ -188,7 +190,9 @@ Role OS operates **locally only**. It copies markdown templates and writes packe
 - v1.1.0: 31 roles, full routing spine, conflict detection, escalation, evidence, dispatch, 7 proven team packs. 35 execution trials. 212 tests.
 - v1.2.0: Calibrated packs promoted to default entry. Auto-selection, mismatch detection, alternative suggestion, free-routing fallback. 246 tests.
 - 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. Adoption certainty, not just routing cleverness. 335 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.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "role-os",
-  "version": "1.4.0",
+  "version": "1.6.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.mjs

@@ -0,0 +1,437 @@
+/**
+ * Artifact Spine — Phase Q (v1.6.0)
+ *
+ * Every important role produces a declared artifact with a known shape.
+ * Downstream roles never guess what they received.
+ *
+ * 1. Per-role artifact contracts (required sections, evidence, references)
+ * 2. Structural validation (completeness, not semantic perfection)
+ * 3. Pack-level handoff contracts (expected artifact flow between steps)
+ * 4. Composite artifact ledger integration
+ */
+
+// ── Per-role artifact contracts ───────────────────────────────────────────────
+
+/**
+ * Each contract defines what a role MUST produce for its handoff to be valid.
+ * Not every role needs a contract — only chain-critical roles that hand off
+ * to other roles.
+ */
+export const ROLE_ARTIFACT_CONTRACTS = {
+  "Product Strategist": {
+    artifactType: "strategy-brief",
+    requiredSections: ["problem-framing", "scope", "non-goals", "tradeoffs"],
+    optionalSections: ["user-value", "risks", "success-criteria"],
+    requiredEvidence: [],
+    consumedBy: ["Spec Writer", "Orchestrator"],
+    completionRule: "All 4 required sections must be present and non-empty.",
+  },
+  "Spec Writer": {
+    artifactType: "implementation-spec",
+    requiredSections: ["acceptance-criteria", "edge-cases", "interface-spec"],
+    optionalSections: ["data-schema", "nfrs", "open-questions"],
+    requiredEvidence: ["strategy-brief"],
+    consumedBy: ["Backend Engineer", "Frontend Developer"],
+    completionRule: "At least 3 acceptance criteria. Edge cases identified. Interface shape defined.",
+  },
+  "Backend Engineer": {
+    artifactType: "change-plan",
+    requiredSections: ["files-to-change", "implementation-approach", "risk-notes"],
+    optionalSections: ["test-strategy", "migration-notes"],
+    requiredEvidence: ["implementation-spec"],
+    consumedBy: ["Test Engineer", "Critic Reviewer"],
+    completionRule: "Files named. Approach described. Risks surfaced.",
+  },
+  "Frontend Developer": {
+    artifactType: "change-plan",
+    requiredSections: ["files-to-change", "implementation-approach", "risk-notes"],
+    optionalSections: ["component-structure", "accessibility-notes"],
+    requiredEvidence: ["implementation-spec"],
+    consumedBy: ["Test Engineer", "Critic Reviewer"],
+    completionRule: "Files named. Approach described. Risks surfaced.",
+  },
+  "Test Engineer": {
+    artifactType: "test-package",
+    requiredSections: ["test-plan", "test-cases", "false-confidence-assessment"],
+    optionalSections: ["edge-case-coverage", "regression-defense"],
+    requiredEvidence: ["change-plan"],
+    consumedBy: ["Critic Reviewer"],
+    completionRule: "Test plan present. At least 3 test cases. False confidence assessment honest.",
+  },
+  "Security Reviewer": {
+    artifactType: "security-findings",
+    requiredSections: ["findings", "severity-assessment", "recommendations"],
+    optionalSections: ["threat-model", "exploitation-scenarios"],
+    requiredEvidence: ["change-plan"],
+    consumedBy: ["Backend Engineer", "Critic Reviewer"],
+    completionRule: "Each finding has severity + recommendation. No finding without remediation path.",
+  },
+  "Coverage Auditor": {
+    artifactType: "coverage-report",
+    requiredSections: ["well-defended", "poorly-defended", "false-confidence", "priority-recommendations"],
+    optionalSections: ["missing-defenses", "regression-vectors"],
+    requiredEvidence: [],
+    consumedBy: ["Test Engineer", "Critic Reviewer"],
+    completionRule: "Coverage honestly assessed. False confidence identified. Priorities ranked.",
+  },
+  "Docs Architect": {
+    artifactType: "doc-map",
+    requiredSections: ["page-structure", "content-gaps", "navigation-design"],
+    optionalSections: ["getting-started-flow", "search-requirements"],
+    requiredEvidence: [],
+    consumedBy: ["Metadata Curator", "Release Engineer"],
+    completionRule: "Pages listed. Gaps identified. Navigation designed.",
+  },
+  "Launch Strategist": {
+    artifactType: "launch-brief",
+    requiredSections: ["launch-sequence", "proof-packaging", "channel-selection", "success-criteria"],
+    optionalSections: ["risk-assessment", "what-not-to-say"],
+    requiredEvidence: [],
+    consumedBy: ["Launch Copywriter"],
+    completionRule: "Sequence defined. Proof mapped. Channels selected. Success measurable.",
+  },
+  "Launch Copywriter": {
+    artifactType: "copy-package",
+    requiredSections: ["release-notes", "short-announcement"],
+    optionalSections: ["npm-description", "social-variants", "messaging-angle"],
+    requiredEvidence: ["launch-brief"],
+    consumedBy: ["Critic Reviewer"],
+    completionRule: "Release notes present. At least one announcement variant.",
+  },
+  "Repo Researcher": {
+    artifactType: "repo-map",
+    requiredSections: ["entrypoints", "module-map", "build-test-commands"],
+    optionalSections: ["seams", "dependencies"],
+    requiredEvidence: [],
+    consumedBy: ["Backend Engineer", "Coverage Auditor", "Security Reviewer"],
+    completionRule: "Entrypoints listed. Module responsibilities described. Commands documented.",
+  },
+  "Metadata Curator": {
+    artifactType: "metadata-audit",
+    requiredSections: ["manifest-audit", "registry-alignment"],
+    optionalSections: ["badge-verification", "discovery-surface", "recommendations"],
+    requiredEvidence: [],
+    consumedBy: ["Release Engineer"],
+    completionRule: "Package.json audited. Registry alignment checked.",
+  },
+  "Release Engineer": {
+    artifactType: "release-plan",
+    requiredSections: ["version-decision", "changelog-draft", "pre-publish-checklist"],
+    optionalSections: ["packaging-check", "release-steps"],
+    requiredEvidence: [],
+    consumedBy: ["Deployment Verifier", "Critic Reviewer"],
+    completionRule: "Version decided with rationale. Changelog written. Checklist present.",
+  },
+  "Deployment Verifier": {
+    artifactType: "deployment-report",
+    requiredSections: ["live-state-assessment"],
+    optionalSections: ["npm-verification", "github-verification", "badge-verification", "translation-check"],
+    requiredEvidence: [],
+    consumedBy: ["Critic Reviewer"],
+    completionRule: "All deployed surfaces checked. Stale/mismatched items named.",
+  },
+  "Critic Reviewer": {
+    artifactType: "verdict",
+    requiredSections: ["verdict", "evidence", "required-corrections"],
+    optionalSections: ["notes", "next-owner", "chain-assessment"],
+    requiredEvidence: [],
+    consumedBy: [],
+    completionRule: "Verdict stated. Evidence cited. Corrections listed if not accept.",
+  },
+  "UX Researcher": {
+    artifactType: "ux-evaluation",
+    requiredSections: ["friction-inventory", "severity-ranking", "recommendations"],
+    optionalSections: ["flow-analysis", "heuristic-evaluation"],
+    requiredEvidence: [],
+    consumedBy: ["Product Strategist", "UI Designer"],
+    completionRule: "Friction points identified. Severity ranked. Evidence-based recommendations.",
+  },
+  "Competitive Analyst": {
+    artifactType: "landscape-analysis",
+    requiredSections: ["competitor-inventory", "differentiation", "honest-disadvantages"],
+    optionalSections: ["positioning-gaps", "recommendations"],
+    requiredEvidence: [],
+    consumedBy: ["Product Strategist"],
+    completionRule: "Competitors listed. Differentiation clear. Disadvantages honest.",
+  },
+  "Feedback Synthesizer": {
+    artifactType: "signal-synthesis",
+    requiredSections: ["theme-extraction", "theme-ranking", "confidence-assessment"],
+    optionalSections: ["contradictions", "complaint-to-action"],
+    requiredEvidence: [],
+    consumedBy: ["Product Strategist"],
+    completionRule: "Themes extracted. Ranking justified. Confidence assessed.",
+  },
+  "Refactor Engineer": {
+    artifactType: "refactor-plan",
+    requiredSections: ["structural-assessment", "module-boundaries", "migration-path"],
+    optionalSections: ["duplication-inventory", "proposed-structure"],
+    requiredEvidence: [],
+    consumedBy: ["Test Engineer", "Critic Reviewer"],
+    completionRule: "Current structure assessed. Target boundaries defined. Migration preserves tests.",
+  },
+  "Support Triage Lead": {
+    artifactType: "triage-report",
+    requiredSections: ["classification", "priority-assignment", "routing"],
+    optionalSections: ["recurring-patterns", "systemic-recommendations"],
+    requiredEvidence: [],
+    consumedBy: ["Feedback Synthesizer", "Docs Architect"],
+    completionRule: "Each item classified. Priority assigned. Route to owner named.",
+  },
+};
+
+// ── Artifact validation ───────────────────────────────────────────────────────
+
+/**
+ * Validate an artifact against its role contract.
+ * Checks structural completeness, not semantic quality.
+ *
+ * @param {string} roleName
+ * @param {string} artifactContent - The artifact text
+ * @returns {{ valid: boolean, missing: string[], warnings: string[], contract: object|null }}
+ */
+export function validateArtifact(roleName, artifactContent) {
+  const contract = ROLE_ARTIFACT_CONTRACTS[roleName];
+  if (!contract) {
+    return { valid: true, missing: [], warnings: ["No artifact contract defined for this role."], contract: null };
+  }
+
+  const lower = artifactContent.toLowerCase();
+  const missing = [];
+  const warnings = [];
+
+  // Check required sections
+  for (const section of contract.requiredSections) {
+    // Look for the section as a heading or key phrase
+    const patterns = [
+      section.toLowerCase(),
+      section.replace(/-/g, " ").toLowerCase(),
+      `## ${section.replace(/-/g, " ")}`.toLowerCase(),
+      `### ${section.replace(/-/g, " ")}`.toLowerCase(),
+    ];
+    const found = patterns.some(p => lower.includes(p));
+    if (!found) {
+      missing.push(section);
+    }
+  }
+
+  // Check required evidence references
+  for (const evidence of contract.requiredEvidence) {
+    const patterns = [
+      evidence.toLowerCase(),
+      evidence.replace(/-/g, " ").toLowerCase(),
+    ];
+    const found = patterns.some(p => lower.includes(p));
+    if (!found) {
+      warnings.push(`Expected reference to "${evidence}" from upstream role.`);
+    }
+  }
+
+  // Check minimum content length (not just headers)
+  const contentLines = artifactContent.split("\n").filter(l => l.trim() && !l.trim().startsWith("#"));
+  if (contentLines.length < 5) {
+    warnings.push("Artifact appears thin — fewer than 5 content lines.");
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+    warnings,
+    contract,
+  };
+}
+
+// ── Pack-level handoff contracts ──────────────────────────────────────────────
+
+/**
+ * Defines the expected artifact flow for each pack.
+ * Each step produces an artifact that the next step consumes.
+ */
+export const PACK_HANDOFF_CONTRACTS = {
+  feature: {
+    flow: [
+      { role: "Product Strategist", produces: "strategy-brief", consumedBy: "Spec Writer" },
+      { role: "Spec Writer", produces: "implementation-spec", consumedBy: "Backend Engineer" },
+      { role: "Backend Engineer", produces: "change-plan", consumedBy: "Test Engineer" },
+      { role: "Test Engineer", produces: "test-package", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "verdict", consumedBy: null },
+    ],
+  },
+  bugfix: {
+    flow: [
+      { role: "Repo Researcher", produces: "repo-map", consumedBy: "Backend Engineer" },
+      { role: "Backend Engineer", produces: "change-plan", consumedBy: "Test Engineer" },
+      { role: "Test Engineer", produces: "test-package", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "verdict", consumedBy: null },
+    ],
+  },
+  security: {
+    flow: [
+      { role: "Security Reviewer", produces: "security-findings", consumedBy: "Critic Reviewer" },
+      { role: "Dependency Auditor", produces: "metadata-audit", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "verdict", consumedBy: null },
+    ],
+  },
+  docs: {
+    flow: [
+      { role: "Support Triage Lead", produces: "triage-report", consumedBy: "Feedback Synthesizer" },
+      { role: "Feedback Synthesizer", produces: "signal-synthesis", consumedBy: "Docs Architect" },
+      { role: "Docs Architect", produces: "doc-map", consumedBy: "Metadata Curator" },
+      { role: "Metadata Curator", produces: "metadata-audit", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "verdict", consumedBy: null },
+    ],
+  },
+  launch: {
+    flow: [
+      { role: "Launch Strategist", produces: "launch-brief", consumedBy: "Launch Copywriter" },
+      { role: "Launch Copywriter", produces: "copy-package", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "verdict", consumedBy: null },
+    ],
+  },
+  research: {
+    flow: [
+      { role: "Product Strategist", produces: "strategy-brief", consumedBy: "UX Researcher" },
+      { role: "UX Researcher", produces: "ux-evaluation", consumedBy: "Competitive Analyst" },
+      { role: "Competitive Analyst", produces: "landscape-analysis", consumedBy: "Feedback Synthesizer" },
+      { role: "Feedback Synthesizer", produces: "signal-synthesis", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "verdict", consumedBy: null },
+    ],
+  },
+  treatment: {
+    flow: [
+      { role: "Repo Researcher", produces: "repo-map", consumedBy: "Security Reviewer" },
+      { role: "Security Reviewer", produces: "security-findings", consumedBy: "Coverage Auditor" },
+      { role: "Coverage Auditor", produces: "coverage-report", consumedBy: "Docs Architect" },
+      { role: "Docs Architect", produces: "doc-map", consumedBy: "Metadata Curator" },
+      { role: "Metadata Curator", produces: "metadata-audit", consumedBy: "Release Engineer" },
+      { role: "Release Engineer", produces: "release-plan", consumedBy: "Deployment Verifier" },
+      { role: "Deployment Verifier", produces: "deployment-report", consumedBy: "Critic Reviewer" },
+      { role: "Critic Reviewer", produces: "verdict", consumedBy: null },
+    ],
+  },
+};
+
+/**
+ * Validate a pack's artifact chain — check that each step's output
+ * matches what the next step expects.
+ *
+ * @param {string} packName
+ * @param {Record<string, string>} artifacts - Map of role name → artifact content
+ * @returns {{ valid: boolean, steps: object[] }}
+ */
+export function validatePackChain(packName, artifacts) {
+  const contract = PACK_HANDOFF_CONTRACTS[packName];
+  if (!contract) {
+    return { valid: false, steps: [{ role: "unknown", status: "error", detail: `No handoff contract for pack "${packName}"` }] };
+  }
+
+  const steps = [];
+  let chainValid = true;
+
+  for (const step of contract.flow) {
+    const content = artifacts[step.role];
+    if (!content) {
+      steps.push({
+        role: step.role,
+        produces: step.produces,
+        status: "missing",
+        detail: `No artifact from ${step.role}.`,
+      });
+      chainValid = false;
+      continue;
+    }
+
+    const validation = validateArtifact(step.role, content);
+    steps.push({
+      role: step.role,
+      produces: step.produces,
+      status: validation.valid ? "valid" : "incomplete",
+      missing: validation.missing,
+      warnings: validation.warnings,
+      detail: validation.valid
+        ? `${step.produces} is structurally complete.`
+        : `Missing sections: ${validation.missing.join(", ")}`,
+    });
+
+    if (!validation.valid) chainValid = false;
+  }
+
+  return { valid: chainValid, steps };
+}
+
+/**
+ * Get the artifact contract for a specific role.
+ *
+ * @param {string} roleName
+ * @returns {object|null}
+ */
+export function getArtifactContract(roleName) {
+  return ROLE_ARTIFACT_CONTRACTS[roleName] || null;
+}
+
+/**
+ * Get the handoff contract for a specific pack.
+ *
+ * @param {string} packName
+ * @returns {object|null}
+ */
+export function getHandoffContract(packName) {
+  return PACK_HANDOFF_CONTRACTS[packName] || null;
+}
+
+/**
+ * Format artifact validation result for display.
+ *
+ * @param {string} roleName
+ * @param {object} validation
+ * @returns {string}
+ */
+export function formatArtifactValidation(roleName, validation) {
+  const lines = [`Artifact validation — ${roleName}`];
+
+  if (validation.valid) {
+    lines.push(`  ✓ Structurally complete`);
+  } else {
+    lines.push(`  ✗ Incomplete — missing: ${validation.missing.join(", ")}`);
+  }
+
+  if (validation.warnings.length > 0) {
+    for (const w of validation.warnings) {
+      lines.push(`  ! ${w}`);
+    }
+  }
+
+  if (validation.contract) {
+    lines.push(`  Contract: ${validation.contract.artifactType}`);
+    lines.push(`  Consumed by: ${validation.contract.consumedBy.join(", ") || "terminal"}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format pack chain validation for display.
+ *
+ * @param {string} packName
+ * @param {object} chainValidation
+ * @returns {string}
+ */
+export function formatPackChain(packName, chainValidation) {
+  const lines = [
+    `\nPack Chain Validation — ${packName}`,
+    `─────────────────────────────────`,
+  ];
+
+  for (const step of chainValidation.steps) {
+    const icon = step.status === "valid" ? "✓" : step.status === "missing" ? "○" : "!";
+    lines.push(`  ${icon} ${step.role} → ${step.produces}: ${step.detail}`);
+  }
+
+  lines.push(``);
+  lines.push(chainValidation.valid
+    ? `Chain valid — all artifacts structurally complete.`
+    : `Chain incomplete — see above for missing artifacts.`
+  );
+
+  return lines.join("\n");
+}

package/src/hooks.mjs

@@ -0,0 +1,469 @@
+/**
+ * Hook Spine — v1.5.0 Runtime Enforcement
+ *
+ * Hooks verify, gate, and record. The actual routing intelligence
+ * stays in explicit artifacts (route cards, pack selection).
+ * Hooks are the proof layer, not the decision layer.
+ *
+ * Four guarantees:
+ * 1. No substantial task begins without a route artifact
+ * 2. No tool execution drifts outside the selected role envelope
+ * 3. No subagent runs without inheriting the role contract
+ * 4. No session ends without an outcome artifact
+ *
+ * Hook lifecycle events used:
+ * - SessionStart: establish session contract
+ * - UserPromptSubmit: classify before improvising
+ * - PreToolUse: enforce role-specific tool law
+ * - SubagentStart: inject role contract into delegation
+ * - Stop: prevent false completion
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+// ── Hook script generators ────────────────────────────────────────────────────
+
+/**
+ * Generate the settings.json hooks configuration.
+ * Each hook is a shell command that runs a Node script from .claude/hooks/.
+ *
+ * @returns {object} The hooks configuration object for settings.json
+ */
+export function generateHooksConfig() {
+  return {
+    hooks: {
+      SessionStart: [
+        {
+          matcher: "",
+          hooks: [{
+            type: "command",
+            command: "node .claude/hooks/session-start.mjs",
+          }],
+        },
+      ],
+      UserPromptSubmit: [
+        {
+          matcher: "",
+          hooks: [{
+            type: "command",
+            command: "node .claude/hooks/prompt-submit.mjs",
+          }],
+        },
+      ],
+      PreToolUse: [
+        {
+          matcher: "",
+          hooks: [{
+            type: "command",
+            command: "node .claude/hooks/pre-tool-use.mjs",
+          }],
+        },
+      ],
+      SubagentStart: [
+        {
+          matcher: "",
+          hooks: [{
+            type: "command",
+            command: "node .claude/hooks/subagent-start.mjs",
+          }],
+        },
+      ],
+      Stop: [
+        {
+          matcher: "",
+          hooks: [{
+            type: "command",
+            command: "node .claude/hooks/stop.mjs",
+          }],
+        },
+      ],
+    },
+  };
+}
+
+// ── Session state ─────────────────────────────────────────────────────────────
+
+const SESSION_STATE_FILE = ".claude/hooks/session-state.json";
+
+/**
+ * Read or create session state.
+ * @param {string} cwd
+ * @returns {object}
+ */
+export function getSessionState(cwd) {
+  const path = join(cwd, SESSION_STATE_FILE);
+  if (existsSync(path)) {
+    try { return JSON.parse(readFileSync(path, "utf-8")); }
+    catch { /* fall through */ }
+  }
+  return {
+    sessionId: null,
+    routeCardPresent: false,
+    activeRole: null,
+    activePack: null,
+    toolsUsed: [],
+    promptCount: 0,
+    substantivePrompts: 0,
+    outcomeRecorded: false,
+    startedAt: null,
+  };
+}
+
+/**
+ * Save session state.
+ * @param {string} cwd
+ * @param {object} state
+ */
+export function saveSessionState(cwd, state) {
+  const dir = join(cwd, ".claude", "hooks");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(cwd, SESSION_STATE_FILE), JSON.stringify(state, null, 2));
+}
+
+// ── Hook logic ────────────────────────────────────────────────────────────────
+
+/**
+ * SessionStart hook logic.
+ * Establishes session contract, checks for existing route artifacts.
+ *
+ * @param {object} input - Hook input (session_id, cwd, etc.)
+ * @returns {{ addContext?: string }}
+ */
+export function onSessionStart(input) {
+  const cwd = input.cwd || process.cwd();
+  const state = getSessionState(cwd);
+
+  state.sessionId = input.session_id || `session-${Date.now()}`;
+  state.startedAt = new Date().toISOString();
+  state.routeCardPresent = false;
+  state.promptCount = 0;
+  state.substantivePrompts = 0;
+  state.outcomeRecorded = false;
+
+  saveSessionState(cwd, state);
+
+  // Check if Role OS is initialized
+  const hasRoleOs = existsSync(join(cwd, ".claude", "agents"));
+
+  if (hasRoleOs) {
+    return {
+      addContext: "Role OS is active in this repo. For non-trivial tasks, run /roleos-route to produce a route card before beginning work. The route card proves the task was classified and the right team was chosen.",
+    };
+  }
+
+  return {};
+}
+
+/**
+ * UserPromptSubmit hook logic.
+ * Detects substantial prompts and warns if no route artifact exists.
+ *
+ * @param {object} input - { prompt, session_id, cwd }
+ * @returns {{ addContext?: string, block?: { reason: string } }}
+ */
+export function onPromptSubmit(input) {
+  const cwd = input.cwd || process.cwd();
+  const state = getSessionState(cwd);
+  const prompt = input.prompt || "";
+
+  state.promptCount++;
+
+  // Classify as substantial if > 50 chars and contains action words
+  const isSubstantial = prompt.length > 50 && /\b(implement|add|fix|build|create|refactor|review|ship|deploy|test|write|update|change|remove|migrate)\b/i.test(prompt);
+
+  if (isSubstantial) {
+    state.substantivePrompts++;
+  }
+
+  saveSessionState(cwd, state);
+
+  // If this is the 2nd+ substantial prompt without a route card, remind
+  if (isSubstantial && state.substantivePrompts >= 2 && !state.routeCardPresent) {
+    return {
+      addContext: "Note: This is a substantial task and no Role OS route card has been produced yet. Consider running /roleos-route to classify the task and choose the right team. A route card ensures the work is staffed correctly.",
+    };
+  }
+
+  return {};
+}
+
+/**
+ * PreToolUse hook logic.
+ * Checks tool usage against active role envelope.
+ *
+ * @param {object} input - { tool_name, tool_input, session_id, cwd }
+ * @returns {{ allow?: boolean, deny?: { reason: string }, addContext?: string }}
+ */
+export function onPreToolUse(input) {
+  const cwd = input.cwd || process.cwd();
+  const state = getSessionState(cwd);
+  const toolName = input.tool_name || "";
+
+  // Record tool usage
+  if (!state.toolsUsed.includes(toolName)) {
+    state.toolsUsed.push(toolName);
+    saveSessionState(cwd, state);
+  }
+
+  // Advisory: flag write tools without route card after substantial prompts
+  const writeTools = ["Bash", "Write", "Edit", "NotebookEdit"];
+  if (writeTools.includes(toolName) && !state.routeCardPresent && (state.substantivePrompts || 0) >= 2) {
+    return {
+      addContext: `Write tool "${toolName}" used without a route card. If this is substantial work, consider routing first.`,
+    };
+  }
+
+  // If a role is active, read-only tools are always fine
+  if (state.activeRole && state.activePack) {
+    const readOnlyTools = ["Read", "Glob", "Grep", "WebSearch", "WebFetch"];
+    if (readOnlyTools.includes(toolName)) {
+      return { allow: true };
+    }
+  }
+
+  return {};
+}
+
+/**
+ * SubagentStart hook logic.
+ * Injects role contract context into delegated agents.
+ *
+ * @param {object} input - { agent_id, agent_type, session_id, cwd }
+ * @returns {{ addContext?: string }}
+ */
+export function onSubagentStart(input) {
+  const cwd = input.cwd || process.cwd();
+  const state = getSessionState(cwd);
+
+  if (state.activeRole) {
+    return {
+      addContext: `This subagent is operating under Role OS. Active role: ${state.activeRole}. Pack: ${state.activePack || "free routing"}. Follow the role contract and produce structured handoffs.`,
+    };
+  }
+
+  return {};
+}
+
+/**
+ * Stop hook logic.
+ * Prevents false completion — warns if no route card or outcome exists.
+ *
+ * @param {object} input - { session_id, cwd, stop_reason }
+ * @returns {{ block?: { reason: string }, addContext?: string }}
+ */
+export function onStop(input) {
+  const cwd = input.cwd || process.cwd();
+  const state = getSessionState(cwd);
+
+  // Only enforce on sessions that had substantial work
+  if (state.substantivePrompts < 2) {
+    return {}; // Trivial session, let it end
+  }
+
+  const warnings = [];
+
+  if (!state.routeCardPresent) {
+    warnings.push("No route card was produced during this session.");
+  }
+
+  if (!state.outcomeRecorded) {
+    warnings.push("No outcome artifact was recorded.");
+  }
+
+  if (warnings.length > 0) {
+    return {
+      addContext: `Role OS session audit: ${warnings.join(" ")} Consider documenting the outcome before ending.`,
+    };
+  }
+
+  return {};
+}
+
+// ── Hook script file generators ───────────────────────────────────────────────
+
+/**
+ * Generate hook script files for .claude/hooks/.
+ * These are the actual scripts that settings.json points to.
+ *
+ * @param {string} cwd
+ * @returns {{ created: string[], skipped: string[] }}
+ */
+export function scaffoldHooks(cwd) {
+  const created = [];
+  const skipped = [];
+  const hooksDir = join(cwd, ".claude", "hooks");
+  mkdirSync(hooksDir, { recursive: true });
+
+  const scripts = {
+    "session-start.mjs": generateSessionStartScript(),
+    "prompt-submit.mjs": generatePromptSubmitScript(),
+    "pre-tool-use.mjs": generatePreToolUseScript(),
+    "subagent-start.mjs": generateSubagentStartScript(),
+    "stop.mjs": generateStopScript(),
+  };
+
+  for (const [name, content] of Object.entries(scripts)) {
+    const path = join(hooksDir, name);
+    if (!existsSync(path)) {
+      writeFileSync(path, content);
+      created.push(`.claude/hooks/${name}`);
+    } else {
+      skipped.push(`.claude/hooks/${name}`);
+    }
+  }
+
+  return { created, skipped };
+}
+
+function generateSessionStartScript() {
+  return `#!/usr/bin/env node
+// Role OS SessionStart hook — establishes session contract
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const cwd = input.cwd || process.cwd();
+const stateDir = join(cwd, ".claude", "hooks");
+mkdirSync(stateDir, { recursive: true });
+
+const state = {
+  sessionId: input.session_id || \`session-\${Date.now()}\`,
+  startedAt: new Date().toISOString(),
+  routeCardPresent: false,
+  activeRole: null,
+  activePack: null,
+  toolsUsed: [],
+  promptCount: 0,
+  substantivePrompts: 0,
+  outcomeRecorded: false,
+};
+
+writeFileSync(join(stateDir, "session-state.json"), JSON.stringify(state, null, 2));
+
+const hasRoleOs = existsSync(join(cwd, ".claude", "agents"));
+if (hasRoleOs) {
+  console.log(JSON.stringify({
+    addContext: "Role OS is active. For non-trivial tasks, run /roleos-route first.",
+  }));
+}
+`;
+}
+
+function generatePromptSubmitScript() {
+  return `#!/usr/bin/env node
+// Role OS UserPromptSubmit hook — classify before improvising
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const cwd = input.cwd || process.cwd();
+const statePath = join(cwd, ".claude", "hooks", "session-state.json");
+
+let state = {};
+if (existsSync(statePath)) {
+  try { state = JSON.parse(readFileSync(statePath, "utf-8")); } catch {}
+}
+
+const prompt = input.prompt || "";
+state.promptCount = (state.promptCount || 0) + 1;
+
+const isSubstantial = prompt.length > 50 &&
+  /\\b(implement|add|fix|build|create|refactor|review|ship|deploy|test|write|update|change|remove|migrate)\\b/i.test(prompt);
+
+if (isSubstantial) state.substantivePrompts = (state.substantivePrompts || 0) + 1;
+
+writeFileSync(statePath, JSON.stringify(state, null, 2));
+
+if (isSubstantial && (state.substantivePrompts || 0) >= 2 && !state.routeCardPresent) {
+  console.log(JSON.stringify({
+    addContext: "No Role OS route card yet. Consider /roleos-route to classify this task.",
+  }));
+}
+`;
+}
+
+function generatePreToolUseScript() {
+  return `#!/usr/bin/env node
+// Role OS PreToolUse hook — enforce role-specific tool law
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const cwd = input.cwd || process.cwd();
+const statePath = join(cwd, ".claude", "hooks", "session-state.json");
+
+let state = {};
+if (existsSync(statePath)) {
+  try { state = JSON.parse(readFileSync(statePath, "utf-8")); } catch {}
+}
+
+const toolName = input.tool_name || "";
+if (!state.toolsUsed) state.toolsUsed = [];
+if (!state.toolsUsed.includes(toolName)) {
+  state.toolsUsed.push(toolName);
+  writeFileSync(statePath, JSON.stringify(state, null, 2));
+}
+
+// Advisory: flag write tools without route card
+const writeTools = ["Bash", "Write", "Edit", "NotebookEdit"];
+if (writeTools.includes(toolName) && !state.routeCardPresent && (state.substantivePrompts || 0) >= 2) {
+  console.log(JSON.stringify({
+    addContext: \`Write tool "\${toolName}" used without route card. Consider /roleos-route.\`,
+  }));
+}
+`;
+}
+
+function generateSubagentStartScript() {
+  return `#!/usr/bin/env node
+// Role OS SubagentStart hook — inject role contract
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const cwd = input.cwd || process.cwd();
+const statePath = join(cwd, ".claude", "hooks", "session-state.json");
+
+let state = {};
+if (existsSync(statePath)) {
+  try { state = JSON.parse(readFileSync(statePath, "utf-8")); } catch {}
+}
+
+if (state.activeRole) {
+  console.log(JSON.stringify({
+    addContext: \`Role OS active. Role: \${state.activeRole}. Pack: \${state.activePack || "free routing"}. Follow role contract.\`,
+  }));
+}
+`;
+}
+
+function generateStopScript() {
+  return `#!/usr/bin/env node
+// Role OS Stop hook — prevent false completion
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+const input = JSON.parse(readFileSync("/dev/stdin", "utf-8").toString() || "{}");
+const cwd = input.cwd || process.cwd();
+const statePath = join(cwd, ".claude", "hooks", "session-state.json");
+
+let state = {};
+if (existsSync(statePath)) {
+  try { state = JSON.parse(readFileSync(statePath, "utf-8")); } catch {}
+}
+
+// Only enforce on sessions with substantial work
+if ((state.substantivePrompts || 0) < 2) process.exit(0);
+
+const warnings = [];
+if (!state.routeCardPresent) warnings.push("No route card produced.");
+if (!state.outcomeRecorded) warnings.push("No outcome artifact recorded.");
+
+if (warnings.length > 0) {
+  console.log(JSON.stringify({
+    addContext: \`Role OS audit: \${warnings.join(" ")} Consider documenting the outcome.\`,
+  }));
+}
+`;
+}

package/src/session.mjs

@@ -14,6 +14,7 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { writeFileSafe } from "./fs-utils.mjs";
+import { scaffoldHooks, generateHooksConfig } from "./hooks.mjs";
 
 // ── roleos init claude ────────────────────────────────────────────────────────
 
@@ -76,6 +77,34 @@ export function scaffoldClaude(cwd, options = {}) {
     skipped.push(".claude/commands/roleos-status.md");
   }
 
+  // 5. Hook scripts
+  const hookResult = scaffoldHooks(cwd);
+  created.push(...hookResult.created);
+  skipped.push(...hookResult.skipped);
+
+  // 6. Settings.json with hooks config
+  const settingsPath = join(cwd, ".claude", "settings.local.json");
+  if (!existsSync(settingsPath) || options.force) {
+    const hooksConfig = generateHooksConfig();
+    writeFileSync(settingsPath, JSON.stringify(hooksConfig, null, 2));
+    created.push(".claude/settings.local.json");
+  } else {
+    // Check if hooks are already configured
+    try {
+      const existing = JSON.parse(readFileSync(settingsPath, "utf-8"));
+      if (!existing.hooks) {
+        const hooksConfig = generateHooksConfig();
+        existing.hooks = hooksConfig.hooks;
+        writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
+        created.push(".claude/settings.local.json (hooks added)");
+      } else {
+        skipped.push(".claude/settings.local.json (hooks already configured)");
+      }
+    } catch {
+      skipped.push(".claude/settings.local.json (could not parse existing)");
+    }
+  }
+
   return { created, skipped };
 }
 
@@ -162,6 +191,35 @@ export function doctor(cwd) {
     detail: existsSync(packetsDir) ? "exists" : "no packets yet — run roleos packet new",
   });
 
+  // Check 7: Hook scripts exist
+  const hooksDir = join(cwd, ".claude", "hooks");
+  const hookFiles = ["session-start.mjs", "prompt-submit.mjs", "pre-tool-use.mjs", "subagent-start.mjs", "stop.mjs"];
+  const existingHooks = hookFiles.filter(f => existsSync(join(hooksDir, f)));
+  if (existingHooks.length === hookFiles.length) {
+    checks.push({ name: "hook scripts", status: "pass", detail: `all ${hookFiles.length} hooks present` });
+  } else if (existingHooks.length > 0) {
+    checks.push({ name: "hook scripts", status: "warn", detail: `${existingHooks.length}/${hookFiles.length} hooks present` });
+  } else {
+    checks.push({ name: "hook scripts", status: "warn", detail: "no hooks — run roleos init claude for runtime enforcement" });
+  }
+
+  // Check 8: Settings has hooks configured
+  const settingsPath = join(cwd, ".claude", "settings.local.json");
+  if (existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+      if (settings.hooks) {
+        checks.push({ name: "hooks in settings", status: "pass", detail: "configured" });
+      } else {
+        checks.push({ name: "hooks in settings", status: "warn", detail: "settings.local.json exists but no hooks section" });
+      }
+    } catch {
+      checks.push({ name: "hooks in settings", status: "warn", detail: "settings.local.json exists but could not parse" });
+    }
+  } else {
+    checks.push({ name: "hooks in settings", status: "warn", detail: "no settings.local.json — hooks not active" });
+  }
+
   const healthy = checks.every(c => c.status !== "fail");
 
   return { checks, healthy };