@alphazede/bearing-lite 0.1.11 → 0.2.1

package/CONTRIBUTING.md

@@ -54,8 +54,33 @@ checkout):
 node --test test/diagram-sync.test.mjs
 node --test test/public-boundary.test.mjs
 node --test test/skills-conformance.test.mjs
+python3 test/schema-validation.py
 ```
 
+Schema validation requires Python 3.12. `python3 test/schema-validation.py` is
+the required developer and CI gate (`CMD-LITE-SCHEMA-VALIDATE`). It installs the
+pinned hashes from `test/schema-validator-requirements.txt` into an isolated
+temporary directory with `pip install --isolated --require-hashes --no-deps` and
+runs Draft 2020-12 validation with no remote `$ref` retrieval. Do not install
+those packages globally, with `--user`, or as production dependencies of this
+package.
+
+CI on `ubuntu-24.04` with Python 3.12 x64 performs the same isolated
+`--require-hashes --no-deps` install into a job-local target directory, then
+runs `python3 test/schema-validation.py`. To reuse a local isolated tree instead
+of a temporary install:
+
+```sh
+python3.12 -m venv .venv-schema-validator
+.venv-schema-validator/bin/python -m pip install \
+  --isolated --require-hashes --no-deps \
+  -r test/schema-validator-requirements.txt
+BEARING_LITE_SCHEMA_ISOLATED_ROOT=.venv-schema-validator/lib/python3.12/site-packages \
+  python3 test/schema-validation.py
+```
+
+Keep that virtualenv uncommitted.
+
 Keep skills lean. Prefer references and assets only when progressive disclosure
 needs them. Do not add dependencies or change the lockfile without explicit
 maintainer approval. Do not add `mcp.json`, postinstall scripts, or global hook

package/README.md

@@ -30,9 +30,12 @@ Then give your agent a real task:
 > responses. Require one independent review at the end.
 
 Bearing Lite fills missing planning stages, then Map the Route creates the
-complete five-artifact package with proposed route, lineup, role states,
-reasoning, and at-end cadence. One integrated owner review approves or changes
-that package before bounded sessions dispatch with visible Markdown state.
+complete five-artifact package (`<journey-topic>-technical-plan.md`,
+`design.md`, `seit.json`, `implementation.json`, and two-state `review.html`)
+with proposed route, lineup, role states, reasoning, and at-end cadence. One
+integrated owner review approves or changes that package before bounded
+sessions dispatch, with visible Markdown task state over those JSON
+authorities.
 
 If Bearing Lite helps keep a long agent task scoped and reviewable,
 [star the repository](https://github.com/alphazede/bearing-lite). It helps other
@@ -97,16 +100,25 @@ register hooks. That path remains first-class. See
 1. **Fill only missing planning stages:** Repository Fit → Set Bearings → Gather
    Supplies.
 2. **Invoke Map the Route** after material intent is settled. It creates
-   specification, design, SEIT, implementation, and `review.html` together.
+   technical-plan, `design.md`, `seit.json`, `implementation.json`, and
+   two-state `review.html` together.
 3. **Review once:** approve or change the proposed route, user-owned
    primary/fallback lineup, role states, reasoning, at-end cadence, and plan.
 4. **Dispatch bounded sessions** with compact receipts. Crewmate and Explorer may
    continue in-wave; assurance always starts fresh at the end.
-5. **Record state visibly** in human-readable Markdown artifacts only.
+5. **Record state visibly.** The project's human-readable Markdown plan is the
+   only task-state record: task blocks, task states, and their transitions. The
+   Journey, execution, V&V, and authority records are machine-readable JSON
+   validated against `schemas/`: `journey.json` (Journey identity, checkout
+   lease, decisions, planning receipts, lineup selection), `seit.json` (V&V
+   proof rows), `implementation.json` (nested execution authority, waves,
+   slices, dispatch), and `authority.json` (authority envelope). `review.html`
+   and diagrams present state; like diagrams, they never authorize a
+   transition, create state, or grant authority.
 
 Bearing Lite never selects models, providers, credentials, or launchers. The
 owner provides each role's primary/fallback agent or harness, model, and
-reasoning level in `~/.agents/bearing-lite/default-role-lineup.md`, then confirms
+reasoning level in `~/.agents/bearing-lite/lineups.json`, then confirms
 the applicable Journey snapshot before implementation.
 
 ## Routes and scaling
@@ -133,8 +145,8 @@ invokes only missing planning stages, has Map the Route generate all five
 artifacts with proposed lineup and `review_cadence: at-end`, then presents one
 integrated owner review before dispatching 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 only at the
-end on the final integrated candidate. Diagrams
+Assurance Test Engineer, Park Ranger, and Surveyor appear only when declared
+and only at the end on the final integrated candidate. Diagrams
 explain orientation; they never authorize a transition.
 
 ## Roles and authority
@@ -144,14 +156,27 @@ explain orientation; they never authorize a transition.
 | **Router** | Stateful planning controller | no | User-facing; planning-state writer; Expedition sequencing |
 | **Navigator** | Compatibility diagnostic | no | Not a normal role; existing plans reroute to Router |
 | **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 |
+| **Crewmate** | Bounded implementer | yes | Split test-writing versus product; neither self-certifies |
+| **Light Implementer** | Mechanical implementer | yes | `work_class: light` slices only; verified by the packet's command; no repair loop |
+| **Scribe** | Event side lane | no | Transcribes; cannot activate authority |
+| **Plan Integrator** | Artifact reconciliation | no | Generates `implementation.json` and `review.html` |
+| **Systems Modeler** | Engineering views | no | After requirements; before design finalization |
+| **Integration Engineer** | Progressive assembly | no | Dual planning and execution sessions |
+| **Test Engineer** | Planning and Assurance V&V | no | Retires Validator; Validator is not an active role |
+| **Park Ranger** | Defect review | no | Consumes Assurance Test Engineer; no routine TE |
+| **Surveyor** | User-facing acceptance | no | Read-only RE, SysML Modeling, and TE |
 | **Owner Authority** | Human decision | n/a | Never an agent role |
 
-**Independent review:** a candidate author never provides their own Validator,
-Park Ranger, or Surveyor verdict.
+**Independent review:** a candidate author never provides their own Assurance
+Test Engineer, Park Ranger, or Surveyor verdict.
+
+Public Bearing Lite remains usable without AlphaZede-specific skills
+(`requirements-engineering`, `sysml-modeling`, `test-engineering`,
+`integration-engineering`). Specialized capabilities activate when selected
+or required. Unavailability of a selected-or-required capability is a typed capability gap,
+not success and not invented behavior. Selected-only missing and required-only
+missing are each typed gaps. Only unselected and unrequired absence remains
+inactive / not a global failure.
 
 Failure escalates to the nearest role whose scope can see it:
 
@@ -177,6 +202,11 @@ Ordinary execution corrections remain bounded. The assurance gate allows one
 review-directed repair, followed by deterministic coordinator verification and
 no second review. Diagrams never create state or authorize transitions.
 
+`hooks/reconcile.cjs` deterministically applies evidence events to Journey state.
+It is a short-lived Router-run invocation, not a daemon or host event adapter;
+hosts emit no events today, so invocation remains a procedural limitation.
+It observes merge and issue closure but never grants acceptance, merges, or closes issues.
+
 ## Implementation process (explanatory)
 
 Default packet completion is author self-check plus coordinator confirmation.
@@ -204,6 +234,8 @@ flowchart LR
 | `plugin.json` | Agent Plugins v1.0.0 manifest |
 | `skills/` | Router, planning stages, and role skills |
 | `hooks/` | Four portable class adapters plus the verified Claude Code / Codex mapping |
+| `lineups.json` | Empty shipped catalog; no packaged providers, models, or defaults |
+| `schemas/` | JSON Schema for `seit.json`, `implementation.json`, `authority.json`, and `journey.json` |
 | `README.md` and governance docs | Public product and conduct surfaces |
 
 There is no `mcp.json`, `bin` entrypoint, postinstall, or runtime dependency on

package/hooks/assurance-budget.cjs

@@ -0,0 +1,149 @@
+"use strict";
+
+/**
+ * Per-declared-phase-or-wave assurance budget (ROUTER-EMV-CADENCE-IMPLEMENTATION-001).
+ * Exact runtime mirror of `skills/bearing-lite/references/assurance-policy.md`.
+ * A pure evaluator behind the existing `transition` class, like planning-review.cjs:
+ * it declares no HOOK_CLASS and registers no host event.
+ */
+
+const fs = require("node:fs");
+
+const { ASSURANCE_BUDGET_POLICY: POLICY } = require("./policy.cjs");
+
+/** The sentinel unit when the frozen declaration names neither waves nor phases. */
+const DIRECT = "direct";
+const PENDING_RECEIPTS = new Set(["WAITING_ON", "UNAVAILABLE"]);
+
+const isCount = (value) => Number.isInteger(value) && value >= 0;
+
+const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+function readJson(file) {
+  if (typeof file !== "string" || !file) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Declared unit ids from the frozen declaration, in declaration order. */
+function declaredUnits(declaration) {
+  const waves = Array.isArray(declaration.waves) ? declaration.waves : [];
+  const waveIds = waves.map((wave) => wave && wave.id).filter((id) => typeof id === "string" && id);
+  if (waveIds.length) return waveIds;
+  const phases = Array.isArray(declaration.phases) ? declaration.phases : [];
+  const phaseIds = phases
+    .map((phase) => phase && phase.phaseId)
+    .filter((id) => typeof id === "string" && id);
+  if (phaseIds.length) return phaseIds;
+  return [DIRECT];
+}
+
+const verdict = (outcome, reason) => ({ outcome, reason });
+
+/**
+ * @param {unknown} input assurance request
+ * @returns {{ outcome: string, reason: string }}
+ */
+function evaluateAssuranceBudget(input) {
+  try {
+    if (!isPlainObject(input)) {
+      return verdict("NEEDS_MORE_EVIDENCE", "assurance_request_missing");
+    }
+    if (
+      POLICY.automatic_per_slice_review === "prohibited" &&
+      (input.request_scope === "slice" || input.unit_kind === "slice")
+    ) {
+      return verdict("OWNER_AMENDMENT_REQUIRED", "automatic_per_slice_review_prohibited");
+    }
+    if (
+      POLICY.automatic_rereview_of_same_unit === "prohibited" &&
+      (input.automatic_rereview_requested === true || input.review_after_repair === true)
+    ) {
+      return verdict("OWNER_AMENDMENT_REQUIRED", "automatic_rereview_prohibited");
+    }
+
+    const declaration = readJson(input.declaration_path);
+    if (!declaration) {
+      return verdict("NEEDS_MORE_EVIDENCE", "frozen_declaration_unreadable");
+    }
+    const record = readJson(input.task_record_path);
+    if (!record) {
+      return verdict("NEEDS_MORE_EVIDENCE", "task_record_unreadable");
+    }
+    // The budget key is `journey + unit_kind + unit_id`; a record from another
+    // Journey never answers for this one.
+    if (
+      typeof record.journey === "string" &&
+      typeof input.journey === "string" &&
+      record.journey !== input.journey
+    ) {
+      return verdict("NEEDS_MORE_EVIDENCE", "task_record_journey_mismatch");
+    }
+
+    const declared = declaredUnits(declaration);
+    const requested =
+      typeof input.assurance_unit === "string" && input.assurance_unit
+        ? input.assurance_unit
+        : declared.length === 1 && declared[0] === DIRECT
+          ? DIRECT
+          : "";
+    if (!requested || !declared.includes(requested)) {
+      return verdict("OWNER_AMENDMENT_REQUIRED", "undeclared_review_unit");
+    }
+
+    const receipts = Array.isArray(input.receipts) ? input.receipts : [];
+    if (receipts.some((receipt) => PENDING_RECEIPTS.has(receipt && receipt.verdict))) {
+      return verdict("NEEDS_MORE_EVIDENCE", "assurance_transport_pending");
+    }
+
+    const units = Array.isArray(record.units) ? record.units : [];
+    const spent = units.find((unit) => {
+      if (!isPlainObject(unit)) return false;
+      const unitId = unit.unit_id || unit.assurance_unit;
+      const id = typeof unitId === "string" && unitId ? unitId : DIRECT;
+      if (id !== requested) return false;
+      if (typeof unit.journey === "string" && unit.journey !== input.journey) return false;
+      if (
+        typeof unit.unit_kind === "string" &&
+        typeof input.unit_kind === "string" &&
+        unit.unit_kind !== input.unit_kind
+      ) {
+        return false;
+      }
+      return true;
+    });
+    const counter = (field) => {
+      const value = spent && spent[field];
+      return value === undefined || value === null ? 0 : value;
+    };
+    const rounds = counter("assurance_rounds");
+    const repairs = counter("assurance_repairs");
+    // A corrupt counter is not a spent-zero budget.
+    if (!isCount(rounds) || !isCount(repairs)) {
+      return verdict("NEEDS_MORE_EVIDENCE", "invalid_assurance_counter");
+    }
+
+    if (repairs > POLICY.aggregated_repairs_max) {
+      return verdict("HALT", "assurance_repair_limit");
+    }
+    if (
+      repairs === POLICY.aggregated_repairs_max &&
+      (spent && spent.deterministic_gate) !== POLICY.post_repair_gate.split("_")[1]
+    ) {
+      return verdict("HALT", "deterministic_post_repair_gate_required");
+    }
+    if (rounds >= POLICY.review_rounds) {
+      return verdict("HALT", "assurance_round_limit");
+    }
+    return verdict("PASS", "assurance_round_available");
+  } catch {
+    return verdict("NEEDS_MORE_EVIDENCE", "assurance_budget_unavailable");
+  }
+}
+
+module.exports = { POLICY, evaluateAssuranceBudget };

package/hooks/closeout.cjs

@@ -39,6 +39,19 @@ const VERDICT_VALUES = new Set([
   "WAITING_ON",
 ]);
 
+/** Closed verdicts that refuse protected completion (#55). */
+const NEGATIVE_VERDICTS = new Set([
+  "BLOCK",
+  "FAIL",
+  "GAPS",
+  "NEEDS_MORE_EVIDENCE",
+  "OWNER_DECISION_REQUIRED",
+  "PARTIAL",
+  "REPAIR_REQUIRED",
+  "REROUTED",
+  "WAITING_ON",
+]);
+
 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 =
@@ -169,6 +182,8 @@ function evaluate(input) {
       const blockers = [];
       const handoffProblems = [...missing, ...invalid];
       if (handoffProblems.length > 0) blockers.push("handoff:" + handoffProblems.join(","));
+      const verdict = String((isPlainObject(input.handoff) ? input.handoff : input).verdict ?? "").trim();
+      if (NEGATIVE_VERDICTS.has(verdict)) blockers.push("verdict:" + verdict);
       if (missingAssurance.length > 0) {
         blockers.push("assurance:" + missingAssurance.join(","));
       }
@@ -283,6 +298,7 @@ module.exports = {
   ENFORCEMENT,
   HANDOFF_FIELDS,
   VERDICT_VALUES,
+  NEGATIVE_VERDICTS,
   evaluate,
 };
 

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

@@ -31,8 +31,15 @@ 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,
@@ -41,9 +48,74 @@ 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

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"
+          }
+        ]
       }
     ]
   }