@alphazede/bearing-lite 0.1.10 → 0.2.0

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

@@ -16,6 +16,7 @@ procedural.
 | 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 |
+| DeepCode | `.deepcode/skills` or interoperable `.agents/skills` discovery | none | 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.
@@ -30,11 +31,91 @@ adapters into global hook configuration.
 |---|---|---|
 | `SessionStart`, `sessionStart`, `session_start` | activation | yes, advisory |
 | `Stop`, `stop` | closeout | yes, advisory only |
+| `PreToolUse`, `preToolUse`, `beforeShellExecution`, `apply_patch` | te_test_write | only where the host has a native write-time deny |
+| `Stop`, `stop`, `SubagentStop`, `subagentStop` | te_completion | only where the host has a native completion or child-stop deny |
 | any other host event | none | unmapped; fail open as `UNAVAILABLE` |
 
+`hooks/com.anthropic.claude-code/host.cjs` owns activation and closeout and
+maps no Test Engineering class. `hooks/te-host.cjs` owns te_test_write and
+te_completion and maps neither of the original four. The two adapters are
+registered separately, and a `Stop` event reaches both.
+
+The shared planning-review evaluator is used by transition and closeout when a
+client supplies a structured `planning_review` record. Current session-start /
+stop mappings cannot derive that nested record safely, so Claude Code, Codex,
+Grok Build, Cursor, and Kimi remain partial and the check is procedural there.
+AGY, Pi, and DeepCode remain skills-only. Do not claim full planning-review
+enforcement for any of these hosts until a native event supplies the complete
+record.
+
+The per-declared-phase-or-wave assurance record
+(`skills/bearing-lite/references/assurance-policy.md`) is evaluated by the same
+`transition` class through the `assurance_transition` action_kind. No mapped
+host exposes a hook event that carries the frozen declaration and the visible
+task record, so the assurance budget is procedural on every mapped host:
+Claude Code, Codex, Grok Build, Cursor, and Kimi Code stay partial, and AGY,
+Pi, and DeepCode stay skills-only. No host may advertise an enforcement of the
+assurance budget it cannot perform.
+
 The adapter accepts snake_case and camelCase (`hook_event_name` /
 `hookEventName`, `cwd` / `workspaceRoot`).
 
+## Test Engineering classes
+
+`te_test_write` and `te_completion` are **additional** classes, shipped by
+`hooks/te-capability.cjs` and `hooks/te-host.cjs`. They do not rename or
+replace activation, closeout, transition-order, or protected-action, and they
+do not reuse those classes' outcome tokens. Their verdicts are `ALLOW`,
+`DENY_ROUTE_TO_TE`, `DENY_RECEIPT_REQUIRED`, and `UNAVAILABLE`.
+
+Bearing Lite ships no Test Engineering evaluator and no Test Engineering
+method content. The adapter resolves the `test-engineering` capability, loads
+the evaluator at `skills/test-engineering/hooks/te-evaluator.cjs` when that
+capability is present in the workspace, builds the request from the real Git
+checkout and the coordinator-authored plan, and returns the evaluator verdict
+unchanged.
+
+| Capability state | Class result |
+|---|---|
+| neither selected nor required | `UNAVAILABLE`; the class fails open and this is not a failure |
+| selected or required, evaluator absent | `UNAVAILABLE` with `code: typed_capability_gap`; a typed gap, never silent success |
+| selected or required, evaluator loaded | the evaluator verdict, verbatim |
+
+Trusted assignment comes from the visible coordinator-authored plan, never
+from the tool payload or the transcript. Candidate state comes from the
+installed Git executable: the committed `diff_base..HEAD` change plus the
+working tree, scoped to the trusted write set. An empty trusted scope covers
+nothing, so unrelated shared dirt never enters the candidate. Derived runtime
+state under the Bearing runtime directory is never a candidate change.
+
+An artifact on disk is never a local pass token; only the evaluator reads it.
+An `ALLOW` completion verdict is not user acceptance and grants no planning or
+publication authority.
+
+### Host honesty
+
+`native` means the host exposes a verified hard deny for that channel.
+Everything else is `UNAVAILABLE`: the class is procedural on that host and
+this adapter must not advertise enforcement it cannot perform.
+
+| Host | te_test_write channel | te_completion at parent stop | te_completion at child stop |
+|---|---|---|---|
+| Claude Code | native `PreToolUse` deny | native `Stop` deny | native `SubagentStop` deny |
+| Codex | native `PreToolUse` deny | native `Stop` deny | native `SubagentStop` deny |
+| Grok Build | native `PreToolUse` deny | native `Stop` deny | native `SubagentStop` deny |
+| Cursor | native `preToolUse` and `beforeShellExecution` deny | te_completion UNAVAILABLE | child te_completion UNAVAILABLE |
+| Kimi Code | te_test_write UNAVAILABLE | te_completion UNAVAILABLE | child te_completion UNAVAILABLE |
+| Pi | te_test_write UNAVAILABLE | te_completion UNAVAILABLE | child te_completion UNAVAILABLE |
+| AGY | te_test_write UNAVAILABLE | te_completion UNAVAILABLE | child te_completion UNAVAILABLE |
+| DeepCode | te_test_write UNAVAILABLE | te_completion UNAVAILABLE | child te_completion UNAVAILABLE |
+
+Cursor's `stop` guidance message is advisory text, not a hard completion
+block, and Cursor exposes no distinct hard child-stop deny; neither is
+registered as one. Kimi Code, Pi, AGY, and DeepCode carry no verified native
+Test Engineering blocking at all, so `hooks/te-host.cjs` returns `UNAVAILABLE`
+for every class on those hosts rather than claiming an enforcement it cannot
+deliver.
+
 ## Derived fields
 
 The host event supplies session metadata. The adapter reads visible Markdown
@@ -44,15 +125,20 @@ trees) and sets only:
 | Bearing field | Source |
 |---|---|
 | `plan_present` | a Markdown file contains a `task_id`, `assigned_role`, non-placeholder journey marker, or `checkout_lease` block |
-| `router_invoked` | a `- journey:` setting is present and not a placeholder |
+| `router_invoked` | a non-placeholder `- journey:` setting is present, including the Journey identity nested inside the `checkout_lease` block |
 | `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 |
+| closeout handoff fields | matching task-record keys when present. Receipt `verdict` is a closed role-return token; task `outcome` is approved intent and is not mapped into the receipt |
 
 `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.
 
+The Router writes the visible `checkout_lease` before any planning write or
+dispatch; its nested non-placeholder Journey identity is the Router-invoked
+signal during planning. The plan-level Explorer-versus-Expedition value is
+recorded later at the route review.
+
 ## Outcome translation
 
 | Outcome | Host JSON | Process exit |

package/hooks/com.cursor/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Bearing Lite Cursor mapping. Partial coverage: sessionStart activation, stop closeout. Transition-order and protected-action remain procedural.",
+  "description": "Bearing Lite Cursor mapping. Partial coverage: sessionStart activation, stop closeout, and write-time te_test_write on preToolUse and beforeShellExecution. Cursor exposes no hard completion or child-stop deny, so te_completion stays procedural. Transition-order and protected-action remain procedural.",
   "hooks": {
     "sessionStart": [
       {
@@ -10,6 +10,16 @@
       {
         "command": "node ./hooks/com.anthropic.claude-code/host.cjs"
       }
+    ],
+    "preToolUse": [
+      {
+        "command": "node ./hooks/te-host.cjs --host=cursor"
+      }
+    ],
+    "beforeShellExecution": [
+      {
+        "command": "node ./hooks/te-host.cjs --host=cursor"
+      }
     ]
   }
 }

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Bearing Lite verified Claude Code and Codex mapping. Partial coverage: activation on SessionStart, closeout on Stop. Transition-order and protected-action remain procedural.",
+  "description": "Bearing Lite verified Claude Code and Codex mapping. Partial coverage: activation on SessionStart, closeout on Stop, and the Test Engineering classes te_test_write on PreToolUse and te_completion on Stop and SubagentStop. Transition-order and protected-action remain procedural.",
   "hooks": {
     "SessionStart": [
       {
@@ -16,6 +16,22 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|apply_patch|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/hooks/te-host.cjs"
+            ],
+            "timeout": 15,
+            "statusMessage": "Bearing Lite test-engineering write check"
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "hooks": [
@@ -29,6 +45,34 @@
             "statusMessage": "Bearing Lite closeout"
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/hooks/te-host.cjs"
+            ],
+            "timeout": 15,
+            "statusMessage": "Bearing Lite test-engineering completion check"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/hooks/te-host.cjs"
+            ],
+            "timeout": 15,
+            "statusMessage": "Bearing Lite test-engineering child completion check"
+          }
+        ]
       }
     ]
   }

package/hooks/planning-review.cjs

@@ -0,0 +1,99 @@
+"use strict";
+
+const POLICY = Object.freeze({
+  reviewer_slots_min: 2,
+  reviewer_slots_max: 2,
+  independence_required: true,
+  isolated_findings_until_aggregation: true,
+  candidate_fields: ["candidate_ref", "candidate_revision", "candidate_digest"],
+  shared_candidate_required: true,
+  review_rounds: 1,
+  aggregated_repairs_max: 1,
+  post_repair_gate: "deterministic_PASS",
+  automatic_rereview: "prohibited",
+  slot_exhaustion_outcome: "FAIL_ROUND",
+  terminal_outcomes: ["HALT", "OWNER_AMENDMENT_REQUIRED"],
+});
+
+const sameCandidate = (a, b) =>
+  POLICY.candidate_fields.every(
+    (key) => typeof a?.[key] === "string" && a[key] && a[key] === b?.[key]
+  );
+
+function evaluatePlanningReview(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return { outcome: "NEEDS_MORE_EVIDENCE", reason: "planning_review_missing" };
+  }
+  const slots = Array.isArray(input.reviewer_slots) ? input.reviewer_slots : [];
+  const ids = slots.map((slot) => slot?.slot_id);
+  const primaryRoutes = slots.map((slot) => slot?.primary_route_ref);
+  if (
+    slots.length < POLICY.reviewer_slots_min ||
+    slots.length > POLICY.reviewer_slots_max ||
+    ids.some((id) => typeof id !== "string" || !id) ||
+    new Set(ids).size !== ids.length ||
+    new Set(primaryRoutes).size !== primaryRoutes.length ||
+    slots.some(
+      (slot) =>
+        typeof slot.primary_route_ref !== "string" ||
+        !slot.primary_route_ref ||
+        !Array.isArray(slot.fallback_route_refs)
+    )
+  ) {
+    return { outcome: "OWNER_AMENDMENT_REQUIRED", reason: "slot_binding_invalid" };
+  }
+  if (slots.some((slot) => slot.exhausted === true)) {
+    return { outcome: POLICY.slot_exhaustion_outcome, reason: "reviewer_slot_exhausted" };
+  }
+  if (input.round_number !== 1 || input.completed_rounds > POLICY.review_rounds) {
+    return { outcome: "HALT", reason: "review_round_limit" };
+  }
+  if (input.completed_rounds === 0) {
+    return { outcome: "NEEDS_MORE_EVIDENCE", reason: "review_round_pending" };
+  }
+  if (input.completed_rounds !== POLICY.review_rounds) {
+    return { outcome: "OWNER_AMENDMENT_REQUIRED", reason: "review_round_invalid" };
+  }
+  if (
+    POLICY.automatic_rereview === "prohibited" &&
+    (input.automatic_rereview_requested === true || input.review_after_repair === true)
+  ) {
+    return { outcome: "OWNER_AMENDMENT_REQUIRED", reason: "automatic_rereview_prohibited" };
+  }
+  const receipts = Array.isArray(input.receipts) ? input.receipts : [];
+  const receiptIds = receipts.map((receipt) => receipt?.slot_id);
+  const selectedRoutes = receipts.map((receipt) => receipt?.selected_route_ref);
+  if (
+    receipts.length !== slots.length ||
+    new Set(receiptIds).size !== receiptIds.length ||
+    new Set(selectedRoutes).size !== selectedRoutes.length ||
+    !input.candidate ||
+    receipts.some(
+      (receipt) => {
+        const slot = slots.find((item) => item.slot_id === receipt?.slot_id);
+        return (
+          !slot ||
+          ![slot.primary_route_ref, ...slot.fallback_route_refs].includes(receipt.selected_route_ref) ||
+          receipt.independent !== POLICY.independence_required ||
+          receipt.findings_isolated !== POLICY.isolated_findings_until_aggregation ||
+          !sameCandidate(receipt, input.candidate)
+        );
+      }
+    )
+  ) {
+    return { outcome: "HALT", reason: "candidate_or_independence_mismatch" };
+  }
+  if (input.aggregation_complete !== true) {
+    return { outcome: "NEEDS_MORE_EVIDENCE", reason: "aggregation_pending" };
+  }
+  const repairs = Number(input.aggregated_repairs || 0);
+  if (!Number.isInteger(repairs) || repairs < 0 || repairs > POLICY.aggregated_repairs_max) {
+    return { outcome: "HALT", reason: "aggregated_repair_limit" };
+  }
+  if (repairs === 1 && input.deterministic_gate !== POLICY.post_repair_gate.split("_")[1]) {
+    return { outcome: "HALT", reason: "deterministic_post_repair_gate_required" };
+  }
+  return { outcome: "PASS", reason: repairs ? "repair_gate_passed" : "review_aggregated" };
+}
+
+module.exports = { POLICY, evaluatePlanningReview };

package/hooks/te-capability.cjs

@@ -0,0 +1,137 @@
+"use strict";
+
+/**
+ * Test Engineering capability resolver (SEIT-EMV-017, SEIT-EMV-036).
+ *
+ * Bearing Lite ships no Test Engineering evaluator and no Test Engineering
+ * method content. This module only answers one question: is the
+ * `test-engineering` capability active for this workspace, and if so, is the
+ * real evaluator loadable at its capability path?
+ *
+ * Activation is `selected OR required`.
+ *   - neither      -> INACTIVE. Not a failure; the class simply does not run.
+ *   - active, gone -> TYPED_GAP. Never silent success, never invented policy.
+ *   - active, here -> ACTIVE, with the loaded evaluator module.
+ *
+ * `invented` is always `false`: this resolver never substitutes a local
+ * decision for the evaluator's.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const CAPABILITY = "test-engineering";
+const STATUSES = Object.freeze(["INACTIVE", "ACTIVE", "TYPED_GAP"]);
+/** Capability path, relative to the workspace root. */
+const EVALUATOR_RELATIVE_PATH = path.join(
+  "skills",
+  CAPABILITY,
+  "hooks",
+  "te-evaluator.cjs"
+);
+
+/**
+ * @param {unknown} workspaceRoot
+ * @returns {string}
+ */
+function evaluatorPath(workspaceRoot) {
+  const root =
+    typeof workspaceRoot === "string" && workspaceRoot.trim()
+      ? workspaceRoot.trim()
+      : process.cwd();
+  return path.resolve(root, EVALUATOR_RELATIVE_PATH);
+}
+
+/**
+ * Load the evaluator at the capability path. Absence, a load failure, or a
+ * module that does not implement the evaluator contract are all the same
+ * observable: the capability is unavailable.
+ * @param {unknown} workspaceRoot
+ * @returns {{ evaluateTestWrite: Function, evaluateCompletion: Function } | null}
+ */
+function loadEvaluator(workspaceRoot) {
+  const target = evaluatorPath(workspaceRoot);
+  let stat;
+  try {
+    stat = fs.statSync(target);
+  } catch {
+    return null;
+  }
+  if (!stat.isFile()) return null;
+  let mod;
+  try {
+    mod = require(target);
+  } catch {
+    return null;
+  }
+  if (
+    !mod ||
+    typeof mod.evaluateTestWrite !== "function" ||
+    typeof mod.evaluateCompletion !== "function"
+  ) {
+    return null;
+  }
+  return mod;
+}
+
+/**
+ * Resolve the `test-engineering` capability for one workspace.
+ * @param {{ workspaceRoot?: string, selected?: boolean, required?: boolean }} [input]
+ */
+function resolve(input) {
+  const opts = input !== null && typeof input === "object" ? input : {};
+  const selected = opts.selected === true;
+  const required = opts.required === true;
+  const base = {
+    capability: CAPABILITY,
+    selected,
+    required,
+    invented: false,
+  };
+
+  if (!selected && !required) {
+    return {
+      ...base,
+      active: false,
+      status: "INACTIVE",
+      evaluator: null,
+      code: "capability_inactive",
+      message:
+        `capability "${CAPABILITY}" is neither selected nor required; ` +
+        "the class does not run and this is not a failure",
+    };
+  }
+
+  const evaluator = loadEvaluator(opts.workspaceRoot);
+  if (!evaluator) {
+    return {
+      ...base,
+      active: true,
+      status: "TYPED_GAP",
+      evaluator: null,
+      code: "typed_capability_gap",
+      message:
+        `selected or required capability "${CAPABILITY}" is unavailable: ` +
+        `no loadable evaluator at ${EVALUATOR_RELATIVE_PATH}`,
+      recovery:
+        "install the test-engineering method capability in this workspace, " +
+        "or clear the selected/required activation for this task",
+    };
+  }
+
+  return {
+    ...base,
+    active: true,
+    status: "ACTIVE",
+    evaluator,
+  };
+}
+
+module.exports = {
+  CAPABILITY,
+  STATUSES,
+  EVALUATOR_RELATIVE_PATH,
+  evaluatorPath,
+  loadEvaluator,
+  resolve,
+};