litgrok-ai 0.2.6 → 0.2.7

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.7 (pending) — 2026-09-02
+
+- Repair payload upgrades across the ownership-manifest transition: installs now
+  record a schema-checked `.grok/.litgrok-install-manifest.json` of SHA-256
+  payload hashes, classify files matching recorded hashes as installer-owned,
+  and atomically replace owned files during upgrades. Uninstall removes owned
+  files and the manifest only after payload removal succeeds.
+- Migrate a pristine manifest-free 0.2.5 payload through the bundled seven-file
+  legacy hash snapshot, while malformed manifests and modified or unrecognized
+  files still fail closed before payload writes.
+- Add regression coverage for historical migration, legacy user edits,
+  malformed ownership metadata, and manifest cleanup; enable full-history CI
+  checkout for the historical archive fixture and document the ownership
+  behavior in both READMEs.
+
 ## 0.2.6 (pending) — 2026-09-02
 
 - Harden inode-reuse handling across skill-loop state locks and the

package/README.md

@@ -22,7 +22,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litgrok--ai-cb3837" alt="npm: litgrok-ai" />
-  <img src="https://img.shields.io/badge/version-0.2.6-2ea44f" alt="version 0.2.6" />
+  <img src="https://img.shields.io/badge/version-0.2.7-2ea44f" alt="version 0.2.7" />
   <img src="https://img.shields.io/badge/Grok%20Build-skills%20%2B%20rules-111827" alt="Grok Build skills and project rules" />
   <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" />
 </p>
@@ -105,7 +105,7 @@ npx --yes litgrok-ai@latest install
 Pin a version when you need a reproducible install:
 
 ```bash
-npx --yes litgrok-ai@0.2.6 install
+npx --yes litgrok-ai@0.2.7 install
 ```
 
 Preview without writing files:
@@ -120,7 +120,7 @@ Default install writes the whole payload into the current project's `.grok/` tre
 npx --yes litgrok-ai@latest install --user
 ```
 
-`--user` targets `~/.grok/skills`, `~/.grok/rules`, and `~/.grok/hooks`. Dry-run, `NO_COLOR`, and non-interactive runs do not mutate files. Reinstall is idempotent for byte-identical payload files. A different file occupying any packaged path refuses the whole install rather than being overwritten.
+`--user` targets `~/.grok/skills`, `~/.grok/rules`, and `~/.grok/hooks`. Dry-run, `NO_COLOR`, and non-interactive runs do not mutate files. The installer records SHA-256 ownership in `.grok/.litgrok-install-manifest.json`: byte-identical files stay untouched, and files matching a previously recorded payload hash may be replaced during an upgrade. A user-modified or otherwise unrecognized file refuses the whole install rather than being overwritten. A pristine pre-manifest 0.2.5 payload is recognized through the bundled migration snapshot while no manifest exists and receives a new manifest after the upgrade.
 
 ### Install output
 
@@ -146,7 +146,7 @@ npx --yes litgrok-ai@latest uninstall
 npx --yes litgrok-ai@latest uninstall --user
 ```
 
-If any installed payload file was changed, uninstall refuses the whole removal. Reinstall by running the matching `install` command again; byte-identical files are left untouched.
+If any installed payload file was changed, uninstall refuses the whole removal. Files recorded as installer-owned are removed too, and the ownership manifest is removed only after the payload removal succeeds. Reinstall by running the matching `install` command again; byte-identical files are left untouched.
 
 ## First use
 
@@ -198,12 +198,12 @@ Review is proposal-only. `autoApply` is always false, transcript text is inert d
 From an installed project, use the package CLI directly when you want a replayable foreground command:
 
 ```bash
-npx --yes litgrok-ai@0.2.6 skill-loop review <session-id>
-npx --yes litgrok-ai@0.2.6 skill-loop list
-npx --yes litgrok-ai@0.2.6 skill-loop apply <proposal-id>
-npx --yes litgrok-ai@0.2.6 skill-loop reject <proposal-id>
-npx --yes litgrok-ai@0.2.6 skill-loop rollback <ledger-id>
-npx --yes litgrok-ai@0.2.6 skill-loop curator
+npx --yes litgrok-ai@0.2.7 skill-loop review <session-id>
+npx --yes litgrok-ai@0.2.7 skill-loop list
+npx --yes litgrok-ai@0.2.7 skill-loop apply <proposal-id>
+npx --yes litgrok-ai@0.2.7 skill-loop reject <proposal-id>
+npx --yes litgrok-ai@0.2.7 skill-loop rollback <ledger-id>
+npx --yes litgrok-ai@0.2.7 skill-loop curator
 ```
 
 `apply` prints the ledger id needed for rollback. The deterministic curator is also user-invoked: by default it runs at most once every seven days, requires at least two idle hours, marks eligible unpinned agent-owned skills stale after 30 idle days, and archives them outside discovery after 90 idle days. It makes a full backup before a transition and never deletes a skill package; `--force` bypasses only the seven-day run interval for an explicit test or maintenance invocation.

package/README_ko-KR.md

@@ -22,7 +22,7 @@
 </p>
 <p align="center">
   <img src="https://img.shields.io/badge/npm-litgrok--ai-cb3837" alt="npm: litgrok-ai" />
-  <img src="https://img.shields.io/badge/version-0.2.6-2ea44f" alt="version 0.2.6" />
+  <img src="https://img.shields.io/badge/version-0.2.7-2ea44f" alt="version 0.2.7" />
   <img src="https://img.shields.io/badge/Grok%20Build-skills%20%2B%20rules-111827" alt="Grok Build skills and project rules" />
   <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" />
 </p>
@@ -105,7 +105,7 @@ npx --yes litgrok-ai@latest install
 재현 가능한 설치는 버전을 고정합니다.
 
 ```bash
-npx --yes litgrok-ai@0.2.6 install
+npx --yes litgrok-ai@0.2.7 install
 ```
 
 파일을 쓰지 않고 미리보기:
@@ -120,7 +120,7 @@ npx --yes litgrok-ai@latest install --dry-run
 npx --yes litgrok-ai@latest install --user
 ```
 
-`--user`는 `~/.grok/skills`, `~/.grok/rules`, `~/.grok/hooks`를 대상으로 합니다. dry-run, `NO_COLOR`, non-interactive는 파일을 바꾸지 않습니다. byte가 같은 payload 재설치는 멱등입니다. package path 하나라도 다른 파일이 차지하면 전체 설치를 거절하고 덮어쓰지 않습니다.
+`--user`는 `~/.grok/skills`, `~/.grok/rules`, `~/.grok/hooks`를 대상으로 합니다. dry-run, `NO_COLOR`, non-interactive는 파일을 바꾸지 않습니다. installer는 `.grok/.litgrok-install-manifest.json`에 SHA-256 소유권을 기록합니다. byte가 같은 파일은 다시 쓰지 않고, 이전 payload hash와 일치하는 installer 소유 파일은 업그레이드에서 교체할 수 있습니다. 사용자가 바꿨거나 소유권을 확인할 수 없는 파일이 있으면 전체 설치를 거절하고 덮어쓰지 않습니다. manifest가 없을 때 0.2.5의 pristine payload는 내장 migration snapshot으로 인식하며 업그레이드 뒤 새 manifest를 기록합니다.
 
 ### 설치 출력
 
@@ -146,7 +146,7 @@ npx --yes litgrok-ai@latest uninstall
 npx --yes litgrok-ai@latest uninstall --user
 ```
 
-설치된 payload 파일 하나라도 바뀌었다면 uninstall은 전체 삭제를 거절합니다. 재설치는 같은 `install` 명령을 다시 실행합니다. byte가 같은 파일은 다시 쓰지 않습니다.
+설치된 payload 파일 하나라도 바뀌었다면 uninstall은 전체 삭제를 거절합니다. installer 소유로 기록된 파일도 삭제하며, payload 삭제가 성공한 뒤에만 ownership manifest를 삭제합니다. 재설치는 같은 `install` 명령을 다시 실행합니다. byte가 같은 파일은 다시 쓰지 않습니다.
 
 ## 처음 사용하기
 
@@ -198,12 +198,12 @@ Review는 proposal만 만듭니다. `autoApply`는 항상 false이고 transcript
 설치된 project에서는 다음 package CLI를 foreground command로 실행할 수 있습니다.
 
 ```bash
-npx --yes litgrok-ai@0.2.6 skill-loop review <session-id>
-npx --yes litgrok-ai@0.2.6 skill-loop list
-npx --yes litgrok-ai@0.2.6 skill-loop apply <proposal-id>
-npx --yes litgrok-ai@0.2.6 skill-loop reject <proposal-id>
-npx --yes litgrok-ai@0.2.6 skill-loop rollback <ledger-id>
-npx --yes litgrok-ai@0.2.6 skill-loop curator
+npx --yes litgrok-ai@0.2.7 skill-loop review <session-id>
+npx --yes litgrok-ai@0.2.7 skill-loop list
+npx --yes litgrok-ai@0.2.7 skill-loop apply <proposal-id>
+npx --yes litgrok-ai@0.2.7 skill-loop reject <proposal-id>
+npx --yes litgrok-ai@0.2.7 skill-loop rollback <ledger-id>
+npx --yes litgrok-ai@0.2.7 skill-loop curator
 ```
 
 `apply`는 rollback에 필요한 ledger id를 출력합니다. Deterministic curator도 user-invoked입니다. 기본적으로 7일에 한 번만 실행되고, 마지막 activity 뒤 최소 2시간이 지나야 하며, pin되지 않은 agent-owned skill을 30일 idle 뒤 stale로 표시하고 90일 idle 뒤 discovery 밖으로 archive합니다. Transition 전에는 전체 backup을 만들고 skill package를 삭제하지 않습니다. `--force`는 명시적인 test 또는 maintenance 실행에서 7일 interval만 건너뜁니다.

package/bin/litgrok.mjs

@@ -1,12 +1,30 @@
 #!/usr/bin/env node
 
-import { constants, copyFileSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, unlinkSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, copyFileSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, relative, resolve, sep } from 'node:path';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const PAYLOAD_ROOT = join(PACKAGE_ROOT, '.grok');
+const INSTALL_MANIFEST_NAME = '.litgrok-install-manifest.json';
+const INSTALL_MANIFEST_SCHEMA = 'litgrok.install-manifest/v1';
+const PACKAGE_NAME = 'litgrok-ai';
+
+// 0.2.5 was the last release before ownership manifests existed. These are the
+// only payload hashes changed by the current security release, so a pristine
+// 0.2.5 install can migrate while no manifest exists without treating its
+// seven security-fix files as user conflicts.
+const PRE_MANIFEST_PAYLOAD_HASHES = Object.freeze({
+  'skills/autoconference/references/_canonical-corpus/manifest.json': '4554ee4041b73577a844abc27a97db91e941b8412f1888209203251dc1fee500',
+  'skills/autoconference/scripts/init_conference.py': 'cb83623c1338b7e3a5be7a7beac7a17b8ae362fc24fbc01d1caff634db290dfc',
+  'skills/autoconference/scripts/verify-canonical-corpus.mjs': '4a4afb7dc0b58519a4c521c987cb8998495afc09b89fb87cafb0f1db0047c28d',
+  'skills/autoresearch/references/_canonical-corpus/manifest.json': '9667f852081d4877c579d14e63c0759ebbe863e4170a9c3d5e6487cdb1f0c323',
+  'skills/autoresearch/scripts/init_research.py': 'a5434711928eb4d0487d933df5e1b374f8553140004c6ab8e38fe577ae074d05',
+  'skills/autoresearch/scripts/verify-canonical-corpus.mjs': '80a85ed4ba0c168bd7f7abef5754c4089a629975a827b6ddb3f01cd813602274',
+  'skills/skill-observer/scripts/skill-loop.mjs': '3f3f5265928c0d71175b0f23f71b836d1dc05e7efba407bfdc2d263c6aaed0ce',
+});
 const USAGE = 'Usage: litgrok [install|uninstall] [--user|--project] [--dry-run] [--no-color] [--yes]\n       litgrok skill-loop <review|propose|list|apply|reject|rollback|curator> ...\n';
 const BRAILLE_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 const SPINNER_INTERVAL_MS = 80;
@@ -235,17 +253,160 @@ function reportFailure(error, { stderr, stdout, options, root, colors, step }) {
   stdout.write(failureCard(options, root, colors, error?.step ?? step, errorText(error)));
 }
 
-function targetState(source, target) {
+function normalizedRelativePath(relativePath) {
+  return relativePath.split(sep).join('/');
+}
+
+function sha256File(filePath) {
+  return createHash('sha256').update(readFileSync(filePath)).digest('hex');
+}
+
+function ownershipManifestFailure(reason) {
+  const message = `Refusing to use ${INSTALL_MANIFEST_NAME}: ${reason}`;
+  const error = new Error(message);
+  error.step = 'OWNERSHIP';
+  error.stderrLines = [message];
+  return error;
+}
+
+function ownershipManifestPath(root) {
+  return join(root, INSTALL_MANIFEST_NAME);
+}
+
+function readOwnershipManifest(root) {
+  const target = ownershipManifestPath(root);
+  let stat;
+  try {
+    stat = lstatSync(target);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isFile()) throw ownershipManifestFailure('path is not a regular file');
+
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(target, 'utf8'));
+  } catch {
+    throw ownershipManifestFailure('file is not valid JSON');
+  }
+  if (
+    !parsed ||
+    parsed.schema !== INSTALL_MANIFEST_SCHEMA ||
+    parsed.package !== PACKAGE_NAME ||
+    typeof parsed.version !== 'string' ||
+    parsed.version.length === 0 ||
+    !parsed.files ||
+    Array.isArray(parsed.files) ||
+    typeof parsed.files !== 'object'
+  ) {
+    throw ownershipManifestFailure('schema is invalid');
+  }
+
+  const hashes = new Map();
+  for (const [relativePath, hash] of Object.entries(parsed.files)) {
+    const segments = relativePath.split('/');
+    if (
+      relativePath.length === 0 ||
+      relativePath.startsWith('/') ||
+      relativePath.includes('\\') ||
+      segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')
+    ) {
+      throw ownershipManifestFailure(`path is invalid: ${relativePath}`);
+    }
+    if (typeof hash !== 'string' || !/^[0-9a-f]{64}$/u.test(hash)) {
+      throw ownershipManifestFailure(`hash is invalid: ${relativePath}`);
+    }
+    hashes.set(relativePath, hash);
+  }
+  return { path: target, hashes };
+}
+
+function targetState(source, target, relativePath, manifest) {
   try {
     const targetStat = lstatSync(target);
     if (!targetStat.isFile()) return 'conflict';
-    return readFileSync(source).equals(readFileSync(target)) ? 'current' : 'conflict';
+    const targetHash = sha256File(target);
+    if (targetHash === sha256File(source)) return 'current';
+    const previousHash = manifest?.hashes.get(normalizedRelativePath(relativePath)) ??
+      (manifest === null ? PRE_MANIFEST_PAYLOAD_HASHES[normalizedRelativePath(relativePath)] : undefined);
+    return targetHash === previousHash ? 'owned' : 'conflict';
   } catch (error) {
     if (error?.code === 'ENOENT') return 'missing';
     throw error;
   }
 }
 
+function manifestContent(files) {
+  const hashes = Object.fromEntries(
+    files
+      .map(({ relativePath, source }) => [normalizedRelativePath(relativePath), sha256File(source)])
+      .sort(([left], [right]) => left.localeCompare(right)),
+  );
+  return `${JSON.stringify({
+    schema: INSTALL_MANIFEST_SCHEMA,
+    package: PACKAGE_NAME,
+    version: packageVersion(),
+    files: hashes,
+  }, null, 2)}\n`;
+}
+
+function writeOwnershipManifest(root, files, previousManifest) {
+  const target = ownershipManifestPath(root);
+  const content = manifestContent(files);
+  let existing;
+  try {
+    const stat = lstatSync(target);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw ownershipManifestFailure('path is not a regular file');
+    existing = readFileSync(target, 'utf8');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  if (existing === content) return false;
+  if (previousManifest === null && existing !== undefined) {
+    throw ownershipManifestFailure('path appeared during installation');
+  }
+
+  const temporary = join(root, `.${basename(target)}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, content, { flag: 'wx', mode: 0o600 });
+    renameSync(temporary, target);
+  } finally {
+    try {
+      unlinkSync(temporary);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+  return true;
+}
+
+function replaceOwnedFile(source, target) {
+  const temporary = join(dirname(target), `.${basename(target)}.${randomUUID()}.tmp`);
+  try {
+    copyFileSync(source, temporary, constants.COPYFILE_EXCL);
+    renameSync(temporary, target);
+  } finally {
+    try {
+      unlinkSync(temporary);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+function removeOwnershipManifest(root, previousManifest) {
+  if (previousManifest === null) return;
+  const target = ownershipManifestPath(root);
+  try {
+    const stat = lstatSync(target);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw ownershipManifestFailure('path is not a regular file');
+    unlinkSync(target);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
 function discoverPayloadFiles(root = PAYLOAD_ROOT) {
   const files = [];
 
@@ -383,10 +544,12 @@ export async function run(args, context = {}) {
 
     step = 'OWNERSHIP';
     const states = runStep(progress, 'OWNERSHIP', () => {
-      const owned = files.map(({ source, target }) => targetState(source, target));
+      const manifest = readOwnershipManifest(root);
+      const owned = files.map(({ relativePath, source, target }) => targetState(source, target, relativePath, manifest));
       const counts = {
         missing: owned.filter((state) => state === 'missing').length,
         current: owned.filter((state) => state === 'current').length,
+        owned: owned.filter((state) => state === 'owned').length,
         conflicts: owned.filter((state) => state === 'conflict').length,
       };
       if (counts.conflicts > 0) {
@@ -394,14 +557,14 @@ export async function run(args, context = {}) {
         for (let index = 0; index < files.length; index += 1) {
           if (owned[index] === 'conflict') stderrLines.push(`Refusing to ${options.command === 'install' ? 'overwrite' : 'remove'} different existing file: ${files[index].target}`);
         }
-        const error = new Error(`${counts.missing} missing · ${counts.current} already-current · ${counts.conflicts} conflicts`);
+        const error = new Error(`${counts.missing} missing · ${counts.current} already-current · ${counts.owned} owned · ${counts.conflicts} conflicts`);
         error.step = 'OWNERSHIP';
         error.stderrLines = stderrLines;
         throw error;
       }
       return {
-        value: { states: owned, counts },
-        detail: `${counts.missing} missing · ${counts.current} already-current · ${counts.conflicts} conflicts`,
+        value: { states: owned, counts, manifest },
+        detail: `${counts.missing} missing · ${counts.current} already-current · ${counts.owned} owned · ${counts.conflicts} conflicts`,
       };
     });
 
@@ -410,12 +573,19 @@ export async function run(args, context = {}) {
       const writeStarted = process.hrtime.bigint();
       progress.start('WRITE');
       let removed = 0;
-      for (let index = 0; index < files.length; index += 1) {
-        if (states.states[index] !== 'current') continue;
-        unlinkSync(files[index].target);
-        removed += 1;
+      try {
+        for (let index = 0; index < files.length; index += 1) {
+          if (!['current', 'owned'].includes(states.states[index])) continue;
+          unlinkSync(files[index].target);
+          removed += 1;
+        }
+        removeOwnershipManifest(root, states.manifest);
+        progress.finish('ok', 'WRITE', `${removed} removed · ${states.counts.missing} already absent`, elapsedSince(writeStarted));
+      } catch (error) {
+        progress.finish('failed', 'WRITE', errorText(error), elapsedSince(writeStarted));
+        if (error && typeof error === 'object') error.step = 'WRITE';
+        throw error;
       }
-      progress.finish('ok', 'WRITE', `${removed} removed · ${states.counts.missing} already absent`, elapsedSince(writeStarted));
       const receipt = receiptCard(options, displayRoot, colors, { status: 'Removed', written: 0, current: states.counts.current });
       progress.close();
       stdout.write(receipt);
@@ -423,6 +593,12 @@ export async function run(args, context = {}) {
     }
 
     if (states.states.every((state) => state === 'current')) {
+      try {
+        writeOwnershipManifest(root, files, states.manifest);
+      } catch (error) {
+        if (error && typeof error === 'object') error.step = 'WRITE';
+        throw error;
+      }
       skipStep(progress, 'WRITE', `SKIPPED · 0 written · ${states.counts.current} already-current`);
       const receipt = receiptCard(options, displayRoot, colors, { status: 'Already current', written: 0, current: states.counts.current });
       progress.close();
@@ -438,10 +614,12 @@ export async function run(args, context = {}) {
         if (states.states[index] === 'current') continue;
         const { source, target } = files[index];
         mkdirSync(dirname(target), { recursive: true });
-        copyFileSync(source, target, constants.COPYFILE_EXCL);
+        if (states.states[index] === 'owned') replaceOwnedFile(source, target);
+        else copyFileSync(source, target, constants.COPYFILE_EXCL);
         installed += 1;
       }
-      progress.finish('ok', 'WRITE', `${installed} written · ${states.counts.current} already-current`, elapsedSince(writeStarted));
+      writeOwnershipManifest(root, files, states.manifest);
+      progress.finish('ok', 'WRITE', `${installed} written · ${states.counts.current} already-current · ${states.counts.owned} owned`, elapsedSince(writeStarted));
     } catch (error) {
       progress.finish('failed', 'WRITE', errorText(error), elapsedSince(writeStarted));
       if (error && typeof error === 'object') error.step = 'WRITE';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "litgrok-ai",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Grok Build skills, project rules, and hooks installer.",
   "type": "module",
   "bin": {

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "litgrok",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Grok Build skills, project rules, and bounded lifecycle hooks for evidence-first lit work.",
   "author": {
     "name": "LitGrok contributors"