@alphazede/bearing-lite 0.1.0 → 0.1.8

package/README.md

@@ -5,93 +5,131 @@
 
 **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.
+
+## Quick start with Pi
+
+Install the published skills package:
+
+```sh
+pi install npm:@alphazede/bearing-lite
+```
+
+Then give your agent a real task:
+
+> Use Bearing Lite to add rate limiting to this API without changing its public
+> responses. Require one independent review at the end.
+
+Bearing Lite asks whether the work is an Explorer Journey or an Expedition,
+fills only the missing planning stages, confirms the agent lineup and review
+cadence, and dispatches bounded sessions with visible Markdown state.
+
+If Bearing Lite helps keep a long agent task scoped and reviewable,
+[star the repository](https://github.com/alphazede/bearing-lite). It helps other
+coding-agent users find it.
 
 ## 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 npm:@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 |
-| **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 Journey** | One bounded packet or one wave | Direct Crewmate or one Explorer |
+| **Expedition** | Multi-phase or concurrent independent lanes | Navigator |
 
-**Explorer** keeps one controller over a compact or sequential set of slices.
-**Expedition** adds navigation (and sometimes a Trail Boss) so independent lanes
+An **Explorer Journey** uses a direct Crewmate for one ready packet or one
+Explorer over a compact/sequential wave.
+**Expedition** adds navigation 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. Explorer
+coordinates proven-independent in-wave lanes without a nested coordinator.
+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 and conflicts |
+| **Explorer** | One-wave controller | no | Dispatches Crewmates; owns proven-independent lanes |
+| **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,
@@ -102,21 +140,21 @@ Failure escalates to the nearest role whose scope can see it:
 | Failure scope | Escalates to |
 |---|---|
 | 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 slices in a wave | Explorer |
+| Across waves or phases | Navigator |
 | Contract, security, or authority change | Owner Authority |
 
 ## Task state (explanatory)
 
-![Bearing Lite task state machine: PROPOSED through READY, IN_PROGRESS, EVIDENCE_READY, optional VALIDATING or REVIEWING, ACCEPTANCE, COMPLETE, with WAITING_ON, CORRECTION_REQUIRED, OWNER_DECISION_REQUIRED, and CANCELLED paths](skills/bearing-lite/assets/task-state.png)
-
-Reviewable Mermaid source: [`skills/bearing-lite/references/task-state.mmd`](skills/bearing-lite/references/task-state.mmd).
+Current task-state diagram source: [`skills/bearing-lite/references/task-state.mmd`](skills/bearing-lite/references/task-state.mmd).
+The text below remains authoritative for clients that do not render Mermaid.
 Authoritative transition rules: [`skills/bearing-lite/references/task-state.md`](skills/bearing-lite/references/task-state.md).
 
 **Authoritative summary:** The project's plan is the only task-state record.
 Normal progress is `PROPOSED` → `READY` → `IN_PROGRESS` → `EVIDENCE_READY`, then
 optional `VALIDATING` / `REVIEWING` when required, then `ACCEPTANCE` →
-`COMPLETE`. `WAITING_ON` holds for missing prerequisites or assurance dispatch.
+`COMPLETE`. `WAITING_ON` holds for missing prerequisites, checkout-lease
+conflict, or assurance dispatch.
 `CORRECTION_REQUIRED` allows two in-authority repairs; a third failed correction
 escalates to `OWNER_DECISION_REQUIRED`. Diagrams never create state or authorize
 transitions.
@@ -177,7 +215,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 +227,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";