@alphazede/bearing-lite 0.1.0

package/guide/migration.md

@@ -0,0 +1,168 @@
+# Existing-run migration and distribution checkpoints
+
+How to retire a deep Bearing run without importing hidden runtime state, hand
+work off in a project-local readable record, and resume with Bearing Lite.
+Repository rename and npm deprecation remain separate owner-authorized release
+checkpoints; this guide documents them only and does not perform remote actions.
+
+Bearing Lite does **not** import `.bearing` data, Focus session state, MCP
+runtime state, or CLI journey ledgers. Resume uses a verified human-readable
+handoff, the existing approved plan, Bearing Lite, and native agent tools.
+
+## Existing-run migration
+
+For each project that still has deep Bearing run data, complete these steps in
+order:
+
+1. **Retire the old run read-only.** Leave historical `.bearing/`,
+   `bearing-<plan>/`, Focus, MCP, and CLI runtime data in place. Do not mutate,
+   import, or rewrite it as Lite input.
+2. **Write a project-local human-readable handoff** in the affected repository
+   (for example under that project's planning docs). Fill every field in the
+   checklist below from visible plan text, Git history, and recorded evidence —
+   not from hidden runtime stores.
+3. **Verify the handoff** against the project tree and the current candidate
+   revision: every field is present, paths exist or are intentionally listed as
+   deleted, blockers and dependencies match the plan, and the next action is
+   actionable without deep runtime state.
+4. **Resume through Bearing Lite** using the existing approved plan plus native
+   agent tools. Do not require `.bearing` import, Focus resume, MCP session
+   restore, or CLI ledger continuity to continue work.
+5. **Keep legacy runtime data read-only** until the handoff is verified. Archive
+   or remove retired run data only as a later, separate owner-authorized action.
+
+Stop if migration would require importing hidden runtime state as Lite resume
+input. That is out of scope for Bearing Lite; produce a fuller handoff from
+visible sources instead.
+
+## Project-local handoff checklist
+
+Use one handoff record per existing run (or per coherent plan-bound workspace).
+Every field is required for a complete handoff:
+
+| Field | What to record |
+|---|---|
+| **Approved plan** | Path and identity of the owner-approved plan the run was executing (title, date, or plan directory). |
+| **Completed work** | Slices, waves, or deliverables already finished and accepted, with enough detail that a new agent does not re-implement them. |
+| **Changed paths** | Exact repository paths modified by completed work (added, edited, or intentionally removed). |
+| **Commands / evidence** | Commands run, test or validation results, review verdicts, and other durable proof that completed work actually landed. |
+| **Blockers** | Open blockers, refusals, or owner decisions still required; write `none` only when none remain. |
+| **Dependencies** | Incomplete prerequisites, external packages, environment needs, or cross-slice dependencies that still gate progress. |
+| **Next action** | The single concrete next step for the receiving agent or owner, scoped so Lite can resume without deep runtime state. |
+
+### Representative handoff template
+
+Copy into the affected project and fill every section:
+
+```markdown
+# Migration handoff — <project or plan name>
+
+## Approved plan
+- Plan path:
+- Plan identity / date:
+
+## Completed work
+- [ ] <slice or deliverable>: summary
+
+## Changed paths
+- `path/to/file` — added | edited | removed
+
+## Commands / evidence
+- Command or review: result / artifact path
+
+## Blockers
+- none | <blocker and owner>
+
+## Dependencies
+- none | <dependency and why it still gates work>
+
+## Next action
+- <one concrete next step for Bearing Lite + native tools>
+```
+
+### Handoff review (PROC-MIGRATION-01)
+
+Before treating the handoff as verified, confirm:
+
+- [ ] Approved plan is named and locatable in the project.
+- [ ] Completed work is enumerated without relying on `.bearing` or other hidden state.
+- [ ] Changed paths are explicit and match the tree or intentional removals.
+- [ ] Commands and evidence are durable and inspectable.
+- [ ] Blockers are stated (or explicitly `none`).
+- [ ] Dependencies are stated (or explicitly `none`).
+- [ ] Next action is sufficient to resume with Bearing Lite and native tools only.
+- [ ] No step requires importing `.bearing`, Focus, MCP, or CLI runtime state.
+
+A handoff that omits blockers, dependencies, or next action is incomplete. A
+migration that imports hidden runtime state as Lite input is rejected.
+
+## Read-only legacy retirement
+
+Until the handoff is verified:
+
+- Treat `.bearing/`, plan-bound `bearing-<plan>/` workspaces, Focus contexts,
+  MCP session artifacts, and CLI journey ledgers as **read-only historical
+  evidence**.
+- Do not delete, rewrite, or “upgrade” those stores into Lite state.
+- Do not point Bearing Lite at them as an import or resume source.
+
+After the handoff is verified, archive or remove retired run data only under
+explicit repository-owner authorization as a separate action. Permanent deletion
+is never implied by writing the handoff.
+
+## Distribution checkpoints (documentation only)
+
+These steps are **owner-authorized release checkpoints**. Document them here so
+operators know the approved sequence. This guide does **not** rename a
+repository, publish or deprecate an npm package, mutate remotes, or perform any
+other registry or network publish action.
+
+Approved sequence (PROC-DISTRIBUTION-01 — verify before any remote action):
+
+1. **Repository rename (in place).** Rename the existing public repository from
+   `alphazede/bearing` to `alphazede/bearing-lite` so public Git history remains
+   intact. Do not create a replacement repository that discards history.
+2. **Package identity.** Publish future Lite releases only as
+   `@alphazede/bearing-lite`, and only after exact package and native-client
+   validation plus explicit owner approval.
+3. **Deprecate the old package.** Deprecate `@alphazede/bearing` with a message
+   that directs users to Bearing Lite. Do not republish Lite under the old
+   identity.
+4. **Link and evidence hygiene.** Update public repository, issue, security,
+   marketplace, package, and documentation links to the Lite identity. Keep
+   historical public evidence clearly historical rather than rewriting it as
+   current Lite behavior.
+5. **Protected settings and authorization.** Confirm protected branch or
+   repository settings, registry credentials, and owner authorization before any
+   remote mutation. Remote action without that checkpoint is blocked.
+
+### Pre-remote owner checklist
+
+Before any rename, publish, or deprecation command:
+
+- [ ] Owner has explicitly approved the repository rename
+      `alphazede/bearing` → `alphazede/bearing-lite`.
+- [ ] Owner has explicitly approved publishing `@alphazede/bearing-lite` (not the
+      old package name).
+- [ ] Owner has explicitly approved deprecating `@alphazede/bearing` with a
+      migration message pointing at Lite.
+- [ ] Package identity on the candidate is `@alphazede/bearing-lite`.
+- [ ] Protected settings and release authority are confirmed.
+- [ ] No remote or registry action is performed from documentation-only work.
+
+Repository rename, npm deprecation, and publication remain separate protected
+owner actions. Completing this migration guide does not authorize them.
+
+## What Bearing Lite does not do
+
+- Import or migrate `.bearing` / Focus / MCP / CLI runtime state as resume input.
+- Automatically rewrite deep run data into Lite task records.
+- Perform repository rename, npm publish, npm deprecation, or other remote
+  release actions from ordinary product use.
+- Depend on another Bearing product's runtime, state store, or release gate to
+  resume work.
+
+Resume authority is the verified project-local handoff, the approved plan, and
+native tools under Bearing Lite.
+
+[Back to the README](../README.md)

package/hooks/activation.cjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * 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.
+ */
+
+const HOOK_CLASS = "activation";
+const OUTCOMES = Object.freeze(["ADVISE", "REROUTE", "BLOCK", "UNAVAILABLE"]);
+const ENFORCEMENT = "procedural";
+
+const RECOVERY_UNAVAILABLE =
+  "Report UNAVAILABLE, invoke the bearing-lite router manually, and continue after context is loaded";
+const RECOVERY_ROUTER =
+  "Invoke skills/bearing-lite (router), load the assigned role skill, and record the next action in the project plan";
+const RECOVERY_CONTINUE =
+  "Continue with the assigned role; keep the project plan as the only task record";
+
+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);
+}
+
+/**
+ * @param {unknown} input
+ * @returns {{hook_class:string,outcome:string,reason:string,recovery:string,enforcement:string,protected_action?:string}}
+ */
+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) {
+      const kind = String(input.infrastructure_failure);
+      return unavailable(kind || "infrastructure_failure");
+    }
+
+    // Safe channels must remain reachable; advisory never blocks them.
+    const channel = input.channel;
+    if (
+      channel === "repair" ||
+      channel === "status" ||
+      channel === "owner_communication" ||
+      channel === "safe_rollback"
+    ) {
+      return result(
+        "ADVISE",
+        "channel_open",
+        "Keep repair, status, owner communication, and safe rollback available"
+      );
+    }
+
+    const planPresent = input.plan_present === true;
+    const nextActionKnown =
+      input.next_action_known === true ||
+      (typeof input.next_action === "string" && input.next_action.trim().length > 0);
+    const role =
+      typeof input.assigned_role === "string" && input.assigned_role.trim()
+        ? input.assigned_role.trim()
+        : null;
+    const routerInvoked = input.router_invoked === true;
+    const missingStages = Array.isArray(input.missing_planning_stages)
+      ? input.missing_planning_stages.filter((s) => typeof s === "string" && s.trim())
+      : [];
+
+    if (!planPresent || !nextActionKnown || !role || !routerInvoked || missingStages.length > 0) {
+      const gaps = [];
+      if (!planPresent) gaps.push("plan");
+      if (!nextActionKnown) gaps.push("next_action");
+      if (!role) gaps.push("assigned_role");
+      if (!routerInvoked) gaps.push("router");
+      if (missingStages.length > 0) gaps.push("planning_stages:" + missingStages.join(","));
+      return result("ADVISE", "context_incomplete:" + gaps.join("+"), RECOVERY_ROUTER);
+    }
+
+    return result("ADVISE", "context_ready", RECOVERY_CONTINUE);
+  } 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;
+  }
+
+  const out = evaluate(parsed);
+  process.stdout.write(JSON.stringify(out) + "\n");
+  // Always exit 0: never map policy or infrastructure to process status (RISK-12 / RISK-20).
+  process.exit(0);
+}
+
+module.exports = {
+  HOOK_CLASS,
+  OUTCOMES,
+  ENFORCEMENT,
+  evaluate,
+};
+
+if (require.main === module) {
+  main();
+}

package/hooks/closeout.cjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Bearing Lite return/closeout adapter (CONTRACT-HOOK-01).
+ * Advisory for ordinary handoff reminders; may BLOCK only protected completion.
+ * Infrastructure failure fails open as UNAVAILABLE and never fabricates BLOCK.
+ */
+
+const HOOK_CLASS = "closeout";
+const OUTCOMES = Object.freeze(["ADVISE", "REROUTE", "BLOCK", "UNAVAILABLE"]);
+const ENFORCEMENT = "procedural";
+
+const HANDOFF_FIELDS = Object.freeze([
+  "plan_ref",
+  "role",
+  "subject",
+  "depends_on",
+  "scope",
+  "authority",
+  "outcome",
+  "evidence",
+  "blocker",
+  "next_action",
+  "receiving_role",
+]);
+
+const RECOVERY_UNAVAILABLE =
+  "Report UNAVAILABLE, complete the handoff checklist manually, and do not request protected completion until required fields and assurance are present";
+const RECOVERY_HANDOFF =
+  "Complete the role return envelope (plan_ref, role, subject, depends_on, scope, authority, outcome, evidence, blocker, next_action, receiving_role) in the project plan";
+const RECOVERY_COMPLETE =
+  "Handoff is complete; parent coordinator may advance using the project plan only";
+const RECOVERY_BLOCK_COMPLETION =
+  "Do not mark COMPLETE; restore missing assurance, candidate match, or handoff fields first. Repair and owner channels remain open";
+const RECOVERY_CHANNEL =
+  "Keep repair, status, owner communication, and safe rollback available; closeout does not block them";
+
+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");
+}
+
+function missingHandoffFields(input) {
+  const handoff = isPlainObject(input.handoff) ? input.handoff : input;
+  const missing = [];
+  for (const field of HANDOFF_FIELDS) {
+    const value = handoff[field];
+    if (value === undefined || value === null) {
+      missing.push(field);
+      continue;
+    }
+    if (typeof value === "string" && value.trim() === "") {
+      missing.push(field);
+    }
+  }
+  // blocker may be the string "none"; that is present and valid.
+  return missing;
+}
+
+/**
+ * @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 mode =
+      input.mode === "protected_completion" || input.protected_completion === true
+        ? "protected_completion"
+        : "advisory";
+
+    const missing = missingHandoffFields(input);
+    const required = normalizeAssurance(input.required_assurance);
+    const accepted = Array.isArray(input.assurance_accepted)
+      ? input.assurance_accepted.map(String)
+      : [];
+    const missingAssurance = required.filter((role) => !accepted.includes(role));
+    // Protected completion requires explicit same-candidate proof; omit/false fail closed.
+    // Advisory closeout never uses this flag for outcome selection.
+    const candidateMatched = input.candidate_matched === true;
+    const unresolvedBlocker =
+      input.unresolved_blocker === true ||
+      (typeof input.blocker === "string" &&
+        input.blocker.trim() &&
+        input.blocker.trim() !== "none");
+
+    if (mode === "protected_completion") {
+      const blockers = [];
+      if (missing.length > 0) blockers.push("handoff:" + missing.join(","));
+      if (missingAssurance.length > 0) {
+        blockers.push("assurance:" + missingAssurance.join(","));
+      }
+      if (!candidateMatched) blockers.push("candidate_mismatch");
+      if (unresolvedBlocker) blockers.push("unresolved_blocker");
+
+      if (blockers.length > 0) {
+        return result(
+          "BLOCK",
+          "protected_completion_invalid:" + blockers.join("+"),
+          RECOVERY_BLOCK_COMPLETION,
+          { protected_action: "completion" }
+        );
+      }
+
+      return result(
+        "ADVISE",
+        "protected_completion_ready",
+        RECOVERY_COMPLETE,
+        { protected_action: "completion" }
+      );
+    }
+
+    // Advisory closeout: never BLOCK.
+    if (missing.length > 0) {
+      return result(
+        "ADVISE",
+        "handoff_incomplete:" + missing.join(","),
+        RECOVERY_HANDOFF
+      );
+    }
+
+    if (missingAssurance.length > 0) {
+      return result(
+        "ADVISE",
+        "assurance_pending:" + missingAssurance.join(","),
+        "Do not request protected completion until assurance roles accept the same candidate: " +
+          missingAssurance.join(", ")
+      );
+    }
+
+    return result("ADVISE", "handoff_complete", RECOVERY_COMPLETE);
+  } 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,
+  HANDOFF_FIELDS,
+  evaluate,
+};
+
+if (require.main === module) {
+  main();
+}