halfcycle 0.3.26 → 0.3.27

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcycle",
-  "version": "0.3.26",
+  "version": "0.3.27",
   "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

@@ -44,15 +44,13 @@ Credit where it is due, and it is due. GStack, Matt Pocock's skills, GitHub Spec
 
 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.
+Writing the process down was never the hard part. What a folder you download structurally cannot have is these three things.
 
 **1. Something other than you checks the work.** A document cannot audit itself, and the session that wrote the draft is the worst available reviewer of it. So Halfcycle's consistency check runs in a session that has never seen your draft, and the method makes that non-negotiable rather than advisory: after every round of fixes it runs again in another new session, never the one that asked for those fixes, because the reviewer that asked for a fix is the one who cannot see what the fix stranded. The guard checks are the harder edge — they run off your machine, on ours, on every real change, and one that fires either warns you or stops the work outright, depending on how serious the rule it broke is.
 
-**2. Evidence that a piece of work actually finished.** Each phase closes with a Build Record: what was decided, what fired, what was accepted, assembled from your repo's own artefacts. That is a document an auditor, a board or a client can read. "The agent said it was done" is not.
+**2. The same gates on every contributor.** The requirement lives in the repository, so everybody inherits identical checks with nothing to set up, and a new hire is compliant in one command. No framework is single-player by accident; they are single-player by construction, and several people changing the same codebase faster than they can synchronise is the one problem a single-session rulebook cannot see.
 
-**3. The same gates on every contributor.** The requirement lives in the repository, so everybody inherits identical checks with nothing to set up, and a new hire is compliant in one command. No framework is single-player by accident; they are single-player by construction, and several people changing the same codebase faster than they can synchronise is the one problem a single-session rulebook cannot see.
-
-**4. A record of how builds break that keeps growing.** This is the part that compounds, and it is why a fork is a snapshot that starts depreciating the day you take it. See below.
+**3. A record of how builds break that keeps growing.** This is the part that compounds, and it is why a fork is a snapshot that starts depreciating the day you take it. See below.
 
 ---
 
@@ -158,7 +156,7 @@ This matters enough to be specific about.
 
 ## What you keep
 
-Everything the method produces is yours, under your own `docs/`, in your git history, in plain markdown: the product spec, the architecture, the phase plans, the feature specs, the ordered work and the Build Records. It reads as documentation your team wrote, because it is.
+Everything the method produces is yours, under your own `docs/`, in your git history, in plain markdown: the product spec, the architecture, the phase plans, the feature specs and the ordered work. It reads as documentation your team wrote, because it is.
 
 Nothing you already had is changed. Existing settings are preserved, and a name collision is reported rather than resolved on your behalf.
 

package/bin/bin.bundle.mjs

@@ -14549,6 +14549,11 @@ var HALFCYCLE_DIR_NAME = ".halfcycle";
 var ENGAGEMENTS_DIR_NAME = "engagements";
 var ENGAGEMENT_ENV_FILENAME = "env";
 var ACCOUNT_STORE_FILENAME = "account.json";
+var ENGAGEMENT_ID_PATTERN = "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$";
+var ENGAGEMENT_ID_SHAPE = new RegExp(ENGAGEMENT_ID_PATTERN);
+function isEngagementId(value) {
+  return typeof value === "string" && ENGAGEMENT_ID_SHAPE.test(value);
+}
 var ENGAGEMENT_ENV_HEADER = "# Halfcycle per-engagement credential \u2014 machine level, owner-only, never in a repository.";
 function shq(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -14684,6 +14689,9 @@ function readConfig() {
 function readNeverConfiguredReason() {
   return process.env["HALFCYCLE_NOT_THIS_ACCOUNT"] === "1" ? "not-this-account" : "no-credential-yet";
 }
+function isHalfcycleOwnCi() {
+  return process.env["HALFCYCLE_INTERNAL_CI"] === "1";
+}
 function readGuardOrigin() {
   return resolveGuardOrigin(process.env);
 }
@@ -14813,7 +14821,15 @@ var evaluationRequestSchema = external_exports.object({
    * 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()
+  clientCapabilities: external_exports.array(external_exports.string()).optional(),
+  /**
+   * Whether this repository has any deploy file — a Dockerfile, a fly.toml or
+   * a .env.example — anywhere in its tree. A check that compares code against
+   * those files reports itself as not run when this is false.
+   *
+   * Omitting the field means "unknown": every check runs as it always has.
+   */
+  repoHasDeployFiles: external_exports.boolean().optional()
 }).strict();
 
 // ../events/dist/result.js
@@ -15143,9 +15159,10 @@ var HOOK_REMEDY = `Fix it by running "npx halfcycle" in this repository: it may
 var PERMISSIONS_BLOCK = "\n    permissions:\n      contents: read\n      id-token: write\n\n";
 var BOTH_LINES_SENTENCE = "BOTH LINES. Declaring any permission replaces the defaults rather than adding to them, so a block naming only the identity token takes read access away from the checkout step and a private repository stops checking out before this check is reached.";
 var CI_CANNOT_PROVE_PROJECT = "has no way to prove which project it belongs to";
-var CI_REMEDY_LEAD = "Add this to the workflow \u2014 at the top of the file, or on this job:\n" + PERMISSIONS_BLOCK + `${BOTH_LINES_SENTENCE} Then, once, on your own machine in this project, if you have not already: \`npx halfcycle ci bind <owner>/<repo>\`. That is the whole configuration \u2014 there is no secret to store.`;
+var CI_REMEDY_LEAD = "Add this to the workflow \u2014 at the top of the file, or on this job:\n" + PERMISSIONS_BLOCK + `${BOTH_LINES_SENTENCE} Binding a repository so a run means something is internal to Halfcycle \u2014 contact hello@halfcycle.ai to have this one bound. There is no secret to store.`;
 var CI_OLDER_SETUP = "The older setup, GUARD_SERVICE_TOKEN and GUARD_ENGAGEMENT_ID supplied as repository secrets, still works unchanged, and a job that has both needs neither line.";
 var CI_REMEDY = `This job cannot vouch for anything, because it ${CI_CANNOT_PROVE_PROJECT}. ${CI_REMEDY_LEAD} ${CI_OLDER_SETUP}`;
+var CI_NOT_SUPPORTED_MESSAGE = "[Halfcycle CI] This is Halfcycle-internal and is not supported in your CI.\n";
 var NEVER_CONFIGURED_HEADLINE = "GUARD NEVER CONFIGURED";
 var NOT_A_SERVICE_OUTAGE = "This is not a service outage.";
 function neverConfiguredMessage(missing, remedy, label = "[Halfcycle]") {
@@ -15624,8 +15641,8 @@ function screenExcerpts(excerpts) {
 }
 
 // dist/extract/env-refs.js
-function extractEnvRefs(diffContent, context = {}) {
-  const names = detectEnvReads(diffContent);
+function extractEnvRefs(diffContent, context = {}, filePath) {
+  const names = detectEnvReads(diffContent, filePath !== void 0 && usesJsComments(filePath));
   if (names.size === 0)
     return [];
   const result = [];
@@ -15634,19 +15651,31 @@ function extractEnvRefs(diffContent, context = {}) {
   }
   return result;
 }
-function detectEnvReads(diffContent) {
+var JS_COMMENT_EXTENSIONS = /\.(?:[cm]?[jt]sx?|vue|svelte|astro)$/i;
+function usesJsComments(filePath) {
+  return JS_COMMENT_EXTENSIONS.test(filePath);
+}
+function detectEnvReads(diffContent, jsComments) {
   const found = /* @__PURE__ */ new Set();
   const dotPattern = /(?:process\.env|import\.meta\.env)\.([A-Z_][A-Z0-9_]*)/g;
   const bracketPattern = /(?:process\.env|import\.meta\.env)\s*\[\s*['"]([A-Z_][A-Z0-9_]*)['"]\s*\]/g;
-  const destructurePattern = /\{([^}]*)\}\s*=\s*(?:process\.env|import\.meta\.env)\b/g;
-  for (const line of diffContent.split("\n")) {
-    if (line.startsWith("-") && !line.startsWith("---"))
+  const destructurePattern = /\{([^{}]*)\}\s*=\s*(?:process\.env|import\.meta\.env)\b/g;
+  for (const raw of diffContent.split("\n")) {
+    if (raw.startsWith("-") && !raw.startsWith("---"))
       continue;
+    const isSource = raw.startsWith("+") && !raw.startsWith("+++") || raw.startsWith(" ");
+    const line = jsComments && isSource ? raw.slice(1) : raw;
+    const comment = jsComments && isSource ? commentedOut(line) : void 0;
+    const live = (match) => comment === void 0 || !comment(match.index, match.index + match[0].length);
     for (const match of line.matchAll(dotPattern))
-      found.add(match[1]);
+      if (live(match))
+        found.add(match[1]);
     for (const match of line.matchAll(bracketPattern))
-      found.add(match[1]);
+      if (live(match))
+        found.add(match[1]);
     for (const destructure of line.matchAll(destructurePattern)) {
+      if (!live(destructure))
+        continue;
       for (const part of destructure[1].split(",")) {
         const nameMatch = part.trim().match(/^([A-Z_][A-Z0-9_]*)\s*(?:[:=]|$)/);
         if (nameMatch)
@@ -15656,6 +15685,28 @@ function detectEnvReads(diffContent) {
   }
   return found;
 }
+var LINE_TERMINATOR = /[\r\u2028\u2029]/g;
+function commentedOut(line) {
+  const lead = line.length - line.trimStart().length;
+  let body;
+  let close;
+  let expression;
+  if (line.startsWith("//", lead)) {
+    body = lead + 2;
+    LINE_TERMINATOR.lastIndex = body;
+    close = LINE_TERMINATOR.exec(line)?.index ?? line.length;
+    expression = "{";
+  } else if (line.startsWith("/*", lead) || line.startsWith("{/*", lead)) {
+    body = lead + (line[lead] === "{" ? 3 : 2);
+    const found = line.indexOf("*/", body);
+    close = found === -1 ? line.length : found;
+    expression = line[lead] === "{" ? "${" : "{";
+  } else {
+    return void 0;
+  }
+  const opened = line.indexOf(expression, body);
+  return (start, end) => start >= body && end <= close && (opened === -1 || opened >= start || opened >= close);
+}
 function collectDeclarationFiles(context) {
   const files = [];
   if (context.dockerfileContent) {
@@ -15667,10 +15718,16 @@ function collectDeclarationFiles(context) {
   if (context.envExampleContent) {
     files.push({ kind: "env-example", path: ".env.example", content: context.envExampleContent });
   }
-  if (context.declarationFiles)
-    files.push(...context.declarationFiles);
+  for (const file2 of context.declarationFiles ?? [])
+    files.push(file2);
   return files;
 }
+function repoHasDeployFiles(context) {
+  const looked = context.declarationFiles !== void 0 || context.dockerfileContent !== void 0 || context.flyTomlContent !== void 0 || context.envExampleContent !== void 0;
+  if (!looked)
+    return void 0;
+  return collectDeclarationFiles(context).length > 0;
+}
 function resolveArgType(name, context) {
   const files = collectDeclarationFiles(context);
   const build = isBuildTimeSite(name, files);
@@ -15745,10 +15802,18 @@ function envExampleHas(name, content, argType) {
 
 // dist/extract/strip-comments.js
 function stripComments(code) {
-  let out = code.replace(/\/\*[\s\S]*?\*\//g, " ");
-  const openBlock = out.indexOf("/*");
-  if (openBlock !== -1)
-    out = out.slice(0, openBlock);
+  let out = "";
+  let from = 0;
+  for (; ; ) {
+    const open = code.indexOf("/*", from);
+    const close = open === -1 ? -1 : code.indexOf("*/", open + 2);
+    if (close === -1) {
+      out += code.slice(from, open === -1 ? code.length : open);
+      break;
+    }
+    out += code.slice(from, open) + " ";
+    from = close + 2;
+  }
   const lineComment = out.match(/(^|[^:])\/\//);
   if (lineComment && lineComment.index !== void 0) {
     const cut = lineComment.index + lineComment[1].length;
@@ -16422,26 +16487,16 @@ function stripDiffPrefix4(line) {
 
 // dist/changeset.js
 var DOC_EXTENSIONS = /* @__PURE__ */ new Set([".md", ".mdx", ".txt", ".rst", ".adoc"]);
-var DOC_DIR_PATTERNS = [
-  "docs/",
-  "/docs/",
-  "skills/",
-  "/skills/",
-  "runbooks/",
-  "/runbooks/",
-  "method/",
-  "/method/"
-];
+var DOC_DIR_NAMES = /* @__PURE__ */ new Set(["docs", "skills", "runbooks", "method"]);
 function isCodeFile(filePath) {
   const lower = filePath.toLowerCase();
   for (const ext of DOC_EXTENSIONS) {
     if (lower.endsWith(ext))
       return false;
   }
-  for (const pat of DOC_DIR_PATTERNS) {
-    if (lower.includes(pat))
-      return false;
-  }
+  const dirs = lower.replace(/\\/g, "/").split("/").slice(0, -1);
+  if (dirs.some((dir) => DOC_DIR_NAMES.has(dir)))
+    return false;
   return true;
 }
 var INSTALLER_OUTPUT_DIR = ".halfcycle/";
@@ -16479,7 +16534,7 @@ function buildChangeSet(files, context = {}) {
       };
     }
     const astShapes = toAstShapes(detectBlastRadiusMarkers(filePath, diffContent));
-    const envRefs = extractEnvRefs(diffContent, context);
+    const envRefs = extractEnvRefs(diffContent, context, filePath);
     const sqlWrites = extractSqlWrites(diffContent);
     const thirdPartyEndpoints = extractThirdPartyEndpoints(diffContent, {
       repoRoot: context.repoRoot
@@ -16517,6 +16572,15 @@ function deriveClientCapabilities(changeSet) {
   }
   return [...seen];
 }
+function buildEvaluationRequest(engagementId, changeSet, context) {
+  const hasDeployFiles = repoHasDeployFiles(context);
+  return {
+    engagementId,
+    changeSet,
+    clientCapabilities: deriveClientCapabilities(changeSet),
+    ...hasDeployFiles === void 0 ? {} : { repoHasDeployFiles: hasDeployFiles }
+  };
+}
 function produceExcerpts(diffContent, descriptors, caps) {
   const excerpts = [];
   const seen = /* @__PURE__ */ new Set();
@@ -16817,24 +16881,21 @@ async function runCi() {
         guardServiceUrl: readGuardOrigin().origin,
         guardServiceToken: acquired.credential.guardServiceToken,
         guardEngagementId: acquired.credential.guardEngagementId,
-        changeSet
+        changeSet,
+        context
       });
     }
   }
   if (!configResult.config) {
     await emitRunRecord({ runType: "ci", outcome: "unconfigured", changeSet });
-    process.stderr.write(ciNeverConfiguredMessage());
+    process.stderr.write(isHalfcycleOwnCi() ? ciNeverConfiguredMessage() : CI_NOT_SUPPORTED_MESSAGE);
     return 1;
   }
-  return await evaluateAndAct({ ...configResult.config, changeSet });
+  return await evaluateAndAct({ ...configResult.config, changeSet, context });
 }
 async function evaluateAndAct(args2) {
-  const { guardServiceUrl, guardServiceToken, guardEngagementId, changeSet } = args2;
-  const clientResult = await evaluate(guardServiceUrl, guardServiceToken, {
-    engagementId: guardEngagementId,
-    changeSet,
-    clientCapabilities: deriveClientCapabilities(changeSet)
-  });
+  const { guardServiceUrl, guardServiceToken, guardEngagementId, changeSet, context } = args2;
+  const clientResult = await evaluate(guardServiceUrl, guardServiceToken, buildEvaluationRequest(guardEngagementId, changeSet, context));
   if (!clientResult.ok) {
     const failure = classifyFailure(clientResult);
     await emitRunRecord({
@@ -16846,7 +16907,7 @@ async function evaluateAndAct(args2) {
       credentialRefused: failure.kind === "credential"
     });
     if (failure.kind === "credential") {
-      process.stderr.write(credentialRejectedMessage(failure.statusCode, failure.message, CI_REMEDY, "[Halfcycle CI]"));
+      process.stderr.write(isHalfcycleOwnCi() ? credentialRejectedMessage(failure.statusCode, failure.message, CI_REMEDY, "[Halfcycle CI]") : CI_NOT_SUPPORTED_MESSAGE);
       return 1;
     }
     if (failure.kind === "service") {
@@ -16951,7 +17012,6 @@ import { homedir as homedir2, platform } from "node:os";
 import { dirname as dirname3, join as join5 } from "node:path";
 var REFRESHED_TOKEN_KEYS = ["HALFCYCLE_TOKEN", "GUARD_SERVICE_TOKEN"];
 var TOKEN_READ_KEY = "GUARD_SERVICE_TOKEN";
-var UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function composeEngagementEnvPath(engagementId, home) {
   return join5(home ?? homedir2(), HALFCYCLE_DIR_NAME, ENGAGEMENTS_DIR_NAME, engagementId, ENGAGEMENT_ENV_FILENAME);
 }
@@ -16979,7 +17039,7 @@ function readStoredEngagementToken(envFilePath) {
   return value && value.trim() !== "" ? value : void 0;
 }
 function writeRefreshedToken(opts) {
-  if (!UUID_SHAPE.test(opts.engagementId)) {
+  if (!isEngagementId(opts.engagementId)) {
     return { written: false, reason: "the engagement this session names is not one this store can be keyed by" };
   }
   let declaredReal;
@@ -17179,11 +17239,7 @@ async function runPostToolUse() {
     guardServiceUrl,
     token: guardServiceToken,
     engagementId: guardEngagementId,
-    request: {
-      engagementId: guardEngagementId,
-      changeSet,
-      clientCapabilities: deriveClientCapabilities(changeSet)
-    }
+    request: buildEvaluationRequest(guardEngagementId, changeSet, context)
   });
   const clientResult = evaluation.result;
   if (!clientResult.ok) {
@@ -17468,11 +17524,7 @@ async function runSessionDiff(input, kind) {
     guardServiceUrl,
     token: guardServiceToken,
     engagementId: guardEngagementId,
-    request: {
-      engagementId: guardEngagementId,
-      changeSet,
-      clientCapabilities: deriveClientCapabilities(changeSet)
-    }
+    request: buildEvaluationRequest(guardEngagementId, changeSet, context)
   });
   const clientResult = evaluation.result;
   if (!clientResult.ok) {
@@ -17866,6 +17918,7 @@ function readStdin3() {
 }
 main().catch((err) => {
   process.stderr.write(`halfcycle-runner: unexpected error: ${err instanceof Error ? err.message : String(err)}
+Contact hello@halfcycle.ai if this keeps happening.
 `);
   process.exit(1);
 });

package/dist/bin.d.ts

@@ -11,13 +11,19 @@
  *   halfcycle build-record <phase>           — assemble the phase Build Record (D1)
  *   halfcycle open-phase <phase>             — open a phase, with its entry decision
  *   halfcycle close-phase <phase>            — record a phase's acceptance and close it
- *   halfcycle ci bind <owner>/<repo>         — trust that repository's CI for this engagement
- *   halfcycle ci unbind <owner>/<repo>       — withdraw that trust
+ *   halfcycle uninstall [--remove-credential] — take back what the installer wrote here
  *
- * EVERY NON-INSTALL SUBCOMMAND MUST BE NAMED IN `bareTarget` BELOW. The bare form
+ * NO `ci` VERB (T-25, operator decision 2026-09-22(c)) — `ci bind`/`ci unbind`
+ * generalised a fix for Halfcycle's own dogfood CI into a client-facing feature;
+ * setting up a project's CI is project scope, not something this product does for
+ * a client. See `ci-oidc-token-exchange.md`.
+ *
+ * `bareTarget` BELOW IS DERIVED FROM `CLI_VERBS` (T-21). The bare form
  * (`npx halfcycle` / `npx halfcycle ./repo`) treats the first positional as an
- * install target, so a subcommand missing from that list is not "unknown command" —
- * it is silently an install into a directory named after the verb.
+ * install target, so a verb it did not recognise would not be "unknown command" —
+ * it would silently be an install into a directory named after the verb. It was a
+ * second, hand-typed list of verbs until `uninstall` joined, which is the verb whose
+ * misreading would be worst: `halfcycle uninstall` INSTALLING. One list now.
  *
  * TWO GUARDS ON THAT SHAPE (W3-F-4, walk 4). The bare-form-installs behaviour is
  * deliberate and stays — it is the primary distribution path — but walk 4 ran the

package/dist/bin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG"}
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG"}