@cxi-lmai/ci-agent-platform 3.1.5 → 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.5",
+  "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/`.