@cxi-lmai/ci-agent-platform 3.1.4 → 3.2.0

package/README.md

@@ -170,12 +170,17 @@ Re-run `npx @cxi-lmai/ci-agent-platform` to take a newer release. It records wha
 it installed in `.claude/pipeline-install.json`, including a checksum per file,
 so it can tell a file you edited from one it wrote.
 
-> [!NOTE]
-> Reconciling those checksums is not implemented yet. Until it is, re-running
-> refreshes the source folder and the manifest; treat updating the installed
-> copies under `.claude/` as a manual diff, and keep your own edits in
-> `pipeline-config.md` rather than in agent files, where nothing will reclaim
-> them.
+A re-run reconciles those checksums against the new release and the copies in
+your repository. A file you never touched is brought up to date in place, with
+no prompt. Everything else is left exactly as it is and written to
+`.claude/onboarding-state.md` as a decision list: files you edited that also
+changed upstream, files new in this release, and files the release dropped.
+Open Claude Code and ask it to finish the upgrade; it works through that list
+one file at a time, showing a diff before it touches anything. A file you
+edited that this release does not change is never mentioned at all.
+
+`pipeline-config.md`, `CLAUDE.md`, `docs/` and `.claude/memory/` carry no
+checksum. They are project-owned, and the installer never reclaims them.
 
 To remove the pipeline: delete `.claude/agents/`, `.claude/skills/`,
 `.claude/templates/`, `.claude/pipeline-config.md`,

package/bin/init.mjs

@@ -70,17 +70,104 @@ function sha256(file) {
   return `sha256:${createHash('sha256').update(fs.readFileSync(file)).digest('hex')}`
 }
 
-// Payload-relative paths, sorted, so the manifest is stable across platforms.
+// Payload-relative paths, posix-separated and sorted, so the manifest is
+// stable across platforms.
 function walk(dir, base = dir) {
   return fs
     .readdirSync(dir, { withFileTypes: true })
     .flatMap((e) => {
       const full = path.join(dir, e.name)
-      return e.isDirectory() ? walk(full, base) : [path.relative(base, full)]
+      return e.isDirectory() ? walk(full, base) : [path.relative(base, full).split(path.sep).join('/')]
     })
     .sort()
 }
 
+/**
+ * Where a payload file ends up in the repository, repo-relative, or null when
+ * it is never installed (INSTALL.md, the github/ README) or belongs to the
+ * other platform. This mirrors step 1 of payload/INSTALL.md and is the only
+ * place in bin/ that knows the shape of an installed repository.
+ */
+function destinationOf(rel, plat) {
+  const parts = rel.split('/')
+  const tail = parts.slice(1).join('/')
+  switch (parts[0]) {
+    case 'agents':
+      return `.claude/agents/${tail}`
+    case 'agents-omp':
+      return `.omp/agents/${tail}`
+    case 'skills':
+      return `.claude/skills/${tail}`
+    case 'templates':
+      return `.claude/templates/${tail}`
+    case 'ci-templates':
+      if (parts[1] === 'scripts') return `.claude-pipeline/${tail}`
+      if (parts[1] === 'github') {
+        return plat === 'github' && rel.endsWith('.yml') ? `.github/workflows/${parts[2]}` : null
+      }
+      if (parts.length === 2 && rel.endsWith('.gitlab-ci.yml')) {
+        return plat === 'gitlab' ? `.claude-pipeline/${parts[1]}` : null
+      }
+      return null
+    default:
+      return null
+  }
+}
+
+/**
+ * Reconcile a previous install against this release. Three checksums decide
+ * every file: the one the previous run recorded, the one this release ships,
+ * and the one on disk.
+ *
+ * Only the unambiguous case is acted on: an installed file still byte-identical
+ * to what was recorded is a file nobody edited, so a changed release can
+ * replace it with no prompt. Everything else is reported and left alone,
+ * because deciding it needs judgement about this repository, which belongs to
+ * the init skill and the human.
+ */
+function reconcile(recorded, digests, plat) {
+  const refreshed = []
+  const conflicted = []
+  const added = []
+  const dropped = []
+  let kept = 0
+
+  for (const [rel, shipped] of digests) {
+    const dest = destinationOf(rel, plat)
+    if (!Object.hasOwn(recorded, rel)) {
+      // No previous install recorded this path. Absent on disk it is simply new
+      // upstream; present on disk it is a copy of unknown provenance, which is
+      // only overwritten after someone has looked at the diff.
+      if (!dest) continue
+      if (!fs.existsSync(dest)) added.push(rel)
+      else if (sha256(dest) !== shipped) conflicted.push({ rel, dest })
+      continue
+    }
+    // Not installed: an agent phase 1 skipped, or the other platform's CI file.
+    if (!dest || !fs.existsSync(dest)) continue
+    const onDisk = sha256(dest)
+    if (onDisk === shipped) continue // already current, whatever the record says
+    if (recorded[rel] === shipped) {
+      kept += 1 // locally edited, but this release does not touch the file
+      continue
+    }
+    if (onDisk !== recorded[rel]) {
+      conflicted.push({ rel, dest }) // edited here and changed upstream: the human decides
+      continue
+    }
+    fs.copyFileSync(path.join(PAYLOAD, rel), dest)
+    refreshed.push(dest)
+  }
+
+  for (const rel of Object.keys(recorded)) {
+    if (digests.has(rel)) continue
+    const dest = destinationOf(rel, plat)
+    if (dest && fs.existsSync(dest)) dropped.push(dest)
+  }
+
+  return { refreshed, conflicted, added, dropped, kept }
+}
+
 /**
  * Classify the remote host without ever surfacing the URL. A remote can embed
  * an access token in its userinfo, so the URL is read, matched, and dropped:
@@ -142,6 +229,22 @@ if (fs.existsSync(configPath) && !fs.existsSync(manifestPath) && !FORCE) {
   )
 }
 
+// The checksums a previous run recorded are the only evidence of what the
+// previous release put on disk, so they are read before anything is written.
+// A manifest that is not readable JSON counts as no manifest: this run then
+// records, and never claims to have reconciled anything.
+let prior = null
+if (fs.existsSync(manifestPath)) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+    if (parsed?.payload && typeof parsed.payload === 'object') prior = parsed
+  } catch {
+    say('Note: .claude/pipeline-install.json is unreadable. It is rewritten from scratch,')
+    say('so nothing is reconciled against it this run.')
+    say()
+  }
+}
+
 const platform = detectPlatform()
 let githubOptIn = null
 if (platform === 'github') {
@@ -182,14 +285,72 @@ fs.copyFileSync(payloadInstall, path.join(REPO, installName))
 fs.mkdirSync(path.join(REPO, '.claude'), { recursive: true })
 
 const payloadFiles = walk(PAYLOAD)
+const digests = new Map(payloadFiles.map((rel) => [rel, sha256(path.join(PAYLOAD, rel))]))
+
+// Reconcile before the manifest is rewritten; afterwards the old checksums are
+// gone. Nothing here touches pipeline-config.md, CLAUDE.md, docs/ or
+// .claude/memory/: those are project-owned and init never reclaims them.
+const recon = prior ? reconcile(prior.payload, digests, platform) : null
+
+const installed = {}
+for (const rel of payloadFiles) {
+  const dest = destinationOf(rel, platform)
+  if (dest && fs.existsSync(dest)) installed[rel] = dest
+}
+
 const manifest = {
   package: pkg.name,
   version: pkg.version,
   platform,
-  payload: Object.fromEntries(payloadFiles.map((rel) => [rel, sha256(path.join(PAYLOAD, rel))])),
+  payload: Object.fromEntries(digests),
 }
+if (Object.keys(installed).length > 0) manifest.installed = installed
+// Phase 2 owns the selection record. A re-run must not erase it.
+if (prior?.selected) manifest.selected = prior.selected
 fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
 
+// Reconciliation is only reported once phase 2 has put files in the repository.
+// A second phase-0 run on a repository nobody has installed into has nothing to
+// reconcile, and a report of five zeroes would only read as a warning.
+const reported = recon && Object.keys(installed).length > 0 ? recon : null
+
+// An install that has a config is finished, so a re-run of it is an upgrade.
+// Without one, phase 2 was interrupted: the files are reconciled all the same,
+// and the session still continues the install at phase 1.
+const upgrade = reported !== null && fs.existsSync(configPath)
+
+// What the model has to act on: the cases reconciliation deliberately refused
+// to decide. An empty list is written as nothing at all, so a clean upgrade
+// leaves the state file as short as a first install.
+const unresolved = reported
+  ? reported.conflicted.length + reported.added.length + reported.dropped.length
+  : 0
+
+function stateList(title, entries) {
+  if (entries.length === 0) return ''
+  return `\n${title}\n${entries.map((e) => `- ${e}`).join('\n')}\n`
+}
+
+const reconSection = !reported
+  ? ''
+  : `
+## Reconciliation with the previous install
+
+Refreshed in place, untouched since they were installed: ${reported.refreshed.length}
+Left alone, edited here and unchanged in this release: ${reported.kept}
+${stateList(
+  'Edited here AND changed in this release. Show the diff against the source\n' +
+    'copy and ask, one file at a time. Never overwrite without asking:',
+  reported.conflicted.map((c) => `${c.dest} (source: ${SRC_DIR}/${c.rel})`),
+)}${stateList(
+      'New in this release, not installed here. Install the ones this project\n' +
+        'selects, following step 1 of the install instructions:',
+      reported.added,
+    )}${stateList(
+      'Installed here, no longer part of the payload. Offer removal:',
+      reported.dropped,
+    )}`
+
 fs.writeFileSync(
   path.join(REPO, '.claude', 'onboarding-state.md'),
   `# Onboarding state
@@ -200,13 +361,18 @@ GitHub experimental opt-in: ${githubOptIn === null ? 'not applicable' : githubOp
 Source folder: ${SRC_DIR}/
 Install instructions: ${installName}
 
-Next action: phase 1 of .ci-agent-platform-src/skills/init-pipeline-config/SKILL.md
-(scan the repository, select agents, draft the config).
+Next action: ${
+    upgrade
+      ? `this repository is already installed, so phase 1 is not redone.
+Work through the reconciliation below, one file at a time, and stop there.`
+      : `phase 1 of ${SRC_DIR}/skills/init-pipeline-config/SKILL.md
+(scan the repository, select agents, draft the config).`
+  }
 
 This file is gitignored and is deleted at the end of the install. A session
 resuming an interrupted onboarding reads it first and continues from the phase
 recorded here, following the skill rather than improvising.
-`,
+${reconSection}`,
 )
 
 // --- handoff ---------------------------------------------------------------
@@ -220,6 +386,21 @@ say('             .claude/pipeline-install.json')
 say('             .claude/onboarding-state.md')
 say(`  gitignored ${addedIgnores.length > 0 ? addedIgnores.join(', ') : 'nothing new'}`)
 say(`  platform   ${platform}${platform === 'github' ? ' (experimental)' : ''}`)
+if (reported) {
+  say(`  refreshed  ${reported.refreshed.length} installed file(s) untouched since the last install`)
+  if (reported.kept > 0) {
+    say(`  kept       ${reported.kept} file(s) you edited that this release does not change`)
+  }
+  if (reported.conflicted.length > 0) {
+    say(`  conflicts  ${reported.conflicted.length} file(s) edited here and changed upstream`)
+  }
+  if (reported.added.length > 0) {
+    say(`  new        ${reported.added.length} payload file(s) not installed here`)
+  }
+  if (reported.dropped.length > 0) {
+    say(`  dropped    ${reported.dropped.length} installed file(s) no longer in the payload`)
+  }
+}
 if (installName !== 'INSTALL.md') {
   say()
   say('  Note: this repository already had its own INSTALL.md, which was left')
@@ -229,8 +410,19 @@ if (platform === 'unknown') {
   say()
   say('  Note: no git remote found, so the platform is unknown. Phase 1 asks.')
 }
+if (unresolved > 0) {
+  say()
+  say(`  Note: ${unresolved} file(s) need a decision. They are listed in`)
+  say('  .claude/onboarding-state.md; the session handles them one at a time.')
+  say('  Nothing you edited was overwritten.')
+}
 say()
-say('Next: open Claude Code in this repository and ask it to install the')
-say('pipeline (any phrasing). It reads the instructions and takes it from here.')
+if (upgrade) {
+  say('Next: open Claude Code in this repository and ask it to finish the upgrade.')
+  say('It reads the reconciliation list and handles what is left, one file at a time.')
+} else {
+  say('Next: open Claude Code in this repository and ask it to install the')
+  say('pipeline (any phrasing). It reads the instructions and takes it from here.')
+}
 say()
 say('Nothing has been committed. Nothing has been pushed.')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxi-lmai/ci-agent-platform",
-  "version": "3.1.4",
+  "version": "3.2.0",
   "description": "Autonomous dev pipeline on plain GitLab CI or GitHub Actions, driven by Claude Code. A labeled issue goes in, an open merge request comes out.",
   "keywords": [
     "claude",

package/payload/INSTALL.md

@@ -27,6 +27,29 @@ manifest that the upgrade path depends on is written only by the bootstrapper.
 Then read `.claude/onboarding-state.md`, which records the detected platform
 and the phase reached.
 
+A `## Reconciliation with the previous install` section in that state file
+means the bootstrapper found an earlier install and has already brought every
+file nobody edited up to date. What is left is the list under that heading: it
+exists precisely because each entry needs a decision, and the bootstrapper
+makes none.
+
+- **Edited here and changed in this release.** Show the diff between the
+  installed file and the source copy named on the same line, one file at a
+  time, and ask. The project's version outranks the shipped one.
+- **New in this release.** Install it only if this project's agent selection
+  wants it, under step 1's rules. A new agent the project has no use for is
+  not installed.
+- **No longer part of the payload.** Offer removal; never delete unasked.
+
+The `Next action:` line says what follows. When it reports the repository is
+already installed, this is an upgrade: work that list, skip steps 1 and 2, then
+offer one commit of what changed, message `ci: upgrade ci-agent-platform to
+<version>` with the version read from `.claude/pipeline-install.json`, and
+clean up (`.ci-agent-platform-src/`, the root copy of this file,
+`.claude/onboarding-state.md`) as at the end of a first install. When it points
+at phase 1 instead, an earlier install was interrupted: work the list, then
+continue with step 1 below, which skips what is already in place.
+
 ## Step 1: distribute the files
 
 Let `<src>` be `.ci-agent-platform-src/`.

package/payload/ci-templates/scripts/lib/pipeline-common.sh

@@ -277,10 +277,16 @@ pipe_run_claude() {
   # $3 = allowed tools (optional), $4 = model for the main loop (optional,
   # e.g. $PIPE_MODEL_REVIEW; subagents keep their frontmatter models),
   # stdin = extra prompt (optional, usually empty)
+  #
+  # Always returns 0, so a caller running under `set -e` keeps control over what
+  # a failed agent means for its job. The agent's real exit code lands in
+  # PIPE_AGENT_RC. A caller that must not read a crashed agent as a clean run
+  # checks that variable, or calls pipe_require_agent_ran below.
   local label="$1" skill="$2" tools="${3:-Agent,Read,Write,Edit,Glob,Grep,Bash}" model="${4:-}"
   pipe_require_harness claude
   local stdin_file; stdin_file=$(mktemp)
   cat > "$stdin_file" || true
+  PIPE_AGENT_RC=0
 
   if [ "$(id -u)" -eq 0 ]; then
     local runuser="pipelinebot"
@@ -315,7 +321,7 @@ pipe_run_claude() {
     } > "$runner"
     chmod +x "$runner"
     chown "$runuser:$runuser" "$runner"
-    su -m "$runuser" -s /bin/bash "$runner" || true
+    su -m "$runuser" -s /bin/bash "$runner" || PIPE_AGENT_RC=$?
     chown -R root:root "$PWD" 2>/dev/null || true
     rm -f "$runner"
   else
@@ -327,9 +333,32 @@ pipe_run_claude() {
       else
         capture_claude "$label" -- --dangerously-skip-permissions --allowedTools "$tools" -p "$skill" < "$stdin_file"
       fi
-    ) || true
+    ) || PIPE_AGENT_RC=$?
   fi
   rm -f "$stdin_file"
+  [ "$PIPE_AGENT_RC" -eq 0 ] || pipe_log "agent exited with code $PIPE_AGENT_RC"
+  return 0
+}
+
+pipe_require_agent_ran() {
+  # $1 = file the skill was supposed to write (empty to check the exit code
+  # only, for skills whose marker is legitimately optional), $2 = human label.
+  # Fails the job when the agent crashed or wrote nothing. Without this an
+  # agent that never started is indistinguishable from one that ran and found
+  # nothing: every caller reads its marker file, misses it, and falls back to
+  # the "all clear" default, so the job goes green without a review, fix, or
+  # triage having happened.
+  local marker="$1" what="${2:-agent}"
+  if [ "${PIPE_AGENT_RC:-0}" -ne 0 ]; then
+    pipe_log "ERROR: $what did not complete (exit code $PIPE_AGENT_RC). See the job log above."
+    return 1
+  fi
+  [ -n "$marker" ] || return 0
+  if [ ! -s "$marker" ]; then
+    pipe_log "ERROR: $what produced no output ($marker is missing or empty)."
+    return 1
+  fi
+  return 0
 }
 
 # --- omp invocation -----------------------------------------------------
@@ -418,6 +447,9 @@ pipe_run_omp() {
   # internally), $4 = model for the main loop (optional, e.g.
   # $PIPE_MODEL_REVIEW; subagents keep the models from their own
   # frontmatter), stdin = extra prompt (optional, usually empty).
+  #
+  # Same contract as pipe_run_claude: always returns 0 and reports the agent's
+  # real exit code in PIPE_AGENT_RC, which pipe_require_agent_ran checks.
   local label="$1" skill="$2" tools="${3:-Agent,Read,Write,Edit,Glob,Grep,Bash}" model="${4:-}"
   local omp_tools; omp_tools=$(pipe_translate_tools_to_omp "$tools")
   # Bound the run below the job's own hard kill (see pipe_agent_max_time).
@@ -431,6 +463,7 @@ pipe_run_omp() {
   pipe_require_harness omp
   local stdin_file; stdin_file=$(mktemp)
   cat > "$stdin_file" || true
+  PIPE_AGENT_RC=0
 
   if [ "$(id -u)" -eq 0 ]; then
     local runuser="pipelinebot"
@@ -465,7 +498,7 @@ pipe_run_omp() {
     } > "$runner"
     chmod +x "$runner"
     chown "$runuser:$runuser" "$runner"
-    su -m "$runuser" -s /bin/bash "$runner" || true
+    su -m "$runuser" -s /bin/bash "$runner" || PIPE_AGENT_RC=$?
     chown -R root:root "$PWD" 2>/dev/null || true
     rm -f "$runner"
   else
@@ -477,9 +510,11 @@ pipe_run_omp() {
       else
         capture_omp "$label" -- "${max_time_args[@]}" --yolo --no-session --no-title --tools "$omp_tools" -p "$skill" < "$stdin_file"
       fi
-    ) || true
+    ) || PIPE_AGENT_RC=$?
   fi
   rm -f "$stdin_file"
+  [ "$PIPE_AGENT_RC" -eq 0 ] || pipe_log "agent exited with code $PIPE_AGENT_RC"
+  return 0
 }
 
 # --- Harness dispatch ---------------------------------------------------

package/payload/ci-templates/scripts/review-fix.sh

@@ -41,6 +41,9 @@ echo "$NOTES" | jq -r --arg u "${PIPE_BOT_USER:-}" --arg m "$REVIEW_MARKER" \
 #    verifies, writes the result JSON, and the review-fix.env marker. On cap it
 #    runs the shared postmortem flow (writing postmortem.md + postmortem.env).
 pipe_run_agent coder "/fix-review-findings" "Agent,Read,Write,Edit,Glob,Grep,Bash" "$PIPE_MODEL_CODE" < /dev/null
+# A crashed agent writes no marker, which step 6 would read as "nothing changed"
+# and step 7 would report as a completed fix run that had nothing to do.
+pipe_require_agent_ran "" "The review-fix agent" || exit 1
 
 # 6. Read the marker the skill wrote.
 RF_ENV="$PIPE_CONTEXT_DIR/review-fix.env"

package/payload/ci-templates/scripts/review.sh

@@ -87,7 +87,14 @@ pipe_metric_event code-reviewer review_findings \
       --argjson inc "$([ "${PIPE_IS_INCREMENTAL:-false}" = "true" ] && echo true || echo false)" \
       '{findings_total: $t, status: $s, has_fixable_bugs: $b, is_incremental: $inc}')"
 
-# 7. Gate. review.env is exported so the fix job can read REVIEW_HAS_BUGS at
+# 7. Fail the job when no review was produced. The comment above already told
+#    the humans; this tells the pipeline. PIPE_NO_GATE does not apply: it turns
+#    off the verdict gate, and this is a broken run, not a verdict. Without it a
+#    review that never ran (crashed agent, missing ANTHROPIC_API_KEY) reads as a
+#    review that ran and found nothing, and the MR goes green unreviewed.
+pipe_require_agent_ran "$PIPE_RESULT_REVIEW" "The review agent" || exit 1
+
+# 8. Gate. review.env is exported so the fix job can read REVIEW_HAS_BUGS at
 #    runtime. On GitLab the job exits non-zero to block the pipeline. On GitHub
 #    the workflow step owns the gate (it reads the output first), so it sets
 #    PIPE_NO_GATE=1 and this script leaves the exit to the workflow.

package/payload/ci-templates/scripts/test-fix.sh

@@ -27,6 +27,9 @@ COVERAGE_BEFORE=$(pipe_count_fix_commits "$PIPE_COMMIT_COVERAGE")
 #    test-writer, verifies, and writes fix-tests.env. On cap it runs the shared
 #    postmortem flow (writing postmortem.md + postmortem.env).
 pipe_run_agent test-fix "/fix-tests" "Agent,Read,Write,Edit,Glob,Grep,Bash" "$PIPE_MODEL_CODE" < /dev/null
+# A crashed agent writes no marker, which step 4 would read as FIX_BRANCH=none
+# and report as a false-alarm trigger, hiding the failure behind a green job.
+pipe_require_agent_ran "" "The test-fix agent" || exit 1
 
 # 4. Read the marker the skill wrote.
 FT_ENV="$PIPE_CONTEXT_DIR/fix-tests.env"