@looop-games/cli 0.1.23 → 0.1.24

package/CHANGELOG.md

@@ -14,6 +14,22 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.24] - 2026-08-01
+
+### Changed
+
+- `looop update` now always installs Looop's version of the skill files and
+  the `AGENTS.md` managed block, and removes retired ones — even where they
+  were changed locally. Before, an edited file was kept and silently stopped
+  receiving updates forever; one unnoticed agent edit could freeze a skill
+  out of every future release. Nothing is lost when this happens: the update
+  marks each such file `OVERWROTE`, saves the previous copy in
+  `.looop/backup-<version>/` (git has it too), and the `/update-looop` skill
+  walks you through keeping anything that mattered. Guidance you want kept
+  belongs in `AGENTS.md` below the managed block, where updates never touch
+  it. Repos already stuck with a frozen skill heal themselves on their next
+  update — no action needed.
+
 ## [0.1.23] - 2026-08-01
 
 ### Changed

package/lib/agent-surface.mjs

@@ -23,26 +23,41 @@
 //
 // The one contract everything here serves:
 //
-//     an update reaches a pre-existing repo without touching anything
-//     user-owned.
+//     an update always lands Looop's surface, and never loses the
+//     creator's content — anything it replaces or removes is backed up
+//     and reported.
 //
-// So ownership is tracked explicitly, in `.looop/agent-surface.json` — the
-// hash of every file WE wrote. On each run a file is one of:
+// Ownership is by PATH (note hx3kd9): a path the artifact ships belongs to the
+// platform and always converges to the artifact's version. On each run a file at
+// a shipped path is one of:
 //
-//   ours, unmodified  (hash matches what we recorded)  → replace with the new
-//   ours, edited      (hash differs)                   → KEEP theirs, warn
-//   never ours        (no record, but on disk)         → KEEP theirs, warn
-//   not on disk                                        → place ours
-//   retired upstream                                   → remove, if still ours
+//   content already equal to the incoming  → heal the record, silently
+//   ours, unmodified (hash == recorded)    → replace with the new
+//   anything else on disk                  → back it up, replace, report lossy
+//   not on disk                            → place ours
+//   retired upstream / orphaned            → remove (backup + lossy when the
+//                                            content didn't match the record)
 //
-// A skill we never placed is never even enumerated, so a creator's own skills
-// are invisible to this code by construction. `AGENTS.md` is the exception that
-// proves the rule: the managed block between the markers is ours to rewrite;
-// everything outside them (their title, their instructions below the end
-// marker) is theirs and is spliced back untouched.
+// There is deliberately no keep-theirs outcome. The old model kept edited
+// files and "shadowed" the incoming version — which permanently froze a file
+// out of every future update after a single (usually agent-made, usually
+// unnoticed) edit, breaking the harness for that repo silently (fb_3a0bea).
+// The hash record in `.looop/agent-surface.json` is therefore not an ownership
+// gate anymore: it is a change DETECTOR, kept so the report can say "this had
+// local content" honestly instead of warning on every write. `lossy` is that
+// report; `looop update` narrates it and the /update-looop skill asks the
+// creator what to do with each lost edit.
+//
+// A skill we never ship is never even enumerated, so a creator's own skills
+// are invisible to this code by construction. `AGENTS.md` is the sanctioned
+// home for creator additions: the managed block between the markers is ours to
+// rewrite; everything outside them (their title, their instructions below the
+// end marker) is theirs and is spliced back untouched — and when the markers
+// themselves have been deleted, the block is re-appended below their content
+// rather than contesting any of it.
 import { createHash } from 'node:crypto';
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
 
 export const SURFACE_DIR = 'agent-surface';
 export const LOCAL_MANIFEST = '.looop/agent-surface.json';
@@ -100,9 +115,27 @@ function pruneEmptyDirs(projectDir, dest) {
   }
 }
 
+// Whether everything on disk at `dest` (a file, or a whole skill folder) still
+// matches the hashes recorded for it. Distinguishes a clean retire/orphan
+// removal from one that destroys real local content — only the latter earns a
+// backup and a `lossy` report. A file with no record at all counts as
+// non-matching: content we can't vouch for is content to preserve.
+function contentMatchesRecord(abs, dest, placed) {
+  if (!statSync(abs).isDirectory()) {
+    return placed[dest] !== undefined && sha(readFileSync(abs)) === placed[dest];
+  }
+  const entries = readdirSync(abs, { recursive: true, withFileTypes: true }).filter((e) => e.isFile());
+  if (!entries.length) return true; // an empty folder holds nothing to lose
+  return entries.every((e) => {
+    const file = join(e.parentPath, e.name);
+    const rel = join(dest, relative(abs, file));
+    return placed[rel] !== undefined && sha(readFileSync(file)) === placed[rel];
+  });
+}
+
 // Splice the artifact's managed block into the repo's AGENTS.md, preserving
 // everything outside the markers. Returns null when the creator's file has no
-// markers — they rewrote Layer 0 themselves, so it is theirs now.
+// markers; the caller then re-appends the block below their content.
 function spliceManaged(current, incoming) {
   const cs = current.indexOf(START);
   const ce = current.indexOf(END);
@@ -122,7 +155,7 @@ function spliceManaged(current, incoming) {
  */
 export function reconcileAgentSurface(projectDir, engineDir, { log = console.log } = {}) {
   const result = {
-    placed: [], removed: [], shadowed: [], backups: [],
+    placed: [], removed: [], lossy: [], backups: [],
     adopted: false, skipped: false, engineVersion: null, backupDir: null,
   };
   const surface = join(engineDir, SURFACE_DIR);
@@ -166,19 +199,22 @@ export function reconcileAgentSurface(projectDir, engineDir, { log = console.log
 
     // ── retired entries: remove what upstream dropped. This is the half that
     //    makes a RENAME possible on a repo that already exists — without it a
-    //    replaced skill would linger next to its replacement forever. ─────────
+    //    replaced skill would linger next to its replacement forever, still
+    //    loaded by the creator's agent as live guidance. Removal is
+    //    unconditional (the path is Looop's); content that doesn't match
+    //    the record is preserved in the backup and reported lossy. ───────────
     for (const rel of manifest.retired ?? []) {
       const dest = target(rel);
       if (!dest) continue;
       const abs = join(projectDir, dest);
       if (!existsSync(abs)) continue;
 
-      const owned = Object.keys(placed).some((p) => p === dest || p.startsWith(`${dest}/`));
-      if (!owned && !adopt) {
-        result.shadowed.push(dest);
-        continue;
+      if (adopt) {
+        backup(dest); // no record to compare — preserve, but don't accuse
+      } else if (!contentMatchesRecord(abs, dest, placed)) {
+        backup(dest);
+        result.lossy.push(dest);
       }
-      if (adopt) backup(dest);
       rmSync(abs, { recursive: true, force: true });
       for (const p of Object.keys(placed)) {
         if (p === dest || p.startsWith(`${dest}/`)) delete placed[p];
@@ -201,12 +237,16 @@ export function reconcileAgentSurface(projectDir, engineDir, { log = console.log
 
       if (dest === 'AGENTS.md') {
         // The markers ARE the contract: inside is ours, outside is theirs.
-        const next = exists
-          ? spliceManaged(current.toString('utf8'), desired.toString('utf8'))
-          : desired.toString('utf8');
+        const desiredStr = desired.toString('utf8');
+        let next = exists ? spliceManaged(current.toString('utf8'), desiredStr) : desiredStr;
         if (next === null) {
-          result.shadowed.push(dest);
-          continue;
+          // Their file has no markers — they (or their agent) rewrote Layer 0.
+          // The block must still land, but everything they wrote is theirs, so
+          // it is re-appended below their content, touching none of it.
+          const is = desiredStr.indexOf(START);
+          const ie = desiredStr.indexOf(END);
+          if (is === -1 || ie === -1) continue; // artifact itself has no block — nothing to land
+          next = current.toString('utf8').replace(/\s*$/, '\n\n') + desiredStr.slice(is, ie + END.length) + '\n';
         }
         if (exists && current.toString('utf8') === next) continue;
         writeFileSync(abs, next);
@@ -217,16 +257,21 @@ export function reconcileAgentSurface(projectDir, engineDir, { log = console.log
 
       if (exists) {
         const now = sha(current);
-        if (now === recorded) {
-          if (now === sha(desired)) continue; // already current
-        } else if (recorded === undefined && adopt) {
-          if (now !== sha(desired)) backup(dest);
-        } else {
-          // Either they edited ours, or it was never ours. Both are theirs.
-          result.shadowed.push(dest);
-          placed[dest] = recorded ?? now;
+        if (now === sha(desired)) {
+          // Content already equal — including the frozen-record case where a
+          // local edit was independently upstreamed (fb_3a0bea). Nothing to
+          // write, nothing lost; heal the record so future updates apply.
+          placed[dest] = now;
           continue;
         }
+        if (adopt) {
+          backup(dest); // no record to compare — preserve, but don't accuse
+        } else if (now !== recorded) {
+          // Edited ours, or never ours — either way real local content is
+          // about to be replaced: preserve it and report it for the ask flow.
+          backup(dest);
+          result.lossy.push(dest);
+        }
       }
 
       mkdirSync(dirname(abs), { recursive: true });
@@ -251,8 +296,10 @@ export function reconcileAgentSurface(projectDir, engineDir, { log = console.log
       const abs = join(projectDir, dest);
       if (existsSync(abs)) {
         if (sha(readFileSync(abs)) !== placed[dest]) {
-          result.shadowed.push(dest); // they changed it — it's theirs now
-          continue;
+          // They changed it — the retirement still lands, the content survives
+          // in the backup and the caller asks the creator about it.
+          backup(dest);
+          result.lossy.push(dest);
         }
         rmSync(abs, { force: true });
         pruneEmptyDirs(projectDir, dest);

package/lib/update.mjs

@@ -22,19 +22,39 @@ import { fetchStatus, landedIn } from './feedback-sync.mjs';
 // The report is the point. A creator reading this must be able to answer, with
 // no further digging: what changed, was any of it mine, and what do I do now.
 function report(log, engineVersion, surface) {
-  const { placed = [], removed = [], shadowed = [], backups = [], backupDir } = surface;
-  if (!placed.length && !removed.length && !shadowed.length) {
+  const { placed = [], removed = [], lossy = [], backups = [], backupDir, adopted } = surface;
+  if (!placed.length && !removed.length && !lossy.length) {
     log('   Your skills and instructions were already current.');
     return;
   }
 
   log('');
   log(`Looop also updated this game's skills and instructions to match engine ${engineVersion}:`);
-  for (const f of placed) log(`   updated     ${f}`);
-  for (const f of removed) log(`   removed     ${f}   (retired by Looop)`);
-  for (const f of shadowed) log(`   KEPT YOURS  ${f}   (you changed it — we left it alone)`);
+  for (const f of placed) {
+    if (lossy.includes(f)) log(`   OVERWROTE   ${f}   (it had local changes — see below)`);
+    else log(`   updated     ${f}`);
+  }
+  for (const f of removed) {
+    if (lossy.includes(f)) log(`   removed     ${f}   (retired by Looop — it had local changes, see below)`);
+    else log(`   removed     ${f}   (retired by Looop)`);
+  }
+  for (const f of lossy) {
+    if (!placed.includes(f) && !removed.includes(f)) log(`   OVERWROTE   ${f}   (it had local changes — see below)`);
+  }
+
+  if (lossy.length) {
+    // The overwrite is the contract (Looop's files always land — a kept edit
+    // used to freeze the file out of every future update), but the content is
+    // never gone: name both recovery routes and the one place local guidance
+    // is safe from updates.
+    log('');
+    log('   Files marked OVERWROTE had local changes that Looop replaced. Nothing is');
+    log(`   lost: recover them with \`git diff\`${backupDir ? `, or from ${backupDir}` : ''}.`);
+    log('   Guidance you want to keep belongs in AGENTS.md, below the managed block —');
+    log('   updates never touch anything there.');
+  }
 
-  if (backups.length) {
+  if (adopted && backups.length) {
     // On adoption we cannot tell an untouched old platform file from one the
     // creator edited — there is no ownership record to compare against, which
     // is precisely why we're adopting. Most of these are just the previous

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looop-games/cli",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",