halfcycle 0.3.17 → 0.3.19

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcycle",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "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/README.md

@@ -42,7 +42,7 @@ A method document cannot fix that, because a document cannot interrupt you. This
 
 Credit where it is due, and it is due. GStack, Matt Pocock's skills, GitHub Spec Kit, BMAD, OpenSpec and claude-flow are genuinely good, and between them they taught this whole category that the bottleneck is discipline rather than model intelligence. We took two things from them deliberately and say so: the one-question-at-a-time interrogation shape, and an install that is one command and then stays out of your way.
 
-If you are one person on a two week project, install one of those instead. They are excellent at exactly that, and you may not need any of this yet.
+The objection this usually meets is that it must be too much for a small project. It would be, if there were one setting. A folder you download has exactly one, so whoever wrote it had to choose who to disappoint, and it is usually the small project that gets buried and quietly drops the process in week three. This reads the work instead and sizes itself to it, which is the section further down.
 
 Writing the process down was never the hard part. What a folder you download structurally cannot have is these four things.
 

package/bin/bin.bundle.mjs

@@ -39,6 +39,9 @@ function readConfig() {
     }
   };
 }
+function readNeverConfiguredReason() {
+  return process.env["HALFCYCLE_NOT_THIS_ACCOUNT"] === "1" ? "not-this-account" : "no-credential-yet";
+}
 function readExcerptConfig() {
   const raw = process.env["HALFCYCLE_SOURCE_EXCERPTS"];
   const enabled = (raw ?? "").trim().toLowerCase() === "true";
@@ -14594,6 +14597,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 +14718,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 +14745,62 @@ 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 (identity === "")
+    return "(empty)";
+  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 +15928,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 +16069,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) {
@@ -16045,8 +16199,8 @@ This is not a service outage: the guard service answered. The suspect is this re
 }
 var UNCONFIGURED_EXIT_TOOL_USE = 2;
 var UNCONFIGURED_EXIT_STOP_FAMILY = 1;
-function emitNeverConfigured(missing, exitCode) {
-  writeSync(2, neverConfiguredMessage(missing, HOOK_REMEDY));
+function emitNeverConfigured(missing, exitCode, reason) {
+  writeSync(2, neverConfiguredReport(missing, reason));
   process.exitCode = exitCode;
 }
 var HOOK_REMEDY = `Fix it by running "npx halfcycle" in this repository: it may open your browser to sign in first, then writes this engagement's credentials to ~/.halfcycle \u2014 outside the repository \u2014 and the hook loads them itself.`;
@@ -16058,6 +16212,18 @@ This is not a service outage. It means the guard has never run here \u2014 not o
 ${remedy}
 `;
 }
+function notThisAccountReport(label) {
+  return `${label} This project belongs to another Halfcycle account. Halfcycle is Solo today \u2014 one person works on a project at a time \u2014 so no credential exists for this machine and none will be issued. Nothing here needs fixing; this copy simply is not checked. Ask the project's owner for view access, or \u2014 if this account is wrong \u2014 sign in as the one that owns the project and run "npx halfcycle" again.
+`;
+}
+function neverConfiguredReport(missing, reason, label = "[Halfcycle]") {
+  switch (reason) {
+    case "no-credential-yet":
+      return neverConfiguredMessage(missing, HOOK_REMEDY, label);
+    case "not-this-account":
+      return notThisAccountReport(label);
+  }
+}
 var CREDENTIAL_REJECTED_STATUSES = /* @__PURE__ */ new Set([401, 403]);
 function classifyFailure(failure) {
   if (failure.kind === "contract-error") {
@@ -16104,6 +16270,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 +16328,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 +16358,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 +16377,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;
   }
@@ -16269,13 +16447,14 @@ async function runPostToolUse() {
   const configResult = readConfig();
   if (!configResult.config) {
     await emitRunRecord({ runType: "hook", outcome: "unconfigured", changeSet });
-    emitNeverConfigured(configResult.missing, UNCONFIGURED_EXIT_TOOL_USE);
+    emitNeverConfigured(configResult.missing, UNCONFIGURED_EXIT_TOOL_USE, readNeverConfiguredReason());
     return;
   }
   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 +16480,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 +16498,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() {
@@ -16529,13 +16713,14 @@ async function runSessionDiff(input, kind) {
   const configResult = readConfig();
   if (!configResult.config) {
     await emitRunRecord({ runType: "hook", outcome: "unconfigured", changeSet, diffBase });
-    emitNeverConfigured(configResult.missing, UNCONFIGURED_EXIT_STOP_FAMILY);
+    emitNeverConfigured(configResult.missing, UNCONFIGURED_EXIT_STOP_FAMILY, readNeverConfiguredReason());
     return;
   }
   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 +16764,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}`);
   }
 }