halfcycle 0.3.22 → 0.3.23

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcycle",
-  "version": "0.3.22",
+  "version": "0.3.23",
   "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/dist/bin.js

@@ -280,6 +280,23 @@ import { z as z5 } from "zod";
 var crewGroupSchema = z5.enum(["builder", "reviewer", "always-on"]);
 var crewTierSchema = z5.enum(["deep", "standard", "fast"]);
 var CREW_DISCIPLINE_MAX = 64;
+var crewFaceHeadSchema = z5.enum(["sq", "sqr", "rnd", "dome", "hex"]);
+var crewFaceAntennaSchema = z5.enum(["none", "stalk", "twin", "dish"]);
+var crewFaceEyesSchema = z5.enum(["dots", "bars", "visor", "cyclops"]);
+var crewFaceMouthSchema = z5.enum(["line", "grid", "dots", "wave"]);
+var crewFaceSchema = z5.object({
+  // The outline of the head. Members who do the same kind of work share one, so a
+  // team is recognisable before any name is read.
+  head: crewFaceHeadSchema,
+  // What sits on top of the head, if anything.
+  antenna: crewFaceAntennaSchema,
+  // The eyes.
+  eyes: crewFaceEyesSchema,
+  // The mouth.
+  mouth: crewFaceMouthSchema,
+  // Whether this member is drawn with ears.
+  ears: z5.boolean()
+}).strict();
 var crewMemberSchema = z5.object({
   // The agent's name. The same twenty-one on every project, so a name is a
   // vocabulary a returning client already knows.
@@ -291,34 +308,163 @@ var crewMemberSchema = z5.object({
   discipline: z5.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
+  tier: crewTierSchema,
+  // How this member's face is drawn. The same face on every project, so a
+  // returning client recognises a member before reading the name.
+  face: crewFaceSchema
 }).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" },
+  {
+    callsign: "ADA",
+    group: "builder",
+    discipline: "implementation",
+    tier: "deep",
+    face: { head: "sq", antenna: "stalk", eyes: "dots", mouth: "line", ears: false }
+  },
+  {
+    callsign: "OTTO",
+    group: "builder",
+    discipline: "implementation",
+    tier: "deep",
+    face: { head: "sq", antenna: "twin", eyes: "bars", mouth: "grid", ears: true }
+  },
+  {
+    callsign: "MILO",
+    group: "builder",
+    discipline: "implementation",
+    tier: "standard",
+    face: { head: "sqr", antenna: "stalk", eyes: "dots", mouth: "dots", ears: false }
+  },
+  {
+    callsign: "NOVA",
+    group: "builder",
+    discipline: "implementation",
+    tier: "standard",
+    face: { head: "sq", antenna: "dish", eyes: "cyclops", mouth: "line", ears: false }
+  },
+  {
+    callsign: "KAI",
+    group: "builder",
+    discipline: "implementation",
+    tier: "standard",
+    face: { head: "sqr", antenna: "none", eyes: "bars", mouth: "line", ears: true }
+  },
+  {
+    callsign: "HUGO",
+    group: "builder",
+    discipline: "infrastructure",
+    tier: "standard",
+    face: { head: "sq", antenna: "twin", eyes: "dots", mouth: "grid", ears: true }
+  },
+  {
+    callsign: "WREN",
+    group: "builder",
+    discipline: "refactor",
+    tier: "fast",
+    face: { head: "sqr", antenna: "stalk", eyes: "bars", mouth: "wave", ears: false }
+  },
+  {
+    callsign: "PIP",
+    group: "builder",
+    discipline: "refactor",
+    tier: "fast",
+    face: { head: "sqr", antenna: "none", eyes: "dots", mouth: "dots", ears: false }
+  },
   // ── 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" },
+  {
+    callsign: "IRIS",
+    group: "builder",
+    discipline: "feature spec",
+    tier: "deep",
+    face: { head: "dome", antenna: "stalk", eyes: "visor", mouth: "line", ears: false }
+  },
+  {
+    callsign: "JUNO",
+    group: "builder",
+    discipline: "feature spec",
+    tier: "standard",
+    face: { head: "dome", antenna: "none", eyes: "dots", mouth: "wave", ears: false }
+  },
+  {
+    callsign: "LEX",
+    group: "builder",
+    discipline: "context & docs",
+    tier: "fast",
+    face: { head: "dome", antenna: "twin", eyes: "bars", mouth: "dots", ears: false }
+  },
   // ── 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" },
+  {
+    callsign: "VERA",
+    group: "reviewer",
+    discipline: "spec consistency",
+    tier: "deep",
+    face: { head: "rnd", antenna: "stalk", eyes: "visor", mouth: "line", ears: false }
+  },
+  {
+    callsign: "ODIN",
+    group: "reviewer",
+    discipline: "cross-spec audit",
+    tier: "deep",
+    face: { head: "rnd", antenna: "dish", eyes: "cyclops", mouth: "line", ears: false }
+  },
+  {
+    callsign: "CASS",
+    group: "reviewer",
+    discipline: "code review",
+    tier: "deep",
+    face: { head: "rnd", antenna: "none", eyes: "visor", mouth: "grid", ears: true }
+  },
+  {
+    callsign: "THEO",
+    group: "reviewer",
+    discipline: "code review",
+    tier: "standard",
+    face: { head: "rnd", antenna: "twin", eyes: "bars", mouth: "line", ears: false }
+  },
+  {
+    callsign: "ECHO",
+    group: "reviewer",
+    discipline: "test quality",
+    tier: "standard",
+    face: { head: "rnd", antenna: "stalk", eyes: "dots", mouth: "wave", ears: false }
+  },
+  {
+    callsign: "MAVIS",
+    group: "reviewer",
+    discipline: "suites & coverage",
+    tier: "standard",
+    face: { head: "rnd", antenna: "none", eyes: "visor", mouth: "dots", ears: false }
+  },
+  {
+    callsign: "ZARA",
+    group: "reviewer",
+    discipline: "smoke & walk aid",
+    tier: "standard",
+    face: { head: "rnd", antenna: "dish", eyes: "bars", mouth: "wave", ears: false }
+  },
+  {
+    callsign: "NORA",
+    group: "reviewer",
+    discipline: "evidence & provenance",
+    tier: "fast",
+    face: { head: "rnd", antenna: "twin", eyes: "dots", mouth: "line", ears: false }
+  },
   // ── 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" }
+  {
+    callsign: "ARGUS",
+    group: "always-on",
+    discipline: "guard \xB7 every diff",
+    tier: "standard",
+    face: { head: "hex", antenna: "dish", eyes: "visor", mouth: "grid", ears: true }
+  },
+  {
+    callsign: "ATLAS",
+    group: "always-on",
+    discipline: "coordinator",
+    tier: "deep",
+    face: { head: "hex", antenna: "twin", eyes: "cyclops", mouth: "line", ears: true }
+  }
 ];
 var CREW_ROSTER_SIZE = CREW_ROSTER.length;
 var CREW_CALLSIGNS = CREW_ROSTER.map((member) => member.callsign);
@@ -1044,11 +1190,15 @@ function writeCollisionSafe(targetAbsPath, targetRepoRoot, content) {
   writeFileSync4(targetAbsPath, content, "utf-8");
   return "written";
 }
+var INSTALLER_OWNED_DIR = ".halfcycle/";
 function writeOwned(targetAbsPath, targetRepoRoot, content) {
   const rel = relative(targetRepoRoot, targetAbsPath).replace(/\\/g, "/");
   if (!isAllowlisted(rel)) {
     throw new Error(`[bundle install] Write-allowlist violation: attempted to write "${rel}". Only the method surface and scaffolding paths are writable.`);
   }
+  if (!rel.startsWith(INSTALLER_OWNED_DIR)) {
+    throw new Error(`[bundle install] Path-ownership violation: attempted to claim "${rel}" by path. Only ${INSTALLER_OWNED_DIR} is owned outright by this installer; everywhere else a differing file may be a developer's, so ownership must be proved from the file's own contents (writeOwnedGenerated) rather than assumed from where it sits.`);
+  }
   if (existsSync3(targetAbsPath) && readFileSync5(targetAbsPath, "utf-8") === content) {
     return "skipped";
   }
@@ -1056,6 +1206,39 @@ function writeOwned(targetAbsPath, targetRepoRoot, content) {
   writeFileSync4(targetAbsPath, content, "utf-8");
   return "written";
 }
+var GENERATED_HEADER_LINE_INDEX = 1;
+function writeOwnedGenerated(targetAbsPath, targetRepoRoot, content, generatedMarker) {
+  const rel = relative(targetRepoRoot, targetAbsPath).replace(/\\/g, "/");
+  if (!isAllowlisted(rel)) {
+    throw new Error(`[bundle install] Write-allowlist violation: attempted to write "${rel}". Only the method surface and scaffolding paths are writable.`);
+  }
+  let replacedExisting = false;
+  if (existsSync3(targetAbsPath)) {
+    const current = readFileSync5(targetAbsPath, "utf-8");
+    if (current === content)
+      return { outcome: "skipped", replacedExisting: false };
+    const headerLine = current.split("\n")[GENERATED_HEADER_LINE_INDEX] ?? "";
+    if (!headerLine.startsWith(generatedMarker))
+      return { outcome: "collided", replacedExisting: false };
+    replacedExisting = true;
+  }
+  mkdirSync4(dirname2(targetAbsPath), { recursive: true });
+  writeFileSync4(targetAbsPath, content, "utf-8");
+  return { outcome: "written", replacedExisting };
+}
+function recordOwnedGenerated(report, targetAbsPath, targetRepoRoot, content, generatedMarker, rel) {
+  const { outcome, replacedExisting } = writeOwnedGenerated(targetAbsPath, targetRepoRoot, content, generatedMarker);
+  record(report, outcome, rel);
+  if (replacedExisting)
+    report.replacedPaths.push(rel);
+}
+function recordOwned(report, targetAbsPath, targetRepoRoot, content, rel) {
+  const existedBefore = existsSync3(targetAbsPath);
+  const outcome = writeOwned(targetAbsPath, targetRepoRoot, content);
+  record(report, outcome, rel);
+  if (outcome === "written" && existedBefore)
+    report.replacedPaths.push(rel);
+}
 function record(report, outcome, rel) {
   const bucket = {
     written: report.writtenPaths,
@@ -1120,6 +1303,17 @@ function generateSettingsJson() {
           ]
         }
       ],
+      Stop: [
+        {
+          hooks: [
+            {
+              type: "command",
+              command: "bash ./.claude/hooks/guard-runner.sh hook stop",
+              timeout: 60
+            }
+          ]
+        }
+      ],
       SubagentStop: [
         {
           hooks: [
@@ -1130,18 +1324,30 @@ function generateSettingsJson() {
             }
           ]
         }
+      ],
+      SessionEnd: [
+        {
+          hooks: [
+            {
+              type: "command",
+              command: "bash ./.claude/hooks/session-end-marker.sh",
+              timeout: 5
+            }
+          ]
+        }
       ]
     }
   };
   return JSON.stringify(settings, null, 2) + "\n";
 }
 var VENDORED_BIN_REL = ".halfcycle/bin/bin.bundle.mjs";
+var GENERATED_GUARD_RUNNER_HEADER = "# Governance hook wrapper \u2014 generated by";
 function generateGuardRunnerWrapper() {
   return `#!/usr/bin/env bash
-# Governance hook wrapper \u2014 generated by the Halfcycle installer.
+${GENERATED_GUARD_RUNNER_HEADER} the Halfcycle installer.
 #
 # Loads this engagement's credentials so the guard runner has its GUARD_SERVICE_*
-# values when Claude Code fires PostToolUse / SubagentStop, then exec's the
+# values when Claude Code fires PostToolUse / Stop / SubagentStop, then exec's the
 # SELF-CONTAINED binary vendored at ${VENDORED_BIN_REL} \u2014 a path inside this
 # project, so the hook resolves in any checkout of it.
 #
@@ -1173,15 +1379,28 @@ fi
 exec node "$PROJECT_DIR/${VENDORED_BIN_REL}" "$@"
 `;
 }
+var GENERATED_SESSION_START_HEADER = "# Session-start marker \u2014 generated by";
+var SESSION_ID_FROM_HOOK_INPUT_SH = `SESSION_ID="$(printf '%s' "$INPUT" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const j=JSON.parse(s);process.stdout.write(typeof j.session_id==="string"?j.session_id:"")}catch{process.stdout.write("")}})' 2>/dev/null || true)"`;
 function generateSessionStartMarker() {
   return `#!/usr/bin/env bash
-# Session-start marker \u2014 generated by the Halfcycle installer.
-# Writes the current git HEAD SHA to a temp file so SubagentStop can
-# diff against session-start rather than just HEAD at stop time.
+${GENERATED_SESSION_START_HEADER} the Halfcycle installer.
+# Records the git HEAD sha this session starts from, in a file named after this
+# session, so the stop-time check can compare what the session did against where
+# it began instead of only against the latest commit. The session id comes in on
+# stdin with the hook input; without one, the older session-less name is written
+# and the stop-time check compares against the latest commit as it used to.
+INPUT="$(cat 2>/dev/null || true)"
 REPO_ROOT="\${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}"
 if [ -z "$REPO_ROOT" ]; then exit 0; fi
-HASH="$(echo -n "$REPO_ROOT" | shasum -a 256 | cut -c1-12)"
-MARKER_FILE="\${TMPDIR%/}/halfcycle-session-\${HASH}.ref"
+HASH="$(printf '%s' "$REPO_ROOT" | shasum -a 256 | cut -c1-12)"
+${SESSION_ID_FROM_HOOK_INPUT_SH}
+MARKER_DIR="\${TMPDIR:-/tmp}"
+MARKER_DIR="\${MARKER_DIR%/}"    # strip trailing slash (macOS TMPDIR ends in /)
+if [ -n "$SESSION_ID" ]; then
+  MARKER_FILE="\${MARKER_DIR}/halfcycle-session-\${HASH}-\${SESSION_ID}.ref"
+else
+  MARKER_FILE="\${MARKER_DIR}/halfcycle-session-\${HASH}.ref"
+fi
 git -C "$REPO_ROOT" rev-parse HEAD > "$MARKER_FILE" 2>/dev/null || true
 
 # ---------------------------------------------------------------------------
@@ -1244,9 +1463,41 @@ ${engagementResolutionShell()}
 exit 0
 `;
 }
+var GENERATED_SESSION_END_HEADER = "# Session-end marker cleanup \u2014 generated by";
+function generateSessionEndMarker() {
+  return `#!/usr/bin/env bash
+${GENERATED_SESSION_END_HEADER} the Halfcycle installer.
+# Removes this session's marker file (and the evaluation-state file beside it)
+# written at session start. Deletion happens HERE and not at stop time: the stop
+# hook runs at the end of every turn, and deleting the marker there would throw
+# away the session's starting point for every later turn.
+INPUT="$(cat 2>/dev/null || true)"
+
+REPO_ROOT="\${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+if [ -z "$REPO_ROOT" ]; then exit 0; fi
+HASH="$(printf '%s' "$REPO_ROOT" | shasum -a 256 | cut -c1-12)"
+
+# The session id arrives on stdin as part of the hook payload. Empty when absent.
+${SESSION_ID_FROM_HOOK_INPUT_SH}
+
+MARKER_DIR="\${TMPDIR:-/tmp}"
+MARKER_DIR="\${MARKER_DIR%/}"    # strip trailing slash (macOS TMPDIR ends in /)
+
+# Exact names only \u2014 never a wildcard. A pattern would match another session
+# running in this same repository and delete the point it started from.
+rm -f "\${MARKER_DIR}/halfcycle-session-\${HASH}.ref" 2>/dev/null || true
+rm -f "\${MARKER_DIR}/halfcycle-session-\${HASH}.eval" 2>/dev/null || true
+if [ -n "$SESSION_ID" ]; then
+  rm -f "\${MARKER_DIR}/halfcycle-session-\${HASH}-\${SESSION_ID}.ref" 2>/dev/null || true
+  rm -f "\${MARKER_DIR}/halfcycle-session-\${HASH}-\${SESSION_ID}.eval" 2>/dev/null || true
+fi
+exit 0
+`;
+}
+var GENERATED_USER_PROMPT_REMINDER_HEADER = "# UserPromptSubmit house-rule reminder \u2014 generated by";
 function generateUserPromptReminderHook() {
   return `#!/usr/bin/env bash
-# UserPromptSubmit house-rule reminder \u2014 generated by the Halfcycle installer.
+${GENERATED_USER_PROMPT_REMINDER_HEADER} the Halfcycle installer.
 #
 # Injects ONE plain-text sentence into context on every prompt (F-2(c),
 # W8-T-05b) \u2014 the per-turn twin of the house rule W8-T-05a put in the client's
@@ -1344,17 +1595,31 @@ function generateCiStanza() {
 #
 # The job prints the diff base it used and how many files it evaluated, on every
 # run. If that line says 0 files on a commit that changed something, the base is
-# wrong \u2014 set HALFCYCLE_DIFF_BASE in the env block above to name it explicitly
-# (on a GitHub push event, \${{ github.event.before }} is the right value).
+# wrong \u2014 set HALFCYCLE_DIFF_BASE in the env block OF YOUR COPY, beside the two
+# secrets, to name it explicitly (on a GitHub push event, \${{ github.event.before }}
+# is the right value).
+#
+# EDIT YOUR COPY, NOT THIS FILE. This one is regenerated by the installer and your
+# changes to it would be replaced the next time you run \`npx halfcycle\`. It is
+# also inert where it sits: no CI system reads this path. Copy the job above into
+# your own workflow and change it there.
 `;
 }
 var MCP_REGISTRATION_REL = ".mcp.json";
 var MCP_SERVER_KEY = "halfcycle";
 var MCP_HEADERS_HELPER_REL = ".halfcycle/mcp-headers.sh";
 var MCP_HEADERS_HELPER_COMMAND = `/bin/sh -c 'd=$(pwd); while [ ! -f "$d/${MCP_HEADERS_HELPER_REL}" ] && [ "$d" != / ]; do d=$(dirname "$d"); done; [ -f "$d/${MCP_HEADERS_HELPER_REL}" ] || { echo "halfcycle: ${MCP_HEADERS_HELPER_REL} not found at or above $(pwd); re-run npx halfcycle" >&2; exit 1; }; exec /bin/sh "$d/${MCP_HEADERS_HELPER_REL}"'`;
+var GENERATED_MCP_HEADERS_HEADER = "# Halfcycle MCP connection headers \u2014 generated by";
+var OWNED_GENERATED_HEADERS = {
+  ".claude/hooks/guard-runner.sh": GENERATED_GUARD_RUNNER_HEADER,
+  ".claude/hooks/user-prompt-reminder.sh": GENERATED_USER_PROMPT_REMINDER_HEADER,
+  ".claude/hooks/session-end-marker.sh": GENERATED_SESSION_END_HEADER,
+  ".claude/hooks/session-start-marker.sh": GENERATED_SESSION_START_HEADER,
+  ".halfcycle/mcp-headers.sh": GENERATED_MCP_HEADERS_HEADER
+};
 function generateMcpHeadersHelper() {
   return `#!/bin/sh
-# Halfcycle MCP connection headers \u2014 generated by the Halfcycle installer.
+${GENERATED_MCP_HEADERS_HEADER} the Halfcycle installer.
 #
 # Claude Code runs this at MCP connection time, from the session's cwd, and merges
 # its stdout into the connection headers for the "halfcycle" server in .mcp.json.
@@ -1539,7 +1804,7 @@ function writeCrewRoster(targetRepoRoot, report) {
   const rendered = `${JSON.stringify(doc, null, 2)}
 `;
   const crewPath = join5(targetRepoRoot, ".halfcycle", "crew.json");
-  record(report, writeOwned(crewPath, targetRepoRoot, rendered), ".halfcycle/crew.json");
+  recordOwned(report, crewPath, targetRepoRoot, rendered, ".halfcycle/crew.json");
 }
 function readBundlePin(targetRepoRoot) {
   const pinPath = join5(targetRepoRoot, ".halfcycle", "bundle.json");
@@ -1690,7 +1955,8 @@ async function install(options) {
     writtenPaths: [],
     skippedPaths: [],
     mergedPaths: [],
-    collidedPaths: []
+    collidedPaths: [],
+    replacedPaths: []
   };
   copyManifestCommands(manifest, targetRepo, report);
   const capturedDir = join5(targetRepo, "test", "fixtures", "captured");
@@ -1703,7 +1969,7 @@ async function install(options) {
   }
   const vendoredBinSrc = resolveVendoredBinary();
   const vendoredBinDest = join5(targetRepo, ".halfcycle", "bin", "bin.bundle.mjs");
-  record(report, writeOwned(vendoredBinDest, targetRepo, readFileSync5(vendoredBinSrc, "utf-8")), ".halfcycle/bin/bin.bundle.mjs");
+  recordOwned(report, vendoredBinDest, targetRepo, readFileSync5(vendoredBinSrc, "utf-8"), ".halfcycle/bin/bin.bundle.mjs");
   const settingsPath = join5(targetRepo, ".claude", "settings.json");
   const settingsPreexisted = existsSync3(settingsPath);
   const generatedSettings = JSON.parse(generateSettingsJson());
@@ -1715,17 +1981,19 @@ async function install(options) {
   (settingsPreexisted ? report.mergedPaths : report.writtenPaths).push(".claude/settings.json");
   for (const [name, content] of [
     ["guard-runner.sh", generateGuardRunnerWrapper()],
-    ["session-start-marker.sh", generateSessionStartMarker()],
-    ["user-prompt-reminder.sh", generateUserPromptReminderHook()]
+    ["session-end-marker.sh", generateSessionEndMarker()],
+    ["user-prompt-reminder.sh", generateUserPromptReminderHook()],
+    ["session-start-marker.sh", generateSessionStartMarker()]
   ]) {
+    const rel = `.claude/hooks/${name}`;
     const hookPath = join5(targetRepo, ".claude", "hooks", name);
-    record(report, writeCollisionSafe(hookPath, targetRepo, content), `.claude/hooks/${name}`);
+    recordOwnedGenerated(report, hookPath, targetRepo, content, OWNED_GENERATED_HEADERS[rel], rel);
   }
   const ciStanzaPath = join5(targetRepo, ".halfcycle", "ci-stanza.yml");
-  record(report, writeCollisionSafe(ciStanzaPath, targetRepo, generateCiStanza()), ".halfcycle/ci-stanza.yml");
+  recordOwned(report, ciStanzaPath, targetRepo, generateCiStanza(), ".halfcycle/ci-stanza.yml");
   if (credential) {
     const helperPath = join5(targetRepo, MCP_HEADERS_HELPER_REL);
-    record(report, writeCollisionSafe(helperPath, targetRepo, generateMcpHeadersHelper()), MCP_HEADERS_HELPER_REL);
+    recordOwnedGenerated(report, helperPath, targetRepo, generateMcpHeadersHelper(), OWNED_GENERATED_HEADERS[MCP_HEADERS_HELPER_REL], MCP_HEADERS_HELPER_REL);
     const mcpPath = join5(targetRepo, MCP_REGISTRATION_REL);
     const existingMcp = existsSync3(mcpPath) ? readFileSync5(mcpPath, "utf-8") : null;
     const mcpContent = generateMcpRegistration(existingMcp, credential.mcpUrl);
@@ -1779,6 +2047,7 @@ async function install(options) {
     skippedPaths: report.skippedPaths,
     mergedPaths: report.mergedPaths,
     collidedPaths: report.collidedPaths,
+    replacedPaths: report.replacedPaths,
     bootstrapScanRan: scanResult.ran,
     legacyCredentialKept: migration.outcome === "kept" ? { keys: migration.unbacked, missing: migration.missingForAdoption } : null
   };
@@ -4007,6 +4276,12 @@ ${USAGE}`);
       }
       if (result.collidedPaths.length > 0) {
         process.stdout.write(`[halfcycle] Collided (a name you already use \u2014 NOT overwritten): ${result.collidedPaths.join(", ")}
+`);
+      }
+      if (result.replacedPaths.length > 0) {
+        process.stdout.write(`[halfcycle] Updated (files Halfcycle wrote earlier, now replaced): ${result.replacedPaths.join(", ")}
+`);
+        process.stdout.write(`[halfcycle]   If you had changed one of those: a change you had COMMITTED is still in your git history ("git log -p -- <path>"). A change you had not committed is gone \u2014 this command overwrote the file.
 `);
       }
       if (result.legacyCredentialKept !== null) {