@alphazede/bearing-lite 0.1.11 → 0.2.1

package/hooks/plan-package.cjs

@@ -0,0 +1,177 @@
+"use strict";
+
+/**
+ * Map the Route freeze (#70, #73, #77, #80): pure checks over a planning package.
+ * checkRoles: every command a slice runs whose seit procedure names an actor
+ * must name the slice's role. checkWorkClass validates light slices;
+ * checkPlanningRoles excludes planning-only roles from Expedition slices.
+ * verifyDigests: every planning input digest
+ * embedded in seit.json matches the file on disk; the manifest digest over
+ * those inputs plus seit.json matches implementation.json's
+ * planning_review.candidate_digest; missing artifacts, inputs, digests, or a
+ * specification Journey's SDoc register fail closed.
+ * CLI: node <plugin root>/hooks/plan-package.cjs <plan dir> -> JSON, exit 1 on any finding.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+const sha256 = (data) => crypto.createHash("sha256").update(data).digest("hex");
+
+/** Walk any object graph and yield slice-like nodes. */
+function* slices(node) {
+  if (Array.isArray(node)) {
+    for (const item of node) yield* slices(item);
+  } else if (node && typeof node === "object") {
+    const ids = [...(node.command_ids || []), ...(node.post_step_command_ids || [])];
+    if (typeof node.id === "string" && typeof node.role === "string") {
+      yield { id: node.id, role: node.role, commandIds: ids };
+    }
+    for (const value of Object.values(node)) yield* slices(value);
+  }
+}
+
+function checkRoles(seit, implementation) {
+  const procedures = new Map(
+    (seit?.procedures_and_commands || []).map((p) => [p.id, p])
+  );
+  const findings = [];
+  for (const slice of slices(implementation)) {
+    for (const command_id of slice.commandIds) {
+      const procedure = procedures.get(command_id);
+      if (!procedure) {
+        findings.push({ code: "unknown_command_id", step: slice.id, command_id });
+      } else if (typeof procedure.actor === "string" && procedure.actor !== slice.role) {
+        findings.push({
+          code: "actor_role_mismatch",
+          step: slice.id,
+          command_id,
+          seit_actor: procedure.actor,
+          implementation_role: slice.role,
+          files: ["seit.json", "implementation.json"],
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+/** #77: a light slice must run at least one command and be routed to the Light Implementer. */
+function checkWorkClass(node, findings = []) {
+  if (Array.isArray(node)) node.forEach((item) => checkWorkClass(item, findings));
+  else if (node && typeof node === "object") {
+    if (node.work_class === "light" && typeof node.id === "string") {
+      if (!(node.command_ids || []).length) findings.push({ code: "light_slice_without_command", step: node.id });
+      if (node.role !== "Light Implementer") findings.push({ code: "light_slice_role", step: node.id, role: node.role });
+    }
+    for (const value of Object.values(node)) checkWorkClass(value, findings);
+  }
+  return findings;
+}
+
+/** #80: Requirements Engineer is planning-only and never an Expedition slice. */
+function checkPlanningRoles(node, findings = []) {
+  if (Array.isArray(node)) node.forEach((item) => checkPlanningRoles(item, findings));
+  else if (node && typeof node === "object") {
+    if (typeof node.role === "string" && node.role.startsWith("Requirements Engineer")) {
+      findings.push({
+        code: "planning_role_in_expedition",
+        step: typeof node.id === "string" ? node.id : null,
+        role: node.role,
+      });
+    }
+    for (const value of Object.values(node)) checkPlanningRoles(value, findings);
+  }
+  return findings;
+}
+
+function repoRoot(dir) {
+  let current = path.resolve(dir);
+  for (;;) {
+    if (fs.existsSync(path.join(current, ".git"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(dir);
+    current = parent;
+  }
+}
+
+function readJson(file) {
+  return fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : null;
+}
+
+function verifyDigests(dir) {
+  const findings = [];
+  for (const name of ["seit.json", "implementation.json"]) {
+    if (!fs.existsSync(path.join(dir, name))) findings.push({ code: "missing_artifact", path: name });
+  }
+  if (findings.length) return { manifest_digest: null, findings };
+  const seit = readJson(path.join(dir, "seit.json"));
+  const implementation = readJson(path.join(dir, "implementation.json"));
+  const root = repoRoot(dir);
+  const inputs = seit?.source_baseline?.planning_inputs;
+  if (!Array.isArray(inputs) || !inputs.length) {
+    findings.push({ code: "missing_planning_inputs", path: "seit.json" });
+  }
+  const actual = [];
+  for (const input of inputs || []) {
+    if (typeof input?.path !== "string" || !/^[0-9a-f]{64}$/.test(input?.sha256 || "")) {
+      findings.push({ code: "malformed_planning_input", input });
+      continue;
+    }
+    const file = path.resolve(root, input.path);
+    if (!fs.existsSync(file)) {
+      findings.push({ code: "missing_input", path: input.path });
+      continue;
+    }
+    const digest = sha256(fs.readFileSync(file));
+    actual.push(digest);
+    if (digest !== input.sha256) {
+      findings.push({ code: "digest_mismatch", path: input.path, recorded: input.sha256, actual: digest });
+    }
+  }
+  // The manifest binds the planning inputs and seit.json itself (#70).
+  actual.push(sha256(fs.readFileSync(path.join(dir, "seit.json"))));
+  const manifest_digest = sha256(actual.join("\n"));
+  const recorded = implementation?.journey_settings?.planning_review?.candidate_digest;
+  if (typeof recorded !== "string" || !recorded) {
+    findings.push({ code: "missing_candidate_digest", actual: manifest_digest });
+  } else if (recorded !== manifest_digest) {
+    findings.push({ code: "candidate_digest_mismatch", recorded, actual: manifest_digest });
+  }
+  // #69: a specification Journey records an existing SDoc register at planning.
+  const settings = implementation?.journey_settings || {};
+  if (settings.journey_type === "specification") {
+    const register = settings.requirement_register;
+    if (typeof register !== "string" || !register.endsWith(".sdoc") || !fs.existsSync(path.resolve(root, register))) {
+      findings.push({ code: "missing_requirement_register", recorded: register ?? null });
+    }
+  }
+  return { manifest_digest, findings };
+}
+
+function freeze(dir) {
+  const digests = verifyDigests(dir);
+  const seit = readJson(path.join(dir, "seit.json"));
+  const implementation = readJson(path.join(dir, "implementation.json"));
+  const findings = [
+    ...checkRoles(seit, implementation),
+    ...checkWorkClass(implementation),
+    ...checkPlanningRoles(implementation),
+    ...digests.findings,
+  ];
+  return { outcome: findings.length ? "FAIL" : "PASS", manifest_digest: digests.manifest_digest, findings };
+}
+
+module.exports = { checkRoles, checkWorkClass, checkPlanningRoles, verifyDigests, freeze };
+
+if (require.main === module) {
+  const dir = process.argv[2];
+  if (!dir) {
+    process.stderr.write("usage: node hooks/plan-package.cjs <plan dir>\n");
+    process.exit(2);
+  }
+  const result = freeze(dir);
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  process.exit(result.outcome === "PASS" ? 0 : 1);
+}

package/hooks/planning-review.cjs

@@ -1,19 +1,6 @@
 "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 { PLANNING_REVIEW_POLICY: POLICY } = require("./policy.cjs");
 
 const sameCandidate = (a, b) =>
   POLICY.candidate_fields.every(
@@ -24,6 +11,14 @@ function evaluatePlanningReview(input) {
   if (!input || typeof input !== "object" || Array.isArray(input)) {
     return { outcome: "NEEDS_MORE_EVIDENCE", reason: "planning_review_missing" };
   }
+  // #69: a specification Journey gates its requirement register at planning;
+  // existence on disk is checked by hooks/plan-package.cjs at the freeze.
+  if (
+    input.journey_type === "specification" &&
+    !(typeof input.requirement_register === "string" && input.requirement_register.endsWith(".sdoc"))
+  ) {
+    return { outcome: "NEEDS_MORE_EVIDENCE", reason: "missing_requirement_register" };
+  }
   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);

package/hooks/policy.cjs

@@ -0,0 +1,45 @@
+"use strict";
+
+/**
+ * Single policy source for the planning-review and assurance-budget
+ * evaluators (#63). The JSON blocks in
+ * skills/bearing-lite/references/review-policy.md and assurance-policy.md
+ * must equal these objects; test/policy-drift.test.mjs enforces it.
+ */
+
+const PLANNING_REVIEW_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 ASSURANCE_BUDGET_POLICY = Object.freeze({
+  budget_scope: "per_declared_phase_or_wave",
+  review_rounds: 1,
+  aggregated_repairs_max: 1,
+  post_repair_gate: "deterministic_PASS",
+  automatic_phase_or_wave_end_review: "required",
+  automatic_per_slice_review: "prohibited",
+  post_repair_rereview: "prohibited",
+  automatic_rereview_of_same_unit: "prohibited",
+  budget_reset_on_candidate_change: false,
+  budget_reset_on_model_change: false,
+  budget_reset_on_harness_change: false,
+  budget_reset_on_role_change: false,
+  budget_reset_on_session_change: false,
+  budget_reset_on_resume: false,
+  budget_reset_on_alias_or_rename: false,
+  budget_reset_condition:
+    "next_distinct_declared_phase_or_wave_present_in_the_frozen_declaration",
+});
+
+module.exports = { PLANNING_REVIEW_POLICY, ASSURANCE_BUDGET_POLICY };

package/hooks/reconcile.cjs

@@ -0,0 +1,145 @@
+"use strict";
+
+/** Deterministically apply evidence events to Journey state (#64). */
+const fs = require("node:fs");
+
+const REQUIRED = [
+  "schema_version", "event_id", "source", "journey", "repository", "unit",
+  "candidate_revision", "generation", "evidence", "transition", "occurred_at",
+];
+const KINDS = new Set(["implementation", "verification", "assurance", "acceptance", "merge", "issue_close"]);
+const FIELDS = {
+  implementation: "implementation",
+  verification: "verification",
+  assurance: "assurance",
+  acceptance: "acceptance",
+  merge: "observed_merge",
+  issue_close: "observed_issue_close",
+};
+const PREDECESSORS = { verification: "implementation", assurance: "verification", acceptance: "assurance" };
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const nonempty = (value) => typeof value === "string" && value.length > 0;
+const only = (value, names) => Object.keys(value).every((name) => names.includes(name));
+const dateTime = (value) => nonempty(value) && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) && !Number.isNaN(Date.parse(value));
+
+function receiptFor(event) {
+  return {
+    event_id: event?.event_id ?? null,
+    applied: false,
+    code: "invalid_event",
+    transition: event?.transition?.kind ?? null,
+    slice: event?.unit?.slice ?? null,
+    candidate_revision: event?.candidate_revision ?? null,
+    evidence_sha256: event?.evidence?.sha256 ?? null,
+  };
+}
+
+function structuralError(event) {
+  if (!object(event) || !REQUIRED.every((name) => Object.hasOwn(event, name)) || !only(event, REQUIRED)) return true;
+  if (event.schema_version !== 1 || !nonempty(event.event_id) || !nonempty(event.source) ||
+      !nonempty(event.journey) || !nonempty(event.repository) || !nonempty(event.candidate_revision) ||
+      !Number.isInteger(event.generation) || event.generation < 0 || !dateTime(event.occurred_at)) return true;
+  if (!object(event.unit) || !only(event.unit, ["wave", "slice"]) || !nonempty(event.unit.slice) ||
+      (Object.hasOwn(event.unit, "wave") && !nonempty(event.unit.wave))) return true;
+  if (!object(event.evidence) || !only(event.evidence, ["ref", "sha256"])) return true;
+  if (!object(event.transition) || !only(event.transition, ["kind", "verdict"]) ||
+      !KINDS.has(event.transition.kind) || !nonempty(event.transition.verdict)) return true;
+  return false;
+}
+
+function reject(state, receipt, code) {
+  return { state, receipt: { ...receipt, code, reason: code } };
+}
+
+function applyEvent(state, event, options = {}) {
+  const receipt = receiptFor(event);
+  if (structuralError(event)) return reject(state, receipt, "invalid_event");
+  if (options.expected_version !== undefined && options.expected_version !== state.version) {
+    return reject(state, receipt, "stale_write");
+  }
+  if (state.applied_event_ids.includes(event.event_id)) return reject(state, receipt, "duplicate_event");
+  if (event.journey !== state.journey || event.repository !== state.repository) {
+    return reject(state, receipt, "unrelated_journey");
+  }
+  if (event.generation < state.generation) return reject(state, receipt, "stale_generation");
+
+  const hasEvidence = nonempty(event.evidence.ref) && nonempty(event.evidence.sha256);
+  if (!hasEvidence && event.transition.verdict === "PASS") return reject(state, receipt, "bare_pass");
+  if (!hasEvidence) return reject(state, receipt, "missing_evidence");
+  if (!/^[0-9a-f]{64}$/.test(event.evidence.sha256)) return reject(state, receipt, "invalid_event");
+
+  const kind = event.transition.kind;
+  const slice = state.slices[event.unit.slice] || {};
+  const field = FIELDS[kind];
+  const prior = slice[field];
+  const history = prior ? {
+    ...prior.history,
+    [prior.candidate_revision]: { verdict: prior.verdict, sha256: prior.evidence.sha256 },
+  } : {};
+  const h = Object.hasOwn(history, event.candidate_revision) ? history[event.candidate_revision] : undefined;
+  if (h && (h.verdict !== event.transition.verdict || h.sha256 !== event.evidence.sha256)) {
+    return reject(state, receipt, "conflicting_receipt");
+  }
+  if (h) {
+    return reject(state, receipt, event.candidate_revision === prior.candidate_revision ? "duplicate_event" : "stale_candidate");
+  }
+
+  const implementation = slice.implementation;
+  if (["verification", "assurance", "acceptance"].includes(kind) &&
+      implementation?.candidate_revision !== event.candidate_revision) {
+    return reject(state, receipt, implementation ? "stale_candidate" : "predecessor_missing");
+  }
+  const predecessor = PREDECESSORS[kind];
+  if (predecessor && slice[predecessor]?.candidate_revision !== event.candidate_revision) {
+    return reject(state, receipt, "predecessor_missing");
+  }
+
+  const entry = {
+    candidate_revision: event.candidate_revision,
+    verdict: event.transition.verdict,
+    evidence: { ...event.evidence },
+    event_id: event.event_id,
+    history: { ...history, [event.candidate_revision]: { verdict: event.transition.verdict, sha256: event.evidence.sha256 } },
+  };
+  const next = {
+    ...state,
+    generation: Math.max(state.generation, event.generation),
+    version: state.version + 1,
+    applied_event_ids: [...state.applied_event_ids, event.event_id],
+    slices: { ...state.slices, [event.unit.slice]: { ...slice, [field]: entry } },
+  };
+  return { state: next, receipt: { ...receipt, applied: true, code: "applied" } };
+}
+
+function replay(state, events) {
+  const receipts = [];
+  let current = state;
+  for (const event of events) {
+    const result = applyEvent(current, event);
+    current = result.state;
+    receipts.push(result.receipt);
+  }
+  return { state: current, receipts };
+}
+
+function main(args = process.argv.slice(2)) {
+  const [stateFile, eventsFile] = args;
+  try {
+    if (!stateFile || !eventsFile) throw new Error("usage: node hooks/reconcile.cjs <state.json> <events.ndjson>");
+    const state = JSON.parse(fs.readFileSync(stateFile, "utf8"));
+    const events = fs.readFileSync(eventsFile, "utf8").split(/\r?\n/).filter(Boolean).map(JSON.parse);
+    const result = replay(state, events);
+    const temporary = `${stateFile}.tmp-${process.pid}`;
+    fs.writeFileSync(temporary, JSON.stringify(result.state, null, 2) + "\n");
+    fs.renameSync(temporary, stateFile);
+    for (const receipt of result.receipts) process.stdout.write(JSON.stringify(receipt) + "\n");
+    return 0;
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return 1;
+  }
+}
+
+module.exports = { applyEvent, replay };
+
+if (require.main === module) process.exitCode = main();

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,
+};