halfcycle 0.3.8 → 0.3.10

package/dist/index.js

@@ -3,6 +3,173 @@ import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as rea
 import { dirname as dirname2, join as join5, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 
+// ../events/dist/result.js
+import { z as z2 } from "zod";
+
+// ../core/dist/guard-record.js
+import { z } from "zod";
+var severitySchema = z.enum(["info", "warn", "block"]);
+var channelSchema = z.enum(["stable", "candidate", "rented"]);
+var matcherKindSchema = z.enum(["grep", "ast", "integrationTest", "llm"]);
+var matcherConfigSchema = z.record(z.string(), z.unknown());
+var grepMatcherSchema = z.object({ kind: z.literal("grep"), config: matcherConfigSchema }).strict();
+var astMatcherSchema = z.object({ kind: z.literal("ast"), config: matcherConfigSchema }).strict();
+var integrationTestMatcherSchema = z.object({ kind: z.literal("integrationTest"), config: matcherConfigSchema }).strict();
+var llmMatcherSchema = z.object({ kind: z.literal("llm"), config: matcherConfigSchema }).strict();
+var matcherSchema = z.discriminatedUnion("kind", [
+  grepMatcherSchema,
+  astMatcherSchema,
+  integrationTestMatcherSchema,
+  llmMatcherSchema
+]);
+
+// ../events/dist/result.js
+var firedGuardSchema = z2.object({
+  guardId: z2.string(),
+  patternRef: z2.string(),
+  severity: severitySchema,
+  explanation: z2.string(),
+  /**
+   * The repo-relative path of the file this firing was decided on. The matcher
+   * has the file live at the moment it decides to fire; this is the field that
+   * carries the answer out. It is the CLIENT's own coordinate — the wire type
+   * still has no field for a matcher body, a channel, a version, a scope or a
+   * guard's provenance, and physically cannot carry one.
+   *
+   * THE PRESENCE RULE, WHICH LIVES HERE AND NOT IN A CONSUMER'S PROSE: every
+   * firing produced from this contract version onward carries `path`, so on the
+   * WIRE, absence means exactly one thing — a response from a guard service
+   * older than this contract. It is declared optional because a client's guard
+   * runner is built from its own checkout and calls a service that may be older
+   * than it; a required field would make that pairing unparseable.
+   *
+   * The rule does NOT transfer to a store that persists a firing, where an
+   * absent path has a second legitimate meaning: a row written before the
+   * column existed. A persisted NULL is therefore not a writer bug.
+   *
+   * NO SHAPE CONSTRAINT. This value is whatever the changed tree called the
+   * file. A consumer that maps it onto a coordinate with its own path rule must
+   * safe-parse it and decide what to do with a refusal, rather than assume the
+   * two shapes agree.
+   */
+  path: z2.string().optional()
+}).strict();
+var resultEnvelopeSchema = z2.object({
+  guardsFired: z2.array(firedGuardSchema),
+  severity: severitySchema.nullable(),
+  blocking: z2.boolean(),
+  explanation: z2.string()
+}).strict();
+var wireErrorSchema = z2.object({
+  statusCode: z2.number(),
+  error: z2.string(),
+  message: z2.string()
+}).strict();
+
+// ../events/dist/telemetry.js
+import { z as z3 } from "zod";
+var utcIso8601 = z3.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/, "must be a UTC ISO-8601 timestamp ending in Z (INV-015)");
+var guardEvalOutcomeSchema = z3.enum([
+  "evaluated",
+  "infra-error",
+  "contract-error",
+  "unconfigured"
+]);
+var guardEvalRunSchema = z3.object({
+  // `runId`/`outcome` are the E2 run-observability additions, declared
+  // field-level-OPTIONAL as the FIRST (expand) step of an expand-contract
+  // migration. Every new record populated by the migrated writer (T-07)
+  // carries both; a legacy line predating the amendment carries neither and
+  // must still parse (the mixed-era guard-eval log the Build-Record reader
+  // assembles from, and the runner emit not yet migrated). So the presence
+  // refinement below is skipped for a legacy line (no `outcome`), and the
+  // per-writer guarantee lives with the writer + reader-normalisation (T-07),
+  // where the schema may then be tightened to required. runId is uuid-checked
+  // WHEN present; outcome is enum-checked when present.
+  runId: z3.string().uuid().optional(),
+  engagementId: z3.string().optional(),
+  runType: z3.enum(["hook", "ci"]),
+  occurredAt: utcIso8601,
+  outcome: guardEvalOutcomeSchema.optional(),
+  failureReason: z3.string().optional(),
+  phase: z3.string().optional(),
+  scope: z3.record(z3.string(), z3.unknown()),
+  cost: z3.record(z3.string(), z3.unknown()).optional(),
+  result: resultEnvelopeSchema.optional()
+}).strict().superRefine((run, ctx) => {
+  if (run.outcome === void 0)
+    return;
+  if (run.outcome === "evaluated" && run.result === void 0) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      path: ["result"],
+      message: "result is required when outcome is 'evaluated'"
+    });
+  }
+  if (run.outcome !== "evaluated" && run.result !== void 0) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      path: ["result"],
+      message: "result is only present when outcome is 'evaluated'"
+    });
+  }
+  if (run.outcome !== "unconfigured" && run.engagementId === void 0) {
+    ctx.addIssue({
+      code: z3.ZodIssueCode.custom,
+      path: ["engagementId"],
+      message: "engagementId is required unless outcome is 'unconfigured'"
+    });
+  }
+});
+
+// ../events/dist/crew.js
+import { z as z4 } from "zod";
+var crewGroupSchema = z4.enum(["builder", "reviewer", "always-on"]);
+var crewTierSchema = z4.enum(["deep", "standard", "fast"]);
+var CREW_DISCIPLINE_MAX = 64;
+var crewMemberSchema = z4.object({
+  // The agent's name. The same twenty-one on every project, so a name is a
+  // vocabulary a returning client already knows.
+  callsign: z4.string().min(1).max(32),
+  // Which of the three headings this member reads under.
+  group: crewGroupSchema,
+  // The kind of work this member takes. A task names a discipline, and only
+  // agents holding it can be dispatched to it.
+  discipline: z4.string().min(1).max(CREW_DISCIPLINE_MAX),
+  // How much thinking this member brings. There is no field naming the supplier
+  // behind it, on this shape or on any other.
+  tier: crewTierSchema
+}).strict();
+var CREW_ROSTER = [
+  // ── builders: code ──────────────────────────────────────────────────────────
+  { callsign: "ADA", group: "builder", discipline: "implementation", tier: "deep" },
+  { callsign: "OTTO", group: "builder", discipline: "implementation", tier: "deep" },
+  { callsign: "MILO", group: "builder", discipline: "implementation", tier: "standard" },
+  { callsign: "NOVA", group: "builder", discipline: "implementation", tier: "standard" },
+  { callsign: "KAI", group: "builder", discipline: "implementation", tier: "standard" },
+  { callsign: "HUGO", group: "builder", discipline: "infrastructure", tier: "standard" },
+  { callsign: "WREN", group: "builder", discipline: "refactor", tier: "fast" },
+  { callsign: "PIP", group: "builder", discipline: "refactor", tier: "fast" },
+  // ── builders: specs and docs ────────────────────────────────────────────────
+  { callsign: "IRIS", group: "builder", discipline: "feature spec", tier: "deep" },
+  { callsign: "JUNO", group: "builder", discipline: "feature spec", tier: "standard" },
+  { callsign: "LEX", group: "builder", discipline: "context & docs", tier: "fast" },
+  // ── reviewers ───────────────────────────────────────────────────────────────
+  { callsign: "VERA", group: "reviewer", discipline: "spec consistency", tier: "deep" },
+  { callsign: "ODIN", group: "reviewer", discipline: "cross-spec audit", tier: "deep" },
+  { callsign: "CASS", group: "reviewer", discipline: "code review", tier: "deep" },
+  { callsign: "THEO", group: "reviewer", discipline: "code review", tier: "standard" },
+  { callsign: "ECHO", group: "reviewer", discipline: "test quality", tier: "standard" },
+  { callsign: "MAVIS", group: "reviewer", discipline: "suites & coverage", tier: "standard" },
+  { callsign: "ZARA", group: "reviewer", discipline: "smoke & walk aid", tier: "standard" },
+  { callsign: "NORA", group: "reviewer", discipline: "evidence & provenance", tier: "fast" },
+  // ── always on: continuous, takes no task ────────────────────────────────────
+  { callsign: "ARGUS", group: "always-on", discipline: "guard \xB7 every diff", tier: "standard" },
+  { callsign: "ATLAS", group: "always-on", discipline: "coordinator", tier: "deep" }
+];
+var CREW_ROSTER_SIZE = CREW_ROSTER.length;
+var CREW_CALLSIGNS = CREW_ROSTER.map((member) => member.callsign);
+
 // dist/engagement-credential.js
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { platform as platform2 } from "node:os";
@@ -30,6 +197,7 @@ var GUARD_ENV_KEYS = [
   "GUARD_SERVICE_TOKEN",
   "GUARD_ENGAGEMENT_ID"
 ];
+var GUARD_COVERAGE_REQUIRED_KEYS = GUARD_ENV_KEYS.filter((key) => key !== "GUARD_SERVICE_URL");
 var ENGAGEMENT_ENV_KEYS = [
   "HALFCYCLE_SERVICE_URL",
   "HALFCYCLE_MCP_URL",
@@ -279,127 +447,6 @@ function mergePermissions(existing, generated) {
 // dist/scan.js
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { join as join4 } from "node:path";
-
-// ../events/dist/result.js
-import { z as z2 } from "zod";
-
-// ../core/dist/guard-record.js
-import { z } from "zod";
-var severitySchema = z.enum(["info", "warn", "block"]);
-var channelSchema = z.enum(["stable", "candidate", "rented"]);
-var matcherKindSchema = z.enum(["grep", "ast", "integrationTest", "llm"]);
-var matcherConfigSchema = z.record(z.string(), z.unknown());
-var grepMatcherSchema = z.object({ kind: z.literal("grep"), config: matcherConfigSchema }).strict();
-var astMatcherSchema = z.object({ kind: z.literal("ast"), config: matcherConfigSchema }).strict();
-var integrationTestMatcherSchema = z.object({ kind: z.literal("integrationTest"), config: matcherConfigSchema }).strict();
-var llmMatcherSchema = z.object({ kind: z.literal("llm"), config: matcherConfigSchema }).strict();
-var matcherSchema = z.discriminatedUnion("kind", [
-  grepMatcherSchema,
-  astMatcherSchema,
-  integrationTestMatcherSchema,
-  llmMatcherSchema
-]);
-
-// ../events/dist/result.js
-var firedGuardSchema = z2.object({
-  guardId: z2.string(),
-  patternRef: z2.string(),
-  severity: severitySchema,
-  explanation: z2.string(),
-  /**
-   * The repo-relative path of the file this firing was decided on. The matcher
-   * has the file live at the moment it decides to fire; this is the field that
-   * carries the answer out. It is the CLIENT's own coordinate — the wire type
-   * still has no field for a matcher body, a channel, a version, a scope or a
-   * guard's provenance, and physically cannot carry one.
-   *
-   * THE PRESENCE RULE, WHICH LIVES HERE AND NOT IN A CONSUMER'S PROSE: every
-   * firing produced from this contract version onward carries `path`, so on the
-   * WIRE, absence means exactly one thing — a response from a guard service
-   * older than this contract. It is declared optional because a client's guard
-   * runner is built from its own checkout and calls a service that may be older
-   * than it; a required field would make that pairing unparseable.
-   *
-   * The rule does NOT transfer to a store that persists a firing, where an
-   * absent path has a second legitimate meaning: a row written before the
-   * column existed. A persisted NULL is therefore not a writer bug.
-   *
-   * NO SHAPE CONSTRAINT. This value is whatever the changed tree called the
-   * file. A consumer that maps it onto a coordinate with its own path rule must
-   * safe-parse it and decide what to do with a refusal, rather than assume the
-   * two shapes agree.
-   */
-  path: z2.string().optional()
-}).strict();
-var resultEnvelopeSchema = z2.object({
-  guardsFired: z2.array(firedGuardSchema),
-  severity: severitySchema.nullable(),
-  blocking: z2.boolean(),
-  explanation: z2.string()
-}).strict();
-var wireErrorSchema = z2.object({
-  statusCode: z2.number(),
-  error: z2.string(),
-  message: z2.string()
-}).strict();
-
-// ../events/dist/telemetry.js
-import { z as z3 } from "zod";
-var utcIso8601 = z3.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/, "must be a UTC ISO-8601 timestamp ending in Z (INV-015)");
-var guardEvalOutcomeSchema = z3.enum([
-  "evaluated",
-  "infra-error",
-  "contract-error",
-  "unconfigured"
-]);
-var guardEvalRunSchema = z3.object({
-  // `runId`/`outcome` are the E2 run-observability additions, declared
-  // field-level-OPTIONAL as the FIRST (expand) step of an expand-contract
-  // migration. Every new record populated by the migrated writer (T-07)
-  // carries both; a legacy line predating the amendment carries neither and
-  // must still parse (the mixed-era guard-eval log the Build-Record reader
-  // assembles from, and the runner emit not yet migrated). So the presence
-  // refinement below is skipped for a legacy line (no `outcome`), and the
-  // per-writer guarantee lives with the writer + reader-normalisation (T-07),
-  // where the schema may then be tightened to required. runId is uuid-checked
-  // WHEN present; outcome is enum-checked when present.
-  runId: z3.string().uuid().optional(),
-  engagementId: z3.string().optional(),
-  runType: z3.enum(["hook", "ci"]),
-  occurredAt: utcIso8601,
-  outcome: guardEvalOutcomeSchema.optional(),
-  failureReason: z3.string().optional(),
-  phase: z3.string().optional(),
-  scope: z3.record(z3.string(), z3.unknown()),
-  cost: z3.record(z3.string(), z3.unknown()).optional(),
-  result: resultEnvelopeSchema.optional()
-}).strict().superRefine((run, ctx) => {
-  if (run.outcome === void 0)
-    return;
-  if (run.outcome === "evaluated" && run.result === void 0) {
-    ctx.addIssue({
-      code: z3.ZodIssueCode.custom,
-      path: ["result"],
-      message: "result is required when outcome is 'evaluated'"
-    });
-  }
-  if (run.outcome !== "evaluated" && run.result !== void 0) {
-    ctx.addIssue({
-      code: z3.ZodIssueCode.custom,
-      path: ["result"],
-      message: "result is only present when outcome is 'evaluated'"
-    });
-  }
-  if (run.outcome !== "unconfigured" && run.engagementId === void 0) {
-    ctx.addIssue({
-      code: z3.ZodIssueCode.custom,
-      path: ["engagementId"],
-      message: "engagementId is required unless outcome is 'unconfigured'"
-    });
-  }
-});
-
-// dist/scan.js
 var HALFCYCLE_STATE_FORMAT = "halfcycle-state-file/v1";
 var HALFCYCLE_STATE_NOTE = [
   "This file is a local cache written ONCE when Halfcycle was installed. It is not a",
@@ -705,7 +752,7 @@ ${engagementResolutionShell()}
     set +a
   fi
   hc_missing=""
-  for hc_key in ${GUARD_ENV_KEYS.join(" ")}; do
+  for hc_key in ${GUARD_COVERAGE_REQUIRED_KEYS.join(" ")}; do
     eval "hc_value=\\\${$hc_key:-}"
     if [ -z "$hc_value" ]; then hc_missing="$hc_missing $hc_key"; fi
   done
@@ -798,7 +845,10 @@ function generateCiStanza() {
 #         node-version: '20'
 #     - name: Halfcycle guard CI check
 #       env:
-#         GUARD_SERVICE_URL: \${{ secrets.GUARD_SERVICE_URL }}
+#         # TWO SECRETS, AND THEY ARE THE TWO THAT ARE YOURS: the engagement's
+#         # token and its id. Both were printed by the installer that generated
+#         # this file. There is no address to configure \u2014 the guard service this
+#         # job talks to ships inside the binary below.
 #         GUARD_SERVICE_TOKEN: \${{ secrets.GUARD_SERVICE_TOKEN }}
 #         GUARD_ENGAGEMENT_ID: \${{ secrets.GUARD_ENGAGEMENT_ID }}
 #       run: node ./.halfcycle/bin/bin.bundle.mjs ci
@@ -810,24 +860,21 @@ function generateCiStanza() {
 `;
 }
 var ENV_EXAMPLE_NAMES = [
-  "GUARD_SERVICE_URL",
+  // The engagement's own secret, under the name the guard runner reads. A CI job
+  // has no per-user credential store, so this is one of the two it must supply.
   "GUARD_SERVICE_TOKEN",
+  // Which engagement this repository is. Per-engagement by construction; the same
+  // CI job supplies it beside the token.
   "GUARD_ENGAGEMENT_ID",
-  "HALFCYCLE_SERVICE_URL",
-  "HALFCYCLE_MCP_URL",
-  "HALFCYCLE_TOKEN",
-  // T-10 — declared because it is now WRITTEN into the credential store, and
-  // `install-guard-config.test.ts`'s INV-004 check requires every written name to
-  // be named here too (`HALFCYCLE_ENGAGEMENT_ID` is the one deliberate exception,
-  // recorded in the spec). Optional at runtime — the runner's own telemetry
-  // emission is fail-open when it is absent — but a name that is written and never
-  // declared is exactly what this generated section exists to prevent.
-  "CONTROL_TELEMETRY_URL"
+  // The same credential under the name every other Halfcycle surface reads. Set in
+  // the environment it takes precedence over the stored credential, which is the
+  // escape hatch for running as a specific identity.
+  "HALFCYCLE_TOKEN"
 ];
 function generateEnvExampleSection() {
   return `
 # ---------------------------------------------------------------------------
-# Halfcycle runner (generated by the Halfcycle installer \u2014 names only, no values)
+# Halfcycle (generated by the Halfcycle installer \u2014 names only, no values)
 # ---------------------------------------------------------------------------
 # YOU DO NOT NEED TO SET ANY OF THESE ON YOUR OWN MACHINE, and there is nowhere in
 # this repository to put them. \`npx halfcycle\` writes this engagement's credential
@@ -835,33 +882,18 @@ function generateEnvExampleSection() {
 # MCP headers helper read it from there. Nothing Halfcycle writes a secret into
 # this tree, so there is no file here to leak, ignore or clean up.
 #
-# These names are declared because they ARE read from the environment in one
-# place: a CI job, which has no browser and no per-user store and supplies them as
-# workflow secrets (see .halfcycle/ci-stanza.yml). HALFCYCLE_TOKEN set in the
-# environment also takes precedence over the stored credential everywhere, which is
-# the escape hatch for running as a specific identity.
-GUARD_SERVICE_URL=<argType:runtime>
+# These three are declared because they ARE read from the environment in one place:
+# a CI job, which has no browser and no per-user store and supplies them as workflow
+# secrets (see .halfcycle/ci-stanza.yml). All three are yours \u2014 a credential and the
+# id of your engagement.
+#
+# THERE IS NO ADDRESS TO CONFIGURE ANYWHERE IN HALFCYCLE. Every service this
+# product talks to has one address, the same for every user, and it ships in the
+# tools you already have: the installer, the guard hook and the CI binary each know
+# where to go. If something tells you to set a Halfcycle URL, it is out of date.
 GUARD_SERVICE_TOKEN=<argType:runtime>
 GUARD_ENGAGEMENT_ID=<argType:runtime>
-# TWO ORIGINS, TWO SERVICES (T-22). HALFCYCLE_SERVICE_URL is the Halfcycle
-# CONTROL plane \u2014 it serves engagement creation and the board's first-visit
-# code. HALFCYCLE_MCP_URL is the method-delivery service, which serves /mcp and
-# nothing else here. The platform reports the second on create, so it is written
-# for you and .mcp.json carries the composed address.
-#
-# NEITHER IS SOMETHING YOU NEED TO SET (T-27). The installer talks to Halfcycle's
-# own control plane by default; HALFCYCLE_SERVICE_URL OVERRIDES that address and
-# exists for a self-hosted or development plane. It is not a prerequisite for
-# \`npx halfcycle\`, and nothing in the product asks you to find its value.
-HALFCYCLE_SERVICE_URL=<argType:runtime>
-HALFCYCLE_MCP_URL=<argType:runtime>
 HALFCYCLE_TOKEN=<argType:runtime>
-# CONTROL_TELEMETRY_URL (T-10) \u2014 the platform reports this on create/join, same as
-# HALFCYCLE_MCP_URL. OPTIONAL: absent, guard-eval telemetry is silently disabled
-# and the guard loop itself is unaffected \u2014 this name is declared only because it
-# is one this installer now writes to the machine-level store, same as every name
-# above it.
-CONTROL_TELEMETRY_URL=<argType:runtime>
 `;
 }
 var MCP_REGISTRATION_REL = ".mcp.json";
@@ -1038,6 +1070,16 @@ function writeBundlePin(targetRepoRoot, version, engagementId, engagementType, w
   const pinPath = join5(targetRepoRoot, ".halfcycle", "bundle.json");
   writeAllowlisted(pinPath, targetRepoRoot, JSON.stringify(pin, null, 2) + "\n", writtenPaths);
 }
+function writeCrewRoster(targetRepoRoot, report) {
+  const doc = {
+    $comment: "GENERATED by the Halfcycle installer \u2014 do not edit by hand. Re-run the installer to pick up a roster change.",
+    crew: CREW_ROSTER
+  };
+  const rendered = `${JSON.stringify(doc, null, 2)}
+`;
+  const crewPath = join5(targetRepoRoot, ".halfcycle", "crew.json");
+  record(report, writeOwned(crewPath, targetRepoRoot, rendered), ".halfcycle/crew.json");
+}
 function readBundlePin(targetRepoRoot) {
   const pinPath = join5(targetRepoRoot, ".halfcycle", "bundle.json");
   if (!existsSync3(pinPath))
@@ -1232,6 +1274,7 @@ async function install(options) {
       break;
   }
   writeBundlePin(targetRepo, manifest.version, engagementId, engagementType, report.writtenPaths);
+  writeCrewRoster(targetRepo, report);
   const scanResult = runBootstrapScan(targetRepo);
   return {
     version: manifest.version,
@@ -1304,7 +1347,7 @@ function planeRefusal(detail) {
     error: typeof candidate.error === "string" ? candidate.error : void 0
   };
 }
-var CONTROL_ORIGIN_HINT = `With nothing configured this CLI talks to ${DEFAULT_CONTROL_ORIGIN}; HALFCYCLE_SERVICE_URL overrides that, and is only for a self-hosted or development plane. Whichever is in use, it must be the CONTROL origin \u2014 the one that serves /engagements and /board/enter-codes. The MCP server runs at a different address, and the platform supplies that one itself; you do not configure it.`;
+var CONTROL_ORIGIN_HINT = `This CLI talks to ${DEFAULT_CONTROL_ORIGIN}; it must be the CONTROL origin \u2014 the one that serves /engagements and /board/enter-codes. The MCP server runs at a different address, and the platform supplies that one itself; you configure neither.`;
 async function createEngagement(baseUrl, name, credential) {
   return requestEngagementValues(`${baseUrl.replace(/\/+$/, "")}/engagements`, name ? { name } : {}, credential, { action: "Create-engagement", nothingHappened: "No engagement was created", route: "POST /engagements" });
 }