@alphazede/bearing-lite 0.1.0 → 0.1.1

package/README.md

@@ -5,93 +5,111 @@
 
 **Bearing Lite** (`@alphazede/bearing-lite`) is a skills-first Agent Plugin for
 planning, routing, bounded execution, and independent review of repository work.
-It ships portable skills, references, templates, and optional client hooks. It
-does **not** ship a CLI, MCP server, browser control room, local scheduler, or
-hidden runtime database.
+It ships portable skills, references, templates, and optional client hooks.
 
-An agent cannot certify its own work. The router selects the smallest valid
-route; independent assurance roles run only when declared, owner-selected, or
-required by a mandatory integrated phase gate. Owner Authority remains human-only.
+An agent cannot certify its own work. The stateful Router owns the planning
+conversation and visible Journey state, then dispatches fresh bounded sessions.
+Independent assurance runs at the owner's selected cadence: per slice, per
+execution/correction round, or once at the end. Owner Authority remains human-only.
 
-Bearing Lite was created by William Rumph at AlphaZede.
+Bearing Lite was created by William Rumph.
 
 ## Install
 
-Install as an Agent Plugin in a compatible client (for example Codex or Claude
-Code marketplaces that discover Agent Plugins `plugin.json` and `skills/`).
+Install as a host plugin. The portable identity is always `bearing-lite` /
+`@alphazede/bearing-lite`. No postinstall script, global hook copy, or
+host-config mutation is required.
 
 ```sh
-# Example: npm package for packaging and inspection
-npm pack @alphazede/bearing-lite
+# Claude Code
+claude plugin marketplace add /path/to/bearing-lite
+claude plugin install bearing-lite@bearing-lite
+
+# Codex
+codex plugin marketplace add /path/to/bearing-lite
+codex plugin add bearing-lite@bearing-lite
+
+# Grok Build
+grok plugin marketplace add /path/to/bearing-lite
+grok plugin install bearing-lite --trust
+
+# Cursor
+# Add the checkout as a Cursor marketplace/plugin (.cursor-plugin/)
+
+# Kimi Code
+# /plugins install /path/to/bearing-lite
+
+# AGY (Antigravity) — install the .agy root, not the repo root
+agy plugin install /path/to/bearing-lite/.agy
+
+# Pi — skills package, no command hooks
+pi install git:github.com/alphazede/bearing-lite
 ```
 
-Client install names follow the host plugin UI. The portable identity is always
-`bearing-lite` / `@alphazede/bearing-lite`. No postinstall script, global hook
-copy, or host-config mutation is required.
+Claude Code, Codex, Grok Build, Cursor, and Kimi Code are **partial** hook
+clients: session start runs the activation advisory and stop runs the closeout
+advisory. AGY and Pi are **skills-only**. Transition-order and protected-action
+checks stay in the skills on every host. Node.js must be on `PATH` for the
+hook adapters.
 
-Node.js is not required to *use* the skills. Optional typed hook adapters under
-`hooks/` run only when a client registers them; hookless clients remain
-first-class and use procedural skill checks.
+**Skills-only copy** of `skills/` into a host skills directory does not
+register hooks. That path remains first-class. See
+[`hooks/com.anthropic.claude-code/mapping.md`](hooks/com.anthropic.claude-code/mapping.md).
 
 ## What it does
 
-1. **Locate** the project plan and next ready task.
+1. **Ask** whether the Journey is an Explorer Journey or an Expedition.
 2. **Fill only missing planning stages:** Repository Fit → Set Bearings → Gather
    Supplies → Map the Route.
-3. **Choose the smallest role route** that preserves dependencies and
-   `required_assurance`.
-4. **Record task state** only in the project's human-readable plan (Markdown).
-5. **Return structured handoffs**; parent coordinators write plan transitions.
+3. **Confirm** the user-owned primary/fallback lineup and review cadence.
+4. **Dispatch fresh sessions** with bounded context, authority, and return types.
+5. **Record state visibly** in human-readable Markdown artifacts only.
 
 Bearing Lite never selects models, providers, credentials, or launchers. The
-owner or client maps available agents to role capability needs.
+owner provides each role's primary/fallback agent or harness, model, and
+reasoning level in `~/.agents/bearing-lite/default-role-lineup.md`, then confirms
+the applicable Journey snapshot before implementation.
 
 ## Routes and scaling
 
 | Route | When | Cost |
 |---|---|---|
-| **Direct** | One bounded implementer packet | Lowest coordination |
-| **Explorer (wave)** | One wave, one or more Crewmates | One lane controller |
+| **Explorer Journey** | One bounded packet or one wave | Direct Crewmate or one Explorer |
 | **Expedition** | Multi-phase or concurrent independent lanes | Navigator; Trail Boss only for concurrent/conflicting waves |
-| **Long multi-phase** | Owner-approved intent across sessions | Optional Delegate Authority |
 
-**Explorer** keeps one controller over a compact or sequential set of slices.
+An **Explorer Journey** uses a direct Crewmate for one ready packet or one
+Explorer over a compact/sequential wave.
 **Expedition** adds navigation (and sometimes a Trail Boss) so independent lanes
 stay small and sharp instead of degrading in one long context. Either shape can
 use substantial tokens; the product does not impose a default budget ceiling.
 
 ### Role routing (explanatory)
 
-![Bearing Lite role routing: Owner Authority and the router select missing planning stages, then the smallest route among Direct Crewmate, Explorer wave, Expedition Navigator, or long multi-phase Delegate Authority; optional Trail Boss, Sub-explorer, and assurance roles appear only when required](skills/bearing-lite/assets/role-routing.png)
-
-Reviewable Mermaid source: [`skills/bearing-lite/references/role-routing.mmd`](skills/bearing-lite/references/role-routing.mmd)
-(plan-local twin under `docs/plans/2026-08-09-bearing-skills-first-architecture/assets/`).
+Current routing diagram source: [`skills/bearing-lite/references/role-routing.mmd`](skills/bearing-lite/references/role-routing.mmd).
+The text below remains authoritative for clients that do not render Mermaid.
 
 **Authoritative text (vision optional):** Owner Authority remains human-only. The
-Bearing Lite Router is entry, not a work role. It invokes only missing planning
-stages, then picks the least costly route: Direct Crewmate; Explorer for one
-wave; Navigator for an expedition (Trail Boss only when waves conflict or run
-concurrently); Delegate Authority only for explicit long multi-phase owner
-delegation. Nested Sub-explorer opens only when a lane must split. After
-Crewmate work, `required_assurance: none` means author self-check plus
-coordinator confirmation; Validator, Park Ranger, and Surveyor appear only when
-listed, owner-selected at slice level, or required by a mandatory phase gate.
-Diagrams explain orientation; they never authorize a transition.
+Bearing Lite Router is the stateful planning controller, not a work role. It
+invokes only missing planning stages in fresh sessions, confirms the owner's
+lineup and cadence, then dispatches an Explorer Journey or Expedition. Nested
+Sub-Explorer opens only for proven-independent lanes. Validator, Park Ranger,
+and Surveyor appear only when declared and when the selected per-slice,
+per-round, or at-end boundary is reached. Diagrams explain orientation; they
+never authorize a transition.
 
 ## Roles and authority
 
 | Role | What it is | Executes | Notes |
 |---|---|---|---|
-| **Router** | Plugin entry procedure | no | Not a work role |
-| **Navigator** | Expedition orchestrator | yes | Owns cross-wave sequencing |
-| **Trail Boss** | Multi-wave controller | yes | Only concurrent or conflicting waves |
-| **Explorer** | One-wave lane controller | yes | Dispatches Crewmates |
-| **Sub-explorer** | Nested lane controller | yes | Only when a lane must split |
-| **Crewmate** | Bounded implementer | yes | Writes only inside declared authority |
-| **Validator** | Evidence sufficiency | yes | Independent of the author |
-| **Park Ranger** | Defect review | yes | Independent of the author |
-| **Surveyor** | User-facing acceptance | no | Read-only acceptance judgment |
-| **Delegate Authority** | Cross-session phase owner | yes | Only when owner explicitly delegates |
+| **Router** | Stateful planning controller | no | User-facing; planning-state writer |
+| **Navigator** | Expedition orchestrator | no | Owns cross-wave sequencing |
+| **Trail Boss** | Multi-wave controller | no | Only concurrent or conflicting waves |
+| **Explorer** | One-wave controller | no | Dispatches Crewmates |
+| **Sub-explorer** | Nested lane controller | no | Only when lanes are proven independent |
+| **Crewmate** | Bounded implementer | yes | Most hands-on work; exact write set |
+| **Validator** | Evidence sufficiency | no | Independent of the author |
+| **Park Ranger** | Defect review | no | Independent of the author |
+| **Surveyor** | User-facing acceptance | no | Read-only outcome judgment |
 | **Owner Authority** | Human decision | n/a | Never an agent role |
 
 **Independent review:** a candidate author never provides their own Validator,
@@ -103,7 +121,7 @@ Failure escalates to the nearest role whose scope can see it:
 |---|---|
 | Within one slice or packet | Explorer or nearest parent |
 | Across slices in a wave | Trail Boss when present, else Navigator |
-| Across phases | Navigator or Delegate Authority |
+| Across phases | Navigator |
 | Contract, security, or authority change | Owner Authority |
 
 ## Task state (explanatory)
@@ -177,7 +195,7 @@ flowchart TD
 |---|---|
 | `plugin.json` | Agent Plugins v1.0.0 manifest |
 | `skills/` | Router, planning stages, and role skills |
-| `hooks/` | Optional client-specific sequencing adapters |
+| `hooks/` | Four portable class adapters plus the verified Claude Code / Codex mapping |
 | `README.md` and governance docs | Public product and conduct surfaces |
 
 There is no `mcp.json`, `bin` entrypoint, postinstall, or runtime dependency on
@@ -189,14 +207,6 @@ Skills declare **capabilities** (reasoning depth, repository access, mutation
 tools, independence, optional vision). They never pin a model, provider API key,
 default route, or launcher. Owners and clients choose how to satisfy each role.
 
-## Migration note
-
-Bearing Lite does not import historical deep-harness run directories or hidden
-runtime state. Resume from the approved project plan and a verified
-human-readable handoff using native agent tools. See
-[guide/migration.md](guide/migration.md) for existing-run migration and
-owner distribution checkpoints.
-
 ## Contributing
 
 Issues and carefully scoped pull requests help. See

package/hooks/activation.cjs

@@ -4,7 +4,8 @@
 /**
  * Bearing Lite activation/context advisory adapter (CONTRACT-HOOK-01).
  * Advisory only: outcomes are ADVISE or UNAVAILABLE. Never fabricates BLOCK.
- * Skills-only clients: enforcement remains procedural until a verified host maps it.
+ * Skills-only clients: enforcement remains procedural. Claude Code and Codex
+ * use the verified partial mapping in hooks/com.anthropic.claude-code/.
  */
 
 const HOOK_CLASS = "activation";

package/hooks/com.anthropic.claude-code/host.cjs

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Verified host adapter (CONTRACT-HOOK-01, CONTRACT-CLIENT-01).
+ *
+ * Claude Code, Codex, Grok Build, Cursor, and Kimi Code deliver session
+ * events. This adapter derives only the Bearing fields that are visible in
+ * the project plan, then calls the portable class evaluators. It never
+ * fabricates BLOCK from a missing field.
+ *
+ * Coverage is partial: activation and closeout are executable; transition and
+ * protected_action stay procedural. Always exit 0 (RISK-12 / RISK-20). Host
+ * blocking, if ever required, is JSON-only — never process status.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const activation = require("../activation.cjs");
+const closeout = require("../closeout.cjs");
+
+const HOST = "com.anthropic.claude-code";
+const COVERAGE = Object.freeze({
+  activation: Object.freeze({ executable: true, procedural: true }),
+  closeout: Object.freeze({ executable: true, procedural: true }),
+  transition: Object.freeze({ executable: false, procedural: true }),
+  protected_action: Object.freeze({ executable: false, procedural: true }),
+});
+
+const MAX_FILES = 20;
+const MAX_BYTES = 256 * 1024;
+const MAX_DEPTH = 3;
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "coverage",
+  ".next",
+  ".cache",
+  "target",
+  "vendor",
+  ".venv",
+  "venv",
+  "skills",
+  "hooks",
+  "test",
+  "tests",
+  "templates",
+]);
+
+const TASK_MARK = /(?:^|\n)###\s*task_id:\s*\S+/;
+const TASK_LINE = /^###\s*task_id:\s*(\S+)\s*$/;
+const FIELD_LINE =
+  /^-\s*(assigned_role|next_action|status|required_assurance|blocker|evidence|candidate_ref|scope|authority|outcome|depends_on|receiving_role|plan_ref|role|subject):\s*(.*)$/;
+const JOURNEY_LINE = /^-\s*journey:\s*(.+)$/i;
+
+const ACTIVATION_EVENTS = new Set([
+  "SessionStart",
+  "UserPromptSubmit",
+  "UserPromptExpansion",
+  "CwdChanged",
+  "SubagentStart",
+]);
+const CLOSEOUT_EVENTS = new Set(["Stop", "SubagentStop", "SessionEnd"]);
+
+const EVENT_ALIASES = Object.freeze({
+  sessionstart: "SessionStart",
+  userpromptsubmit: "UserPromptSubmit",
+  beforesubmitprompt: "UserPromptSubmit",
+  userpromptexpansion: "UserPromptExpansion",
+  cwdchanged: "CwdChanged",
+  subagentstart: "SubagentStart",
+  stop: "Stop",
+  subagentstop: "SubagentStop",
+  sessionend: "SessionEnd",
+  pretooluse: "PreToolUse",
+  posttooluse: "PostToolUse",
+  beforeshellexecution: "PreToolUse",
+  afterfileedit: "PostToolUse",
+});
+
+/**
+ * Normalize Claude, Codex, Grok, Cursor, and Kimi event names.
+ * @param {unknown} name
+ */
+function canonicalizeEvent(name) {
+  if (typeof name !== "string" || !name.trim()) return "";
+  const compact = name.trim().replace(/[_-]/g, "").toLowerCase();
+  return EVENT_ALIASES[compact] || name.trim();
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isPlaceholder(value) {
+  if (typeof value !== "string") return false;
+  const trimmed = value.trim();
+  return trimmed === "" || trimmed === "unassigned" || /^<[^>]+>$/.test(trimmed);
+}
+
+function presentString(value) {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (!trimmed || isPlaceholder(trimmed)) return undefined;
+  return trimmed;
+}
+
+function readStdinSync() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (err) {
+    const code = err && err.code;
+    if (code === "EAGAIN" || code === "EOF") return "";
+    throw err;
+  }
+}
+
+function rankMarkdown(name) {
+  const n = name.toLowerCase();
+  if (n === "plan.md" || n === "progress.md") return 0;
+  if (n.includes("plan")) return 1;
+  if (n.includes("implementation") || n.includes("progress")) return 2;
+  return 5;
+}
+
+function walkMarkdown(root) {
+  const out = [];
+  function walk(dir, depth) {
+    if (out.length >= MAX_FILES || depth > MAX_DEPTH) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const files = [];
+    const dirs = [];
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      if (entry.name.startsWith(".") && entry.name !== ".agents") continue;
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) dirs.push(entry.name);
+      } else if (entry.isFile() && /\.(md|markdown)$/i.test(entry.name)) {
+        files.push(entry.name);
+      }
+    }
+    files.sort((a, b) => rankMarkdown(a) - rankMarkdown(b) || a.localeCompare(b));
+    for (const name of files) {
+      if (out.length >= MAX_FILES) return;
+      out.push(path.join(dir, name));
+    }
+    dirs.sort((a, b) => {
+      if (a === "docs") return -1;
+      if (b === "docs") return 1;
+      if (a === "plans") return -1;
+      if (b === "plans") return 1;
+      return a.localeCompare(b);
+    });
+    for (const name of dirs) {
+      walk(path.join(dir, name), depth + 1);
+    }
+  }
+  walk(root, 0);
+  return out;
+}
+
+function parsePlanMarkdown(text) {
+  const tasks = [];
+  let journey = null;
+  let current = null;
+  for (const line of String(text).split(/\r?\n/)) {
+    const journeyMatch = line.match(JOURNEY_LINE);
+    if (journeyMatch) {
+      const value = presentString(journeyMatch[1]);
+      if (value) journey = value;
+    }
+    const taskMatch = line.match(TASK_LINE);
+    if (taskMatch) {
+      if (current) tasks.push(current);
+      current = { task_id: taskMatch[1] };
+      continue;
+    }
+    if (!current) continue;
+    const fieldMatch = line.match(FIELD_LINE);
+    if (fieldMatch) {
+      const value = presentString(fieldMatch[2]);
+      if (value !== undefined) current[fieldMatch[1]] = value;
+    }
+  }
+  if (current) tasks.push(current);
+  return { tasks, journey };
+}
+
+/**
+ * Derive Bearing domain fields from visible Markdown in cwd.
+ * Does not invent router_invoked, assigned_role, or next_action.
+ * @param {string} cwd
+ */
+function deriveContext(cwd) {
+  const files = walkMarkdown(cwd);
+  const allTasks = [];
+  let journey = null;
+  let planPresent = false;
+  for (const file of files) {
+    let text;
+    try {
+      const st = fs.statSync(file);
+      if (!st.isFile() || st.size > MAX_BYTES) continue;
+      text = fs.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    if (!TASK_MARK.test(text) && !/^-\s*assigned_role:/m.test(text)) continue;
+    planPresent = true;
+    const parsed = parsePlanMarkdown(text);
+    if (parsed.journey) journey = parsed.journey;
+    for (const task of parsed.tasks) allTasks.push(task);
+  }
+
+  const active =
+    allTasks.find((task) => {
+      const status = presentString(task.status);
+      return status && status !== "COMPLETE" && status !== "CANCELLED";
+    }) ||
+    allTasks[0] ||
+    null;
+
+  const assignedRole = active ? presentString(active.assigned_role) : undefined;
+  const nextAction = active ? presentString(active.next_action) : undefined;
+
+  return {
+    plan_present: planPresent,
+    router_invoked: Boolean(journey),
+    assigned_role: assignedRole,
+    next_action: nextAction,
+    next_action_known: Boolean(nextAction),
+    active_task: active,
+    journey,
+  };
+}
+
+function classForEvent(eventName) {
+  const canonical = canonicalizeEvent(eventName);
+  if (ACTIVATION_EVENTS.has(canonical)) return "activation";
+  if (CLOSEOUT_EVENTS.has(canonical)) return "closeout";
+  return null;
+}
+
+function formatAdvice(verdict) {
+  const lines = [
+    "Bearing Lite " + verdict.hook_class + ": " + verdict.outcome,
+    verdict.reason ? "reason: " + verdict.reason : "",
+    verdict.recovery ? "recovery: " + verdict.recovery : "",
+    "Coverage: this host mapping is partial. activation and closeout are executable; transition and protected_action remain procedural.",
+  ].filter(Boolean);
+  return lines.join("\n").slice(0, 4000);
+}
+
+function unavailableHost(eventName, reason) {
+  const event = eventName || "SessionStart";
+  return {
+    hookSpecificOutput: {
+      hookEventName: event,
+      additionalContext:
+        "Bearing Lite UNAVAILABLE: " +
+        reason +
+        ". Invoke the bearing-lite router manually and continue after context is loaded.",
+    },
+  };
+}
+
+/**
+ * Translate a portable verdict into Claude Code / Codex JSON.
+ * Exit status is never used for policy (RISK-12 / RISK-20).
+ */
+function toHostResponse(eventName, verdict) {
+  const event = eventName || "SessionStart";
+  const text = formatAdvice(verdict);
+  const body = {
+    hookSpecificOutput: {
+      hookEventName: event,
+      additionalContext: text,
+    },
+  };
+  // This mapping never requests protected_completion, so BLOCK should not
+  // appear. If a future caller passes a BLOCK verdict, use JSON only.
+  if (verdict.outcome === "BLOCK") {
+    body.decision = "block";
+    body.reason = text;
+  }
+  return body;
+}
+
+function evaluateForHost(eventName, derived) {
+  if (classForEvent(eventName) === "closeout") {
+    const task = derived.active_task || {};
+    return closeout.evaluate({
+      plan_ref: derived.plan_present ? "project-plan" : undefined,
+      role: presentString(task.assigned_role) || presentString(task.role),
+      subject: presentString(task.task_id) || presentString(task.subject),
+      depends_on: task.depends_on,
+      scope: presentString(task.scope),
+      authority: presentString(task.authority),
+      outcome: presentString(task.outcome),
+      evidence: presentString(task.evidence),
+      blocker: presentString(task.blocker) || "none",
+      next_action: presentString(task.next_action),
+      receiving_role: presentString(task.receiving_role),
+      required_assurance: task.required_assurance,
+    });
+  }
+  return activation.evaluate({
+    plan_present: derived.plan_present === true,
+    next_action_known: derived.next_action_known === true,
+    next_action: derived.next_action,
+    assigned_role: derived.assigned_role,
+    router_invoked: derived.router_invoked === true,
+  });
+}
+
+/**
+ * @param {unknown} input
+ */
+function handle(input) {
+  let parsed = input;
+  if (typeof parsed === "string") {
+    try {
+      parsed = JSON.parse(parsed);
+    } catch {
+      return unavailableHost("SessionStart", "malformed_input");
+    }
+  }
+  if (parsed === undefined || parsed === null) {
+    return unavailableHost("SessionStart", "missing_input");
+  }
+  if (!isPlainObject(parsed)) {
+    return unavailableHost("SessionStart", "malformed_input");
+  }
+
+  const eventName = canonicalizeEvent(
+    parsed.hook_event_name || parsed.hookEventName
+  );
+  if (!classForEvent(eventName)) {
+    return unavailableHost(eventName || "SessionStart", "unmapped_host_event");
+  }
+
+  const cwd =
+    presentString(parsed.cwd) ||
+    presentString(parsed.workspaceRoot) ||
+    process.cwd();
+
+  let derived;
+  try {
+    derived = deriveContext(cwd);
+  } catch {
+    return toHostResponse(
+      eventName,
+      activation.evaluate({ infrastructure_failure: "permission_error" })
+    );
+  }
+
+  return toHostResponse(eventName, evaluateForHost(eventName, derived));
+}
+
+function main() {
+  let raw = "";
+  try {
+    raw = readStdinSync();
+  } catch {
+    process.stdout.write(JSON.stringify(unavailableHost("SessionStart", "stdin_read_failure")) + "\n");
+    process.exit(0);
+    return;
+  }
+
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    process.stdout.write(JSON.stringify(unavailableHost("SessionStart", "missing_input")) + "\n");
+    process.exit(0);
+    return;
+  }
+
+  process.stdout.write(JSON.stringify(handle(trimmed)) + "\n");
+  process.exit(0);
+}
+
+module.exports = {
+  HOST,
+  COVERAGE,
+  canonicalizeEvent,
+  classForEvent,
+  deriveContext,
+  evaluateForHost,
+  handle,
+  toHostResponse,
+};
+
+if (require.main === module) {
+  main();
+}

package/hooks/com.anthropic.claude-code/mapping.md

@@ -0,0 +1,63 @@
+# Verified host mapping
+
+This adapter is the verified native mapping for hosts that share a
+session-start / stop command hook. Coverage is **partial**: activation and
+closeout are executable; transition-order and protected-action stay
+procedural.
+
+## Hosts
+
+| Host | Plugin install | Hooks | Coverage |
+|---|---|---|---|
+| Claude Code | `.claude-plugin/` marketplace | `hooks/hooks.json` | partial |
+| Codex | `.codex-plugin/` + `.agents/plugins/` | `hooks/hooks.json` | partial |
+| Grok Build | `.grok-plugin/` marketplace | `hooks/hooks.json` | partial |
+| Cursor | `.cursor-plugin/` | `hooks/com.cursor/hooks.json` (`sessionStart`, `stop`) | partial |
+| Kimi Code | `.kimi-plugin/plugin.json` | manifest `hooks` array | partial |
+| AGY | `.agy/` (strict `plugin.json`) | none | skills-only |
+| Pi | `package.json` `"pi"` + `pi-package` | none (TypeScript extensions, not command hooks) | skills-only |
+
+Do **not** set `hooks` on Claude, Codex, or Grok host manifests. Those hosts
+auto-load `hooks/hooks.json`; declaring both is a duplicate-file error.
+
+Skill-copy into a host skills directory does **not** register hooks. Plugin
+install or disable uses the host's native controls. Bearing Lite never copies
+adapters into global hook configuration.
+
+## Event map
+
+| Host event names | Bearing class | Executable? |
+|---|---|---|
+| `SessionStart`, `sessionStart`, `session_start` | activation | yes, advisory |
+| `Stop`, `stop` | closeout | yes, advisory only |
+| any other host event | none | unmapped; fail open as `UNAVAILABLE` |
+
+The adapter accepts snake_case and camelCase (`hook_event_name` /
+`hookEventName`, `cwd` / `workspaceRoot`).
+
+## Derived fields
+
+The host event supplies session metadata. The adapter reads visible Markdown
+under `cwd` (bounded; skips `skills/`, `hooks/`, `test/`, and dependency
+trees) and sets only:
+
+| Bearing field | Source |
+|---|---|
+| `plan_present` | a Markdown file contains a `task_id` or `assigned_role` block |
+| `router_invoked` | a `- journey:` setting is present and not a placeholder |
+| `assigned_role` | active task `assigned_role` when not `unassigned` or `<…>` |
+| `next_action` / `next_action_known` | active task `next_action` when not a placeholder |
+| closeout handoff fields | matching task-record keys when present |
+
+`assigned_role` and `router_invoked` are **not** inferred from the tool-call
+payload. Missing values stay missing, so activation advises the router instead
+of inventing context.
+
+## Outcome translation
+
+| Outcome | Host JSON | Process exit |
+|---|---|---|
+| `ADVISE`, `REROUTE`, `UNAVAILABLE` | `hookSpecificOutput.additionalContext` | always `0` |
+| `BLOCK` | JSON `decision: "block"` only; this mapping never requests protected completion | always `0` |
+
+Never map policy or infrastructure to a non-zero exit.