halfcycle 0.3.17 → 0.3.18

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcycle",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "description": "Halfcycle Method bundle — resolution-stub slash commands, remote method-delivery registration, and governance-hook wiring for a Halfcycle engagement repo. It ships NO worker role files: a project's roles are authored from that project's own recorded decisions at orchestration kickoff (FX-2, W3-F-27).",
   "commands": [
     {

package/bin/bin.bundle.mjs

@@ -14594,6 +14594,80 @@ function date4(params) {
 // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 config(en_default());
 
+// ../events/dist/evaluation.js
+var envRefSchema = external_exports.object({
+  name: external_exports.string(),
+  argType: external_exports.enum(["build", "runtime", "both"])
+}).strict();
+var sqlWriteSchema = external_exports.object({
+  kind: external_exports.enum(["insert", "update", "upsert", "delete"]),
+  table: external_exports.string(),
+  whereColumns: external_exports.array(external_exports.string())
+}).strict();
+var schemaConstraintSchema = external_exports.object({
+  table: external_exports.string(),
+  kind: external_exports.enum(["unique", "check", "foreignKey"]),
+  constraintName: external_exports.string().optional()
+}).strict();
+var numericColumnSchema = external_exports.object({
+  table: external_exports.string(),
+  column: external_exports.string(),
+  pgType: external_exports.enum(["numeric", "bigint", "decimal"]),
+  wireField: external_exports.string().optional(),
+  hasRegisteredCoercion: external_exports.boolean().optional()
+}).strict();
+var thirdPartyEndpointSchema = external_exports.object({
+  signature: external_exports.string(),
+  provider: external_exports.string().optional(),
+  hasCapturedFixture: external_exports.boolean()
+}).strict();
+var sourceExcerptSchema = external_exports.object({
+  /** The declared construct the excerpt was cut around (a derived-fact anchor). */
+  construct: external_exports.enum(["sqlWrite", "thirdPartyEndpoint", "envRef"]),
+  /** 1-based start line in the changed file (best-effort). */
+  startLine: external_exports.number().int().nonnegative(),
+  /** The bounded excerpt text — capped CLIENT-SIDE in the runner before send. */
+  text: external_exports.string()
+}).strict();
+var diffMetadataSchema = external_exports.object({
+  path: external_exports.string(),
+  astShapes: external_exports.array(external_exports.string()),
+  envRefs: external_exports.array(envRefSchema),
+  sqlWrites: external_exports.array(sqlWriteSchema),
+  endpointSigs: external_exports.array(external_exports.string()),
+  schemaConstraints: external_exports.array(schemaConstraintSchema),
+  numericColumns: external_exports.array(numericColumnSchema),
+  thirdPartyEndpoints: external_exports.array(thirdPartyEndpointSchema),
+  // Present only when you have turned source excerpts on. Left out
+  // entirely otherwise — never sent as an empty list.
+  sourceExcerpts: external_exports.array(sourceExcerptSchema).optional()
+}).strict();
+var changeSetSchema = external_exports.object({
+  files: external_exports.array(diffMetadataSchema)
+}).strict();
+var NON_CAPABILITY_DESCRIPTOR_FIELDS = [
+  "path",
+  "sourceExcerpts"
+];
+var CLIENT_CAPABILITY_VOCABULARY = Object.keys(diffMetadataSchema.shape).filter((field) => !NON_CAPABILITY_DESCRIPTOR_FIELDS.includes(field));
+function isClientCapability(value) {
+  return CLIENT_CAPABILITY_VOCABULARY.includes(value);
+}
+var evaluationRequestSchema = external_exports.object({
+  engagementId: external_exports.string(),
+  changeSet: changeSetSchema,
+  /**
+   * What this client can supply: the names of the descriptor kinds it fills in
+   * for each changed file. A check that needs a kind this client does not send
+   * is reported by name as not run, with the missing kind named, instead of
+   * quietly reporting nothing.
+   *
+   * Omitting the field means "unknown", never "everything" — a client that
+   * says nothing is treated as an older one, not a capable one.
+   */
+  clientCapabilities: external_exports.array(external_exports.string()).optional()
+}).strict();
+
 // ../core/dist/guard-record.js
 var severitySchema = external_exports.enum(["info", "warn", "block"]);
 var channelSchema = external_exports.enum(["stable", "candidate", "rented"]);
@@ -14641,11 +14715,26 @@ var firedGuardSchema = external_exports.object({
    */
   path: external_exports.string().optional()
 }).strict();
+var notRunCheckSchema = external_exports.object({
+  /** Which check did not run, by the same reference a fired check carries. */
+  patternRef: external_exports.string(),
+  /**
+   * Why it could not run, in plain words — what this client did not send, or
+   * that the check's kind is not implemented yet. Never the check's own rule.
+   */
+  reason: external_exports.string()
+}).strict();
 var resultEnvelopeSchema = external_exports.object({
   guardsFired: external_exports.array(firedGuardSchema),
   severity: severitySchema.nullable(),
   blocking: external_exports.boolean(),
-  explanation: external_exports.string()
+  explanation: external_exports.string(),
+  /**
+   * The checks that could not run on this edit, each named with the reason.
+   * Absent when every check ran — so an evaluation where nothing was skipped
+   * looks exactly as it always has, and an absent list is never an empty one.
+   */
+  notRun: external_exports.array(notRunCheckSchema).optional()
 }).strict();
 var wireErrorSchema = external_exports.object({
   statusCode: external_exports.number(),
@@ -14653,6 +14742,60 @@ var wireErrorSchema = external_exports.object({
   message: external_exports.string()
 }).strict();
 
+// ../events/dist/phase-identity.js
+var PHASE_SEGMENT_PREFIX = "phase-";
+function isValidPhaseIdentity(identity) {
+  if (typeof identity === "number")
+    return Number.isInteger(identity) && identity >= 0;
+  if (typeof identity !== "string")
+    return false;
+  if (identity === "")
+    return false;
+  if (identity.includes("/"))
+    return false;
+  if (identity.includes("\\"))
+    return false;
+  if (identity.includes("\0"))
+    return false;
+  if (identity.startsWith("."))
+    return false;
+  return true;
+}
+var InvalidPhaseIdentityError = class extends Error {
+  /** The value that was refused, exactly as supplied. */
+  identity;
+  constructor(identity, allowedLocation) {
+    const subject = allowedLocation === void 0 ? "a file" : "a Build Record";
+    const where = allowedLocation === void 0 ? "" : `
+  Records are written only into ${allowedLocation.replace(/\\/g, "/")}/. Nothing was written.`;
+    super(`that phase identity cannot name ${subject}.
+  identity: ${describeIdentity(identity)}` + where);
+    this.name = "InvalidPhaseIdentityError";
+    this.identity = identity;
+  }
+};
+function renderPhaseSegment(identity) {
+  if (!isValidPhaseIdentity(identity)) {
+    throw new InvalidPhaseIdentityError(identity);
+  }
+  return `${PHASE_SEGMENT_PREFIX}${identity}`;
+}
+function describeIdentity(identity) {
+  if (typeof identity === "string")
+    return identity;
+  if (identity === null)
+    return "null";
+  if (identity === void 0)
+    return "none supplied";
+  if (typeof identity === "number" || typeof identity === "boolean")
+    return String(identity);
+  if (Array.isArray(identity))
+    return "(a list)";
+  if (typeof identity === "object")
+    return "(an object)";
+  return `(a ${typeof identity})`;
+}
+
 // dist/client.js
 var REQUEST_TIMEOUT_MS = 1e4;
 async function evaluate(url2, token, request, fetchFn = globalThis.fetch) {
@@ -15780,6 +15923,16 @@ function buildChangeSet(files, context = {}) {
   });
   return { files: fileMetadata };
 }
+function deriveClientCapabilities(changeSet) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const file2 of changeSet.files) {
+    for (const key of Object.keys(file2)) {
+      if (isClientCapability(key))
+        seen.add(key);
+    }
+  }
+  return [...seen];
+}
 function produceExcerpts(diffContent, descriptors, caps) {
   const excerpts = [];
   const seen = /* @__PURE__ */ new Set();
@@ -15911,26 +16064,22 @@ async function emitTelemetry(run, config2, logger, fetchFn = globalThis.fetch) {
     await postTelemetry(run, config2.controlTelemetryUrl, config2.controlTelemetryToken, logger, fetchFn);
   }
 }
-function normalizePhaseBaseName(phase) {
-  if (phase === void 0)
-    return null;
-  const trimmed = phase.trim();
-  if (trimmed === "")
-    return null;
-  const match = /^(?:phase-)?(\d+)$/.exec(trimmed);
-  if (!match)
-    return null;
-  return `phase-${match[1]}`;
-}
 function localLogPath(run, config2) {
   const logDir = config2.guardEvalLogDir ?? join4(homedir(), ".halfcycle", "guard-eval-log");
-  const base = normalizePhaseBaseName(run.phase);
-  const fileName = base !== null ? `${base}.jsonl` : "unphased.jsonl";
+  const phase = run.phase;
+  const fileName = phase === void 0 || phase === "" ? "unphased.jsonl" : `${renderPhaseSegment(phase)}.jsonl`;
   return join4(logDir, fileName);
 }
 function appendToLocalLog(run, config2, logger) {
+  let logPath;
+  try {
+    logPath = localLogPath(run, config2);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.warn(`[Halfcycle telemetry] Phase name refused, nothing written (dropped): ${msg}`);
+    return;
+  }
   try {
-    const logPath = localLogPath(run, config2);
     mkdirSync2(dirname2(logPath), { recursive: true });
     appendFileSync(logPath, JSON.stringify(run) + "\n", "utf-8");
   } catch (err) {
@@ -16104,6 +16253,14 @@ function emitCredentialRejected(statusCode, serviceMessage, exitCode) {
   writeSync(2, credentialRejectedMessage(statusCode, serviceMessage, HOOK_REMEDY));
   process.exitCode = exitCode;
 }
+function notRunReport(notRun, label = "[Halfcycle]") {
+  if (!notRun || notRun.length === 0)
+    return "";
+  const count = notRun.length;
+  const noun = count === 1 ? "check" : "checks";
+  const lines = notRun.map((entry) => `  [NOT RUN] ${entry.patternRef}: ${entry.reason}`);
+  return [`${label} ${count} ${noun} did not run on this change:`, ...lines].join("\n");
+}
 
 // dist/ci.js
 async function runCi() {
@@ -16154,7 +16311,8 @@ async function runCi() {
   const { guardServiceUrl, guardServiceToken, guardEngagementId } = configResult.config;
   const clientResult = await evaluate(guardServiceUrl, guardServiceToken, {
     engagementId: guardEngagementId,
-    changeSet
+    changeSet,
+    clientCapabilities: deriveClientCapabilities(changeSet)
   });
   if (!clientResult.ok) {
     const failure = classifyFailure(clientResult);
@@ -16183,9 +16341,9 @@ async function runCi() {
   const run = buildGuardEvalRun({
     engagementId: guardEngagementId,
     runType: "ci",
-    // Phase source (D6, HALFCYCLE_PHASE) — emit.ts normalises this to the exact
-    // phase-<N>.jsonl filename the Build-Record reader expects (#61 seam). Absent
-    // at CI time → the run is unphased (lands in unphased.jsonl).
+    // The phase this run belongs to, as the client named it — it names the
+    // guard-eval log file the run is appended to. Absent at CI time → the run
+    // is unphased and lands in unphased.jsonl.
     phase: telemetryConfig.phase,
     outcome: "evaluated",
     changeSet,
@@ -16202,6 +16360,9 @@ async function runCi() {
   return actOnEnvelope(clientResult.envelope);
 }
 function actOnEnvelope(envelope) {
+  const notRun = notRunReport(envelope.notRun, "[Halfcycle CI]");
+  if (notRun)
+    process.stdout.write(notRun + "\n");
   if (envelope.guardsFired.length === 0) {
     return 0;
   }
@@ -16275,7 +16436,8 @@ async function runPostToolUse() {
   const { guardServiceUrl, guardServiceToken, guardEngagementId } = configResult.config;
   const clientResult = await evaluate(guardServiceUrl, guardServiceToken, {
     engagementId: guardEngagementId,
-    changeSet
+    changeSet,
+    clientCapabilities: deriveClientCapabilities(changeSet)
   });
   if (!clientResult.ok) {
     const failure = classifyFailure(clientResult);
@@ -16301,8 +16463,8 @@ async function runPostToolUse() {
   const run = buildGuardEvalRun({
     engagementId: guardEngagementId,
     runType: "hook",
-    // Phase source (D6, HALFCYCLE_PHASE) — emit.ts normalises this to the exact
-    // phase-<N>.jsonl filename the Build-Record reader expects (#61 seam).
+    // The phase this run belongs to, as the client named it — it names the
+    // guard-eval log file the run is appended to. Absent → the run is unphased.
     phase: telemetryConfig.phase,
     outcome: "evaluated",
     changeSet,
@@ -16319,18 +16481,23 @@ async function runPostToolUse() {
   actOnEnvelope2(clientResult.envelope);
 }
 function actOnEnvelope2(envelope) {
+  const notRun = notRunReport(envelope.notRun);
+  const notRunBlock = notRun ? `
+${notRun}` : "";
   if (envelope.guardsFired.length === 0) {
+    if (notRun)
+      emitWarning(notRun);
     return;
   }
   if (envelope.blocking) {
     const guardLines = envelope.guardsFired.map((g) => `  [${g.severity.toUpperCase()}] ${g.patternRef}: ${g.explanation}`).join("\n");
     const reason = `Guard blocked: ${envelope.explanation}
-${guardLines}`;
+${guardLines}${notRunBlock}`;
     emitBlock(reason);
   } else {
     const guardLines = envelope.guardsFired.map((g) => `  [${g.severity.toUpperCase()}] ${g.patternRef}: ${g.explanation}`).join("\n");
     emitWarning(`[Halfcycle] Guard warning: ${envelope.explanation}
-${guardLines}`);
+${guardLines}${notRunBlock}`);
   }
 }
 function readStdin() {
@@ -16535,7 +16702,8 @@ async function runSessionDiff(input, kind) {
   const { guardServiceUrl, guardServiceToken, guardEngagementId } = configResult.config;
   const clientResult = await evaluate(guardServiceUrl, guardServiceToken, {
     engagementId: guardEngagementId,
-    changeSet
+    changeSet,
+    clientCapabilities: deriveClientCapabilities(changeSet)
   });
   if (!clientResult.ok) {
     const failure = classifyFailure(clientResult);
@@ -16579,20 +16747,26 @@ async function runSessionDiff(input, kind) {
   actOnEnvelope3(clientResult.envelope, kind, input.stop_hook_active === true);
 }
 function actOnEnvelope3(envelope, kind, neverBlock) {
-  if (envelope.guardsFired.length === 0)
+  const notRun = notRunReport(envelope.notRun);
+  const notRunBlock = notRun ? `
+${notRun}` : "";
+  if (envelope.guardsFired.length === 0) {
+    if (notRun)
+      emitWarning(notRun);
     return;
+  }
   const where = kind === "stop" ? "session stop" : "session stop";
   const guardLines = envelope.guardsFired.map((g) => `  [${g.severity.toUpperCase()}] ${g.patternRef}: ${g.explanation}`).join("\n");
   if (envelope.blocking && !neverBlock) {
     emitBlock(`Guard blocked at ${where}: ${envelope.explanation}
-${guardLines}`);
+${guardLines}${notRunBlock}`);
   } else if (envelope.blocking && neverBlock) {
     emitWarning(`[Halfcycle] Guard would block at ${where} but the stop was already continued (stop_hook_active) \u2014 surfacing as a warning:
 ${envelope.explanation}
-${guardLines}`);
+${guardLines}${notRunBlock}`);
   } else {
     emitWarning(`[Halfcycle] Guard warning at ${where}: ${envelope.explanation}
-${guardLines}`);
+${guardLines}${notRunBlock}`);
   }
 }