@alphazede/bearing-lite 0.1.0

package/hooks/protected-action.cjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Bearing Lite protected-action integrity adapter (CONTRACT-HOOK-01).
+ * BLOCKs only explicit positive protected-action violations.
+ * Repair, status, owner communication, and safe rollback remain reachable.
+ * Infrastructure failure never becomes BLOCK or implicit permission.
+ */
+
+const HOOK_CLASS = "protected_action";
+const OUTCOMES = Object.freeze(["ADVISE", "REROUTE", "BLOCK", "UNAVAILABLE"]);
+const ENFORCEMENT = "procedural";
+
+const RECOVERY_UNAVAILABLE =
+  "Keep the action pending; obtain normal owner approval when owner-only, otherwise complete the equivalent procedural integrity check before retrying";
+const RECOVERY_ALLOW =
+  "Proceed only within declared authority; leave the project plan as the only task record";
+const RECOVERY_CHANNEL =
+  "Keep repair, status, owner communication, and safe rollback available while the protected action stays pending";
+const RECOVERY_OWNER =
+  "Route to OWNER_DECISION_REQUIRED with evidence, blocker, and the smallest owner choices; do not expand authority";
+
+const SAFE_CHANNELS = new Set([
+  "repair",
+  "status",
+  "owner_communication",
+  "safe_rollback",
+]);
+
+/** Explicit positive violation categories (design hard-block list). */
+const VIOLATION_KEYS = Object.freeze([
+  "owner_authority_violation",
+  "destructive_public_without_authority",
+  "secret_exposure",
+  "repository_ambiguous",
+  "evidence_dishonest",
+]);
+
+/**
+ * Owner authorization may waive only authority-dependent actions.
+ * Secret exposure, dishonest evidence, and repository ambiguity are never waivable.
+ */
+const WAIVABLE_VIOLATIONS = new Set([
+  "owner_authority_violation",
+  "destructive_public_without_authority",
+]);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function result(outcome, reason, recovery, extra) {
+  const body = {
+    hook_class: HOOK_CLASS,
+    outcome,
+    reason,
+    recovery,
+    enforcement: ENFORCEMENT,
+  };
+  if (extra && typeof extra.protected_action === "string" && extra.protected_action) {
+    body.protected_action = extra.protected_action;
+  }
+  return body;
+}
+
+function unavailable(reason) {
+  return result("UNAVAILABLE", reason, RECOVERY_UNAVAILABLE);
+}
+
+function actionId(input) {
+  if (typeof input.protected_action === "string" && input.protected_action.trim()) {
+    return input.protected_action.trim();
+  }
+  if (typeof input.action === "string" && input.action.trim()) {
+    return input.action.trim();
+  }
+  return "protected_action";
+}
+
+/**
+ * @param {unknown} input
+ */
+function evaluate(input) {
+  try {
+    if (input === undefined || input === null) {
+      return unavailable("missing_input");
+    }
+    if (typeof input === "string") {
+      try {
+        input = JSON.parse(input);
+      } catch {
+        return unavailable("malformed_input");
+      }
+    }
+    if (!isPlainObject(input)) {
+      return unavailable("malformed_input");
+    }
+
+    if (input.infrastructure_failure) {
+      return unavailable(String(input.infrastructure_failure) || "infrastructure_failure");
+    }
+
+    // Never block the communication path needed to resolve a finding.
+    if (SAFE_CHANNELS.has(input.channel) || SAFE_CHANNELS.has(input.action_kind)) {
+      return result("ADVISE", "channel_open", RECOVERY_CHANNEL);
+    }
+
+    const id = actionId(input);
+    const ownerAuthorized = input.owner_authorized === true;
+
+    // Collect only explicit positive violation flags (truthy booleans or listed categories).
+    const categories = Array.isArray(input.violation_categories)
+      ? input.violation_categories.map(String)
+      : [];
+    const hits = [];
+
+    for (const key of VIOLATION_KEYS) {
+      if (input[key] === true || categories.includes(key)) {
+        hits.push(key);
+      }
+    }
+
+    // Generic explicit_violation requires a named category; bare true alone is not enough
+    // to invent a security finding.
+    if (input.explicit_violation === true && hits.length === 0) {
+      if (typeof input.reason_code === "string" && input.reason_code.trim()) {
+        hits.push(input.reason_code.trim());
+      }
+    }
+
+    if (hits.length > 0) {
+      const nonWaivable = hits.filter((h) => !WAIVABLE_VIOLATIONS.has(h));
+      if (nonWaivable.length > 0) {
+        // Non-waivable integrity findings always hard-block, even with owner_authorized.
+        return result(
+          "BLOCK",
+          "protected_violation:" + nonWaivable.join("+"),
+          RECOVERY_OWNER,
+          { protected_action: id }
+        );
+      }
+      if (!ownerAuthorized) {
+        return result(
+          "BLOCK",
+          "protected_violation:" + hits.join("+"),
+          RECOVERY_OWNER,
+          { protected_action: id }
+        );
+      }
+      // All hits are authority-dependent and explicitly owner-authorized.
+      return result(
+        "ADVISE",
+        "owner_authorized:" + hits.join("+"),
+        RECOVERY_ALLOW,
+        { protected_action: id }
+      );
+    }
+
+    // Owner-only action declared without owner confirmation: keep pending (not a fabricated block
+    // unless a positive violation flag is set). Report REROUTE to owner when marked owner_only.
+    if (input.owner_only === true && !ownerAuthorized) {
+      return result(
+        "REROUTE",
+        "owner_confirmation_required",
+        RECOVERY_OWNER,
+        { protected_action: id }
+      );
+    }
+
+    return result("ADVISE", "protected_action_clear", RECOVERY_ALLOW, {
+      protected_action: id,
+    });
+  } catch {
+    return unavailable("adapter_exception");
+  }
+}
+
+function readStdinSync() {
+  try {
+    return require("node:fs").readFileSync(0, "utf8");
+  } catch (err) {
+    const code = err && err.code;
+    if (code === "EAGAIN" || code === "EOF") return "";
+    throw err;
+  }
+}
+
+function main() {
+  let raw = "";
+  try {
+    raw = readStdinSync();
+  } catch {
+    process.stdout.write(JSON.stringify(unavailable("stdin_read_failure")) + "\n");
+    process.exit(0);
+    return;
+  }
+
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    process.stdout.write(JSON.stringify(unavailable("missing_input")) + "\n");
+    process.exit(0);
+    return;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    process.stdout.write(JSON.stringify(unavailable("malformed_input")) + "\n");
+    process.exit(0);
+    return;
+  }
+
+  process.stdout.write(JSON.stringify(evaluate(parsed)) + "\n");
+  process.exit(0);
+}
+
+module.exports = {
+  HOOK_CLASS,
+  OUTCOMES,
+  ENFORCEMENT,
+  VIOLATION_KEYS,
+  evaluate,
+};
+
+if (require.main === module) {
+  main();
+}

package/hooks/transition-order.cjs

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Bearing Lite transition-order integrity adapter (CONTRACT-HOOK-01).
+ * Reroutes missing prerequisites; BLOCKs only explicit positive sequence violations.
+ * Never fabricates BLOCK from infrastructure failure. Safe channels stay open.
+ */
+
+const HOOK_CLASS = "transition";
+const OUTCOMES = Object.freeze(["ADVISE", "REROUTE", "BLOCK", "UNAVAILABLE"]);
+const ENFORCEMENT = "procedural";
+
+const RECOVERY_UNAVAILABLE =
+  "Keep the current state, run the transition checklist procedurally, and record the result before retrying";
+const RECOVERY_ALLOW =
+  "Proceed with the requested transition and update the project plan as the only task record";
+const RECOVERY_CHANNEL =
+  "Keep repair, status, owner communication, and safe rollback available; do not treat them as sequence violations";
+
+/** Legal directed edges from CONTRACT-STATE-01 / task-state text. */
+const LEGAL = Object.freeze({
+  PROPOSED: ["READY", "WAITING_ON"],
+  READY: ["IN_PROGRESS", "OWNER_DECISION_REQUIRED"],
+  WAITING_ON: ["READY", "EVIDENCE_READY", "CANCELLED"],
+  IN_PROGRESS: ["EVIDENCE_READY", "CORRECTION_REQUIRED", "OWNER_DECISION_REQUIRED"],
+  EVIDENCE_READY: [
+    "VALIDATING",
+    "REVIEWING",
+    "ACCEPTANCE",
+    "WAITING_ON",
+  ],
+  VALIDATING: ["EVIDENCE_READY", "CORRECTION_REQUIRED"],
+  REVIEWING: ["EVIDENCE_READY", "CORRECTION_REQUIRED", "OWNER_DECISION_REQUIRED"],
+  ACCEPTANCE: ["COMPLETE", "CORRECTION_REQUIRED"],
+  CORRECTION_REQUIRED: ["READY", "OWNER_DECISION_REQUIRED"],
+  OWNER_DECISION_REQUIRED: ["READY", "CANCELLED"],
+  COMPLETE: [],
+  CANCELLED: [],
+});
+
+const SAFE_CHANNELS = new Set([
+  "repair",
+  "status",
+  "owner_communication",
+  "safe_rollback",
+]);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function result(outcome, reason, recovery, extra) {
+  const body = {
+    hook_class: HOOK_CLASS,
+    outcome,
+    reason,
+    recovery,
+    enforcement: ENFORCEMENT,
+  };
+  if (extra && typeof extra.protected_action === "string" && extra.protected_action) {
+    body.protected_action = extra.protected_action;
+  }
+  return body;
+}
+
+function unavailable(reason) {
+  return result("UNAVAILABLE", reason, RECOVERY_UNAVAILABLE);
+}
+
+function normalizeAssurance(value) {
+  if (value === undefined || value === null || value === "" || value === "none") {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.map(String).filter((s) => s && s !== "none");
+  }
+  return [String(value)].filter((s) => s && s !== "none");
+}
+
+/** Normalize role labels for order comparison (Validator vs validator vs park-ranger). */
+function normalizeRoleKey(role) {
+  return String(role)
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-");
+}
+
+/**
+ * Map the next missing assurance role to the state that should receive it.
+ * Validator -> VALIDATING, Park Ranger -> REVIEWING, Surveyor -> ACCEPTANCE.
+ */
+function assuranceTargetState(role) {
+  const key = normalizeRoleKey(role);
+  if (key === "validator") return "VALIDATING";
+  if (key === "park-ranger" || key === "parkranger") return "REVIEWING";
+  if (key === "surveyor") return "ACCEPTANCE";
+  return null;
+}
+
+/**
+ * @param {unknown} input
+ */
+function evaluate(input) {
+  try {
+    if (input === undefined || input === null) {
+      return unavailable("missing_input");
+    }
+    if (typeof input === "string") {
+      try {
+        input = JSON.parse(input);
+      } catch {
+        return unavailable("malformed_input");
+      }
+    }
+    if (!isPlainObject(input)) {
+      return unavailable("malformed_input");
+    }
+
+    if (input.infrastructure_failure) {
+      return unavailable(String(input.infrastructure_failure) || "infrastructure_failure");
+    }
+
+    if (SAFE_CHANNELS.has(input.channel) || SAFE_CHANNELS.has(input.action_kind)) {
+      return result("ADVISE", "channel_open", RECOVERY_CHANNEL);
+    }
+
+    const from = typeof input.from_state === "string" ? input.from_state.trim() : "";
+    const to = typeof input.to_state === "string" ? input.to_state.trim() : "";
+    if (!from || !to) {
+      return unavailable("malformed_input");
+    }
+    if (!Object.prototype.hasOwnProperty.call(LEGAL, from)) {
+      return unavailable("unknown_from_state");
+    }
+
+    const legalTargets = LEGAL[from] || [];
+    const required = normalizeAssurance(input.required_assurance);
+    const completed = Array.isArray(input.assurance_completed)
+      ? input.assurance_completed.map(String)
+      : [];
+    const missingAssurance = required.filter((role) => !completed.includes(role));
+    const prerequisitesMet = input.prerequisites_met !== false;
+    const explicitSkip = input.skip_required_step === true;
+    const afterReroute = input.after_reroute === true;
+    const invalidatesDependents = input.invalidates_dependents === true;
+
+    // Hard block only for explicit positive violations (DEC-HOOK-03 / DEC-HOOK-02).
+    if (explicitSkip && afterReroute) {
+      return result(
+        "BLOCK",
+        "required_step_skipped_after_reroute",
+        "Stop the invalid transition; reroute remains recorded; restore the missing step before retrying",
+        { protected_action: "transition:" + from + "->" + to }
+      );
+    }
+
+    if (explicitSkip && invalidatesDependents) {
+      return result(
+        "BLOCK",
+        "sequence_violation_invalidates_dependents",
+        "Stop the transition that would invalidate dependents; repair the sequence before retrying",
+        { protected_action: "transition:" + from + "->" + to }
+      );
+    }
+
+    if (!legalTargets.includes(to)) {
+      return result(
+        "REROUTE",
+        "illegal_transition:" + from + "->" + to,
+        "Return to a legal edge from " + from + "; do not invent a state jump"
+      );
+    }
+
+    if (!prerequisitesMet) {
+      const missing =
+        typeof input.missing_step === "string" && input.missing_step.trim()
+          ? input.missing_step.trim()
+          : "prerequisite";
+      return result(
+        "REROUTE",
+        "missing_prerequisite:" + missing,
+        "Perform missing step `" + missing + "` and record evidence before retrying " + from + "->" + to
+      );
+    }
+
+    // Completing while required assurance is still open.
+    if (to === "COMPLETE" && missingAssurance.length > 0) {
+      if (explicitSkip) {
+        return result(
+          "BLOCK",
+          "required_assurance_skipped:" + missingAssurance.join(","),
+          "Complete required assurance roles before protected completion",
+          { protected_action: "transition:ACCEPTANCE->COMPLETE" }
+        );
+      }
+      return result(
+        "REROUTE",
+        "required_assurance_pending:" + missingAssurance.join(","),
+        "Dispatch the next missing assurance role: " + missingAssurance[0]
+      );
+    }
+
+    // Assurance order: only the next missing role's state is allowed.
+    // E.g. Validator done, Park Ranger pending -> REVIEWING allowed, ACCEPTANCE reroutes.
+    if (
+      missingAssurance.length > 0 &&
+      (to === "VALIDATING" || to === "REVIEWING" || to === "ACCEPTANCE")
+    ) {
+      const nextRole = missingAssurance[0];
+      const expectedTo = assuranceTargetState(nextRole);
+      if (!expectedTo || to !== expectedTo) {
+        return result(
+          "REROUTE",
+          "assurance_order:" + nextRole,
+          "Run assurance in declared order; next required role is " + nextRole
+        );
+      }
+    }
+
+    if (explicitSkip) {
+      // First detection: reroute before hard block.
+      const step =
+        typeof input.missing_step === "string" && input.missing_step.trim()
+          ? input.missing_step.trim()
+          : missingAssurance[0] || "required_step";
+      return result(
+        "REROUTE",
+        "required_step_skipped:" + step,
+        "Reroute to missing step `" + step + "`; hard block only after a repeated skip"
+      );
+    }
+
+    return result("ADVISE", "transition_allowed:" + from + "->" + to, RECOVERY_ALLOW);
+  } catch {
+    return unavailable("adapter_exception");
+  }
+}
+
+function readStdinSync() {
+  try {
+    return require("node:fs").readFileSync(0, "utf8");
+  } catch (err) {
+    const code = err && err.code;
+    if (code === "EAGAIN" || code === "EOF") return "";
+    throw err;
+  }
+}
+
+function main() {
+  let raw = "";
+  try {
+    raw = readStdinSync();
+  } catch {
+    process.stdout.write(JSON.stringify(unavailable("stdin_read_failure")) + "\n");
+    process.exit(0);
+    return;
+  }
+
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    process.stdout.write(JSON.stringify(unavailable("missing_input")) + "\n");
+    process.exit(0);
+    return;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    process.stdout.write(JSON.stringify(unavailable("malformed_input")) + "\n");
+    process.exit(0);
+    return;
+  }
+
+  process.stdout.write(JSON.stringify(evaluate(parsed)) + "\n");
+  process.exit(0);
+}
+
+module.exports = {
+  HOOK_CLASS,
+  OUTCOMES,
+  ENFORCEMENT,
+  LEGAL,
+  evaluate,
+};
+
+if (require.main === module) {
+  main();
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@alphazede/bearing-lite",
+  "version": "0.1.0",
+  "description": "Skills-first Agent Plugin for planning, routing, bounded execution, and independent review of repository work—without CLI, MCP, server, or hidden runtime state.",
+  "keywords": [
+    "agent-plugins",
+    "agent-skills",
+    "coding-agent",
+    "planning",
+    "workflow",
+    "developer-tools",
+    "skills-first",
+    "evidence",
+    "code-review"
+  ],
+  "author": "William Rumph / AlphaZede",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alphazede/bearing-lite.git"
+  },
+  "homepage": "https://github.com/alphazede/bearing-lite#readme",
+  "bugs": {
+    "url": "https://github.com/alphazede/bearing-lite/issues"
+  },
+  "files": [
+    "plugin.json",
+    "skills/",
+    "hooks/",
+    "README.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "LICENSE-APACHE",
+    "guide/migration.md"
+  ]
+}

package/plugin.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "bearing-lite",
+  "version": "0.1.0",
+  "description": "Skills-first portable plugin that routes repository work through the smallest valid planning stages and agent roles, using project Markdown as the only task record.",
+  "author": {
+    "name": "William Rumph / AlphaZede",
+    "url": "https://github.com/alphazede"
+  },
+  "homepage": "https://github.com/alphazede/bearing-lite#readme",
+  "repository": "https://github.com/alphazede/bearing-lite",
+  "license": "Apache-2.0",
+  "keywords": [
+    "agent-plugins",
+    "agent-skills",
+    "planning",
+    "workflow",
+    "routing",
+    "developer-tools",
+    "skills-first"
+  ]
+}

package/skills/bearing-lite/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: bearing-lite
+description: >
+  Bearing Lite router for entry, resume, or unclear next action on repository
+  work. Locates the project plan, next ready task, dependency state, risk, and
+  smallest valid route among planning stages and roles. Activate for bearing
+  lite, start/resume bearing, route the next task, or choose the minimum role
+  path. Do not use for model or provider selection, package publication, deep
+  harness control-room work, or a single already-assigned role packet.
+---
+
+# Bearing Lite Router
+
+Plugin entry skill. Not a work role. Owner Authority remains human-only.
+
+## Inputs
+
+Plan path, next ready task, dependencies, risk, and available native capabilities.
+
+## Select the smallest route
+
+1. Identify the project plan and next ready task. Missing plan fields stay `PROPOSED`.
+2. Invoke only missing planning stages: `repository-fit`, `set-bearings`, `gather-supplies`, `map-the-route`. Reuse valid evidence; do not replay completed stages.
+3. Choose the least costly role route that preserves dependencies and assurance:
+   - **Direct:** Crewmate → author self-check plus coordinator confirmation when `required_assurance` is `none`; otherwise the declared assurance roles. Add Park Ranger only when required or owner-selected. Validator and Park Ranger appear only when declared, owner-selected, or at a mandatory integrated phase gate.
+   - **Single wave:** Explorer → Crewmate packets with the same assurance rule → Surveyor when multi-packet or owner acceptance requires it. Never automatic Validator per packet.
+   - **Expedition:** Navigator → Trail Boss only for concurrent/conflicting waves → Explorer lanes → optional Sub-explorer → Crewmates, with assurance only where `required_assurance`, owner selection, or a mandatory phase gate requires it.
+   - **Long multi-phase:** Delegate Authority only when the owner explicitly delegates across sessions or Navigator replacement.
+4. Leave dormant roles unselected. No placeholder, receipt, or hidden state.
+5. Report honest hook coverage: full, partial, or skills-only procedural checks.
+
+## Never
+
+- Select models, providers, credentials, launchers, or tool routes.
+- Create, import, or interpret `.bearing` state, MCP, CLI, or a scheduler.
+- Expand owner authority, publish, or self-certify as Validator, Park Ranger, or Surveyor.
+
+## State and task record
+
+Task status lives only in the project plan. See `references/task-state.md` and `templates/task.md`. Orientation diagrams may load later under `references/` and `assets/`; text remains authoritative.

package/skills/bearing-lite/references/role-routing.mmd

@@ -0,0 +1,34 @@
+flowchart TD
+    O[Owner Authority] --> R[Bearing Lite Router]
+    R --> P{Next missing planning stage?}
+    P -->|Repository Fit| PF[Repository Fit]
+    P -->|Set Bearings| SB[Set Bearings]
+    P -->|Gather Supplies| GS[Gather Supplies]
+    P -->|Map the Route| MR[Map the Route]
+    PF --> R
+    SB --> R
+    GS --> R
+    MR --> R
+    P -->|none| Q{Smallest valid route}
+    Q -->|direct| C[Crewmate]
+    Q -->|wave| E[Explorer]
+    Q -->|expedition| N[Navigator]
+    Q -->|long multi-phase| D[Delegate Authority]
+    D --> N
+    N --> TB{Multiple active or conflicting waves?}
+    TB -->|yes| T[Trail Boss]
+    TB -->|no| E
+    T --> E
+    E --> X{Nested split needed?}
+    X -->|yes| SE[Sub-explorer]
+    SE --> C
+    X -->|no| C
+    C --> A{required_assurance / next missing?}
+    A -->|none: coordinator confirms| Q
+    A -->|Validator| V[Validator]
+    A -->|Park Ranger| PK[Park Ranger]
+    A -->|Surveyor| S[Surveyor]
+    A -->|owner acceptance| O
+    V --> A
+    PK --> A
+    S --> O