@pathbit/agentdevkit 0.0.16 → 0.0.18

package/src/install.mjs

@@ -1,20 +1,137 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { chmodSync, existsSync, lstatSync, readFileSync, writeFileSync, readdirSync, mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, rmdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, closeSync, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, writeFileSync, readdirSync, mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, rmdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { synchronize, isReference } from '../.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs';
-import { isGeneratedOutput, planLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, applyLocalIgnore, planUntrack, applyUntrack, restoreUntrack } from '../.pbai4devs/scripts/lib/gitignore.mjs';
+import { isGeneratedOutput, planLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, applyLocalIgnore, planUntrack, applyUntrack, restoreUntrack, indexContentMatches } from '../.pbai4devs/scripts/lib/gitignore.mjs';
 import { nativePathBoundary } from '../.pbai4devs/scripts/lib/native-paths.mjs';
 import { canonicalEntrypoint, resolveEntrypoint, entrypointReference, renderEntrypointImports, extractManagedBlock, managedBlockDigest, mergeManagedContent, stripManagedContent } from '../.pbai4devs/scripts/lib/managed-content.mjs';
 import { extractTomlManagedBlock, tomlManagedBlockDigest, mergeTomlContent, stripTomlContent } from '../.pbai4devs/scripts/lib/managed-toml.mjs';
 import { writeAdapterManifest, adapterRoots, normalizeClients, resolveAdapters } from './adapters/index.mjs';
-import { packageRoot, packageInfo, statePath, entryNames, begin, end } from './config.mjs';
+import { packageRoot, packageInfo, statePath, legacyStatePath, entryNames, begin, end } from './config.mjs';
 import { normalizeLanguage, text } from './i18n.mjs';
 
 const hash = value => createHash('sha256').update(value).digest('hex');
 const portable = value => value.split(sep).join('/');
 const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
 const stat = path => { try { return lstatSync(path); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } };
+
+// Protect staged human bytes that differ from the working tree, without
+// treating an unchanged HEAD entry as a staged edit or rewriting the index.
+function stagedDivergences(root) {
+  let anchor = resolve(root);
+  while (!existsSync(anchor)) {
+    const parent = dirname(anchor);
+    if (parent === anchor) break;
+    anchor = parent;
+  }
+  const prefix = portable(relative(anchor, root));
+  let hasGitMarker = false;
+  for (let current = anchor; ; current = dirname(current)) {
+    if (stat(join(current, '.git'))) { hasGitMarker = true; break; }
+    if (dirname(current) === current) break;
+  }
+  const env = { ...process.env, GIT_OPTIONAL_LOCKS: '0' };
+  for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE', 'GIT_EXTERNAL_DIFF']) delete env[key];
+  const run = args => spawnSync('git', ['-C', anchor, '-c', 'core.fsmonitor=false', ...args], {
+    env, timeout: 30000, windowsHide: true, maxBuffer: 16 * 1024 * 1024,
+  });
+  const repository = run(['rev-parse', '--is-inside-work-tree']);
+  if (repository.error || repository.status !== 0) {
+    if (hasGitMarker) fail('E_GIT', 'Unable to inspect the existing Git repository safely.');
+    if (repository.error?.code === 'ENOENT' || !repository.error && repository.status !== 0) return new Set();
+  }
+  if (repository.error || repository.status !== 0 || repository.stdout.toString('utf8').trim() !== 'true') fail('E_GIT', 'Unable to inspect Git worktree.');
+  // `git diff` against the worktree respects assume-unchanged and
+  // skip-worktree, so compare the actual bytes to the index blobs instead.
+  const stagedResult = run(['diff', '--cached', '--no-renames', '--no-ext-diff', '--no-textconv', '--name-only', '--relative', '-z']);
+  const indexResult = run(['ls-files', '--stage', '-z']);
+  if (stagedResult.error || stagedResult.status !== 0 || indexResult.error || indexResult.status !== 0) fail('E_GIT', 'Unable to inspect staged changes safely.');
+  const decode = buffer => {
+    const value = buffer.toString('utf8');
+    if (!Buffer.from(value, 'utf8').equals(buffer)) fail('E_GIT', 'Unable to safely inspect a non-UTF-8 staged path.');
+    return value;
+  };
+  const records = buffer => {
+    const result = []; let start = 0;
+    for (let i = 0; i < buffer.length; i++) if (buffer[i] === 0) { result.push(buffer.subarray(start, i)); start = i + 1; }
+    if (start !== buffer.length) fail('E_GIT', 'Unable to parse Git output safely.');
+    return result;
+  };
+  const paths = new Set(records(stagedResult.stdout).map(decode));
+  const entries = new Map();
+  for (const bytes of records(indexResult.stdout)) {
+    const tab = bytes.indexOf(9);
+    const record = bytes.subarray(0, tab).toString('ascii');
+    if (tab < 0) fail('E_GIT', 'Unable to parse the Git index safely.');
+    const match = /^(\d+) ([0-9a-f]+) ([0-3])$/.exec(record);
+    if (!match) fail('E_GIT', 'Unable to parse the Git index safely.');
+    const rawName = bytes.subarray(tab + 1);
+    const name = rawName.toString('utf8');
+    if (!paths.has(name)) continue;
+    if (!Buffer.from(name, 'utf8').equals(rawName)) fail('E_GIT', 'Unable to safely inspect a non-UTF-8 staged path.');
+    if (entries.has(name) || match[3] !== '0') entries.set(name, null);
+    else entries.set(name, { mode: match[1], oid: match[2] });
+  }
+  const divergent = new Set();
+  divergent.deleted = new Set();
+  for (const name of paths) {
+    if (prefix && !name.startsWith(`${prefix}/`)) continue;
+    const path = prefix ? name.slice(prefix.length + 1) : name;
+    const entry = entries.get(name);
+    // Distinguish a staged deletion from unresolved index stages.
+    if (!entries.has(name)) { divergent.add(path); divergent.deleted.add(path); continue; }
+    if (!entry || !['100644', '100755'].includes(entry.mode) || ![40, 64].includes(entry.oid.length)) { divergent.add(path); continue; }
+    let fd;
+    try {
+      const file = safePath(root, path), info = stat(file);
+      if (!info?.isFile()) { divergent.add(path); continue; }
+      fd = openSync(file, 'r');
+      const before = fstatSync(fd);
+      const digest = createHash(entry.oid.length === 64 ? 'sha256' : 'sha1').update(`blob ${before.size}\0`);
+      const buffer = Buffer.allocUnsafe(64 * 1024);
+      let count = 0, n;
+      while ((n = readSync(fd, buffer, 0, buffer.length, null)) !== 0) { digest.update(buffer.subarray(0, n)); count += n; }
+      const after = fstatSync(fd);
+      if (count !== before.size || before.size !== after.size || before.mtimeMs !== after.mtimeMs) { divergent.add(path); continue; }
+      if (digest.digest('hex') !== entry.oid) {
+        const indexed = run(['cat-file', 'blob', entry.oid]);
+        const working = readFileSync(file), latest = fstatSync(fd);
+        if (indexed.error || indexed.status !== 0) fail('E_GIT', 'Unable to inspect staged content safely.');
+        if (latest.size !== after.size || latest.mtimeMs !== after.mtimeMs || !indexContentMatches(root, path, working, indexed.stdout)) divergent.add(path);
+      }
+    } catch (error) {
+      // Treat paths that cannot be inspected (including symbolic links) as
+      // divergent; the normal safety checks still reject unsafe writes.
+      if (error.code === 'E_SYMLINK' || error.code === 'ENOENT' || error.code === 'ENOTDIR' || error.code === 'E_PATH') divergent.add(path);
+      else throw error;
+    } finally { if (fd !== undefined) closeSync(fd); }
+  }
+  return divergent;
+}
+// A staged name may use another case for the same path on macOS or Windows.
+// Probe an existing directory only; do not create files during a dry run.
+function stagedContains(root, paths, path) {
+  if (paths.has(path)) return true;
+  let current = root;
+  while (!stat(current) && dirname(current) !== current) current = dirname(current);
+  while (dirname(current) !== current) {
+    const base = current.slice(dirname(current).length + 1);
+    const index = base.search(/[A-Za-z]/);
+    if (index >= 0) {
+      const letter = base[index];
+      const other = letter === letter.toUpperCase() ? letter.toLowerCase() : letter.toUpperCase();
+      const alternative = join(dirname(current), `${base.slice(0, index)}${other}${base.slice(index + 1)}`);
+      const a = stat(current), b = stat(alternative);
+      if (!a || !b || a.dev !== b.dev || a.ino !== b.ino) return false;
+      return [...paths].some(candidate => candidate.toLowerCase() === path.toLowerCase());
+    }
+    current = dirname(current);
+  }
+  // If no existing name can be probed, preserve on ambiguity.
+  return [...paths].some(candidate => candidate.toLowerCase() === path.toLowerCase());
+}
 const ignored = new Set(['.git', '.local', '.cache', 'node_modules', '.agent-tests', 'opencode-loop']);
 const reservedTargets = new Set(['.git', 'node_modules', '.pbai4devs']);
 const checkTarget = path => {
@@ -54,11 +171,11 @@ export function safePath(root, path) {
 
 function resourceAllowed(path, directory = false) {
   const parts = path.split('/');
-  const folders = new Set(['agents', 'commands', 'external-skills', 'rules', 'scripts', 'skills', 'templates', 'tools', 'estado']);
+  const folders = new Set(['agents', 'commands', 'external-skills', 'rules', 'scripts', 'skills', 'templates', 'tools', 'state']);
   const files = new Set(['README.md', 'INSTRUCTIONS.md', 'COMPATIBILIDADE.md', 'LICENSE', '.gitignore']);
   if (!folders.has(parts[0]) && !(parts.length === 1 && files.has(parts[0]))) return false;
-  if (parts[0] === 'estado') return directory && parts.length === 1 || path === 'estado/README.md';
-  if (isGeneratedOutput(path, directory) || parts.some(part => ignored.has(part)) || parts[0] === 'adapters' || path === 'estado/agentdevkit.json' || path === '.npmignore') return false;
+  if (parts[0] === 'state') return directory && parts.length === 1 || path === 'state/README.md';
+  if (isGeneratedOutput(path, directory) || parts.some(part => ignored.has(part)) || parts[0] === 'adapters' || path === 'state/agentdevkit.json' || path === '.npmignore') return false;
   if (parts[0] === 'tools') return parts.length === 1 || (directory && parts.length === 2 && !['bin', 'npm-cache'].includes(parts[1])) || (parts.length === 2 && parts[1] === 'README.md') || (parts.length === 3 && ['TOOL.json', 'SCRIPT.mjs', 'README.md'].includes(parts[2]));
   if (parts[0] === 'external-skills') return parts.length === 1 || (parts.length === 2 && ['README.md', 'CATALOG.json'].includes(parts[1]));
   return true;
@@ -71,7 +188,10 @@ function walk(root, path = '', filter = () => true) {
   for (const name of readdirSync(directory).sort()) {
     const child = path ? `${path}/${name}` : name;
     const info = lstatSync(join(root, child));
-    if (info.isSymbolicLink()) fail('E_SYMLINK', `Symbolic link refused: ${child}`);
+    if (info.isSymbolicLink()) {
+      if (!filter(child, false) && !filter(child, true)) continue;
+      fail('E_SYMLINK', `Symbolic link refused: ${child}`);
+    }
     if (!filter(child, info.isDirectory())) continue;
     if (info.isDirectory()) files.push(...walk(root, child, filter));
     else if (info.isFile()) files.push(child);
@@ -109,6 +229,7 @@ function read(root, path) {
 }
 
 function allowedManaged(path) {
+  if (['.pbai4devs/estado/README.md', '.pbai4devs/adapters/README.md'].includes(path)) return true;
   if (canonicalEntrypoint(path) || path === '.gitignore') return true;
   if (nativeMarkdown(path) || nativeToml(path)) return true;
   if (['catalog.json', 'skills.json', 'agents.json', 'rules.json', 'espelhos.conf'].some(name => path === `.pbai4devs/${name}`)) return true;
@@ -122,7 +243,7 @@ function nativeMarkdown(path) {
     && adapterRoots.some(root => {
       if (!path.startsWith(`${root}/`)) return false;
       const relative = path.slice(root.length + 1).split('/');
-      return !['tools', 'scripts', 'templates', 'external-skills', 'estado', 'tests', 'docs', 'adapters', 'workflows'].includes(relative[0].toLowerCase())
+      return !['tools', 'scripts', 'templates', 'external-skills', 'estado', 'state', 'tests', 'docs', 'adapters', 'workflows'].includes(relative[0].toLowerCase())
         && !['readme.md', 'instructions.md'].includes(relative.at(-1).toLowerCase());
     });
 }
@@ -130,7 +251,7 @@ const nativeToml = path => path.startsWith('.gemini/commands/') && path.endsWith
 const nativeManagedText = path => nativeMarkdown(path) || nativeToml(path);
 
 export function loadState(root) {
-  const content = read(root, statePath); if (content === null) return null;
+  const content = read(root, actualStatePath(root)); if (content === null) return null;
   let state; try { state = JSON.parse(content); } catch { fail('E_STATE', 'Invalid AgentDevKit state JSON.'); }
   if (state?.schemaVersion !== 1 || !normalizeLanguage(state.language) || typeof state.version !== 'string' || !state.files || typeof state.files !== 'object' || Array.isArray(state.files) || !state.blocks || typeof state.blocks !== 'object' || Array.isArray(state.blocks)) fail('E_STATE', 'Invalid AgentDevKit state.');
   if (state.clients !== undefined) {
@@ -144,6 +265,81 @@ export function loadState(root) {
   return state;
 }
 
+function actualStatePath(root) {
+  const legacy = stat(safePath(root, '.pbai4devs/estado'));
+  const current = stat(safePath(root, '.pbai4devs/state'));
+  if (legacy && !legacy.isDirectory() || current && !current.isDirectory()) fail('E_STATE', 'AgentDevKit state must be a directory.');
+  if (legacy && current) fail('E_STATE', 'Both .pbai4devs/estado and .pbai4devs/state exist; preserve both and resolve the conflict.');
+  return legacy ? legacyStatePath : statePath;
+}
+
+function readLegacyConfiguration(root, path) {
+  const limit = 4 * 1024 * 1024, fd = openSync(safePath(root, path), 'r');
+  try {
+    if (!fstatSync(fd).isFile() || fstatSync(fd).size > limit) fail('E_STATE', 'Legacy configuration is too large or not a regular file.');
+    const buffer = Buffer.allocUnsafe(limit + 1);
+    let total = 0, count;
+    while (total < buffer.length && (count = readSync(fd, buffer, total, buffer.length - total, null)) > 0) total += count;
+    if (total > limit) fail('E_STATE', 'Legacy configuration is too large to inspect safely.');
+    return buffer.subarray(0, total);
+  } finally { closeSync(fd); }
+}
+
+function assertNoLegacyReferences(value) {
+  const legacy = /\.pbai4devs\/estado(?=$|\/|[\s"'\],}:#])/i;
+  const reject = () => fail('E_LEGACY_PATH', 'Replace .pbai4devs/estado references with .pbai4devs/state in the legacy configuration before running update.');
+  if (legacy.test(value)) reject();
+  const normalized = value.replaceAll('\r', '');
+  const header = normalized.match(/^---\n([\s\S]*?)\n---(?:\n|$)/)?.[1];
+  if (header === undefined) {
+    if (normalized.startsWith('---')) fail('E_CONFIG_PARSE', 'Legacy configuration has an incomplete frontmatter block.');
+    return;
+  }
+  let documents = false;
+  for (const line of header.split('\n')) {
+    const top = line.match(/^([a-z_]+):\s*(.*)$/);
+    if (top) documents = top[1] === 'documentos';
+    const nested = !top && documents ? line.match(/^  ([a-z_]+):\s*(.*)$/) : null;
+    const raw = (top?.[2] ?? nested?.[2])?.trim();
+    if (!raw?.startsWith('"')) continue;
+    let decoded;
+    try { decoded = JSON.parse(raw); }
+    catch { fail('E_CONFIG_PARSE', 'Legacy configuration contains an ambiguous quoted scalar.'); }
+    if (typeof decoded !== 'string') fail('E_CONFIG_PARSE', 'Legacy configuration contains an invalid quoted scalar.');
+    if (legacy.test(decoded)) reject();
+  }
+}
+
+function legacyStateMigration(root) {
+  if (actualStatePath(root) !== legacyStatePath) return null;
+  const base = '.pbai4devs/estado', files = [], directories = [];
+  const visit = folder => {
+    const info = stat(safePath(root, folder));
+    if (!info?.isDirectory()) fail('E_STATE', `Invalid state directory: ${folder}`);
+    const names = readdirSync(safePath(root, folder)).sort();
+    directories.push({ path: folder, mode: info.mode & 0o777, names });
+    for (const name of names) {
+      const path = `${folder}/${name}`, item = stat(safePath(root, path));
+      if (item?.isDirectory()) visit(path);
+      else if (item?.isFile()) {
+        const configuration = path === `${base}/configuracao/ESTADO.md`;
+        const content = configuration ? readLegacyConfiguration(root, path) : read(root, path);
+        if (configuration) {
+          if (content.includes(0)) fail('E_STATE', 'Legacy configuration contains binary data.');
+          let value;
+          try { value = new TextDecoder('utf-8', { fatal: true }).decode(content); }
+          catch { fail('E_STATE', 'Legacy configuration is not valid UTF-8.'); }
+          assertNoLegacyReferences(value);
+        }
+        files.push({ path, target: path.replace(`${base}/`, '.pbai4devs/state/'), mode: item.mode & 0o777, content });
+      }
+      else fail('E_STATE', `Unsupported state entry: ${path}`);
+    }
+  };
+  visit(base);
+  return { files, directories };
+}
+
 function extractBlock(content, first = begin, last = end) {
   const start = content.indexOf(first), finish = content.indexOf(last);
   if (start < 0 && finish < 0) return null;
@@ -194,7 +390,7 @@ function copyResources(source, destination) {
 
 function readDerivedState(target) {
   let entries = {}, outputs = {}, blocks = {}, files = {}, removedBlocks = [];
-  const derived = read(target, '.pbai4devs/estado/derived.json');
+  const derived = read(target, actualStatePath(target).replace(/agentdevkit\.json$/, 'derived.json'));
   if (derived) {
     try {
       const value = JSON.parse(derived);
@@ -216,6 +412,10 @@ function readDerivedState(target) {
 
 export function planInstallation({ target, language = 'pt', mode = 'init', force = false, clients }) {
   const previous = loadState(target);
+  const migration = legacyStateMigration(target);
+  // A migration must update the installed scripts and pointers in the same
+  // transaction; a plain sync/agents/lang would leave old hard-coded paths.
+  if (migration && !['init', 'update'].includes(mode)) fail('E_UPGRADE', 'Run AgentDevKit update before migrating the legacy state directory.');
   if (mode !== 'init' && !previous) fail('E_MISSING', text(language, 'missing'));
   const selected = normalizeClients(clients ?? previous?.clients ?? ['all']);
   const active = resolveAdapters(selected);
@@ -236,6 +436,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     ?? (canonicalEntrypoint(path) ? Object.entries(knownBlocks).find(([candidate]) => canonicalEntrypoint(candidate) === canonicalEntrypoint(path))?.[1] : undefined);
   const preserved = new Map();
   const recordPreserved = (path, reason) => { preserved.set(path, { path, reason }); return true; };
+  const stagedHuman = stagedDivergences(target);
   const native = path => canonicalEntrypoint(path) || path === 'README.md' || adapterRoots.some(root => path === root || path.startsWith(`${root}/`));
   const boundary = path => {
     if (!native(path)) return false;
@@ -272,9 +473,28 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       bundled.push('LICENSE');
     }
     const supplied = new Set(bundled);
-    const internal = new Set(['catalog.json', 'skills.json', 'agents.json', 'rules.json', 'espelhos.conf', '.gitignore', 'estado/README.md']);
-    if (bundled.length) for (const path of Object.keys(previous?.files || {})) {
-      if (path.startsWith('.pbai4devs/') && !supplied.has(path.slice(11)) && !internal.has(path.slice(11))) rmSync(safePath(stage, path), { force: true });
+    const internal = new Set(['catalog.json', 'skills.json', 'agents.json', 'rules.json', 'espelhos.conf', '.gitignore', 'state/README.md', 'estado/README.md']);
+    // A pathname, matching contents, or --force alone do not establish that a
+    // project's hub source belongs to the kit. Restore human files *before*
+    // deriving native pointers so that the staged catalogue describes the
+    // source that will actually remain in the project.
+    const preservedHub = new Set();
+    for (const relative of existing) {
+      const path = `.pbai4devs/${relative}`;
+      if (internal.has(relative)) continue;
+      const current = read(target, path);
+      if (!current || previous?.files?.[path] === hash(current) && !stagedContains(target, stagedHuman, path)) continue;
+      if (supplied.has(relative)) write(stage, path, current);
+      preservedHub.add(path);
+      recordPreserved(path, stagedContains(target, stagedHuman, path) ? 'staged-content-differs' : previous?.files?.[path] ? 'edited-managed-file' : 'existing-file');
+    }
+    if (bundled.length) for (const [path, digest] of Object.entries(previous?.files || {})) {
+      if (!path.startsWith('.pbai4devs/') || supplied.has(path.slice(11)) || internal.has(path.slice(11))) continue;
+      const current = read(target, path);
+      if (current && (digest !== hash(current) || stagedContains(target, stagedHuman, path))) {
+        preservedHub.add(path);
+        recordPreserved(path, stagedContains(target, stagedHuman, path) ? 'staged-content-differs' : 'edited-managed-file');
+      } else rmSync(safePath(stage, path), { force: true });
     }
     for (const root of active.roots) {
       if (preserveNative(`${root}/.gitignore`)) continue;
@@ -302,10 +522,32 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       }
     }
     if (!preserveNative('README.md') && !read(target, 'README.md')) write(stage, 'README.md', `---\ndescription: ${JSON.stringify(text(language, 'readme'))}\nlanguage: ${language}\n---\n\n# ${text(language, 'project')}\n\n${text(language, 'readme')}\n`);
-    if (!existsSync(join(stage, '.pbai4devs/estado/README.md'))) write(stage, '.pbai4devs/estado/README.md', `---\ndescription: AgentDevKit state.\n---\n\n# AgentDevKit\n\n${text(language, 'state')}\n`);
+    if (!existsSync(join(stage, '.pbai4devs/state/README.md'))) write(stage, '.pbai4devs/state/README.md', `---\ndescription: AgentDevKit state.\n---\n\n# AgentDevKit\n\n${text(language, 'state')}\n`);
     const unknown = new Set(existing.filter(path => !supplied.has(path) && !previous?.files[`.pbai4devs/${path}`] && !internal.has(path)));
     const paths = walk(stage, '', path => !path.split('/').includes('.agent-tests')).filter(path => !path.startsWith('.pbai4devs/') || !unknown.has(path.slice(11)));
     const desired = new Map(paths.filter(path => !preserveNative(path)).map(path => [path, readFileSync(join(stage, path))]));
+    const migratedHuman = new Set();
+    for (const item of migration?.files || []) {
+      if (item.path === legacyStatePath) continue;
+      if (item.path === '.pbai4devs/estado/README.md') {
+        const managed = previous?.files?.[item.path] === hash(item.content);
+        const matchesTemplate = desired.get(item.target)?.equals(item.content);
+        desired.set(item.target, item.content);
+        if (!managed || !matchesTemplate) { recordPreserved(item.target, 'existing-file'); migratedHuman.add(item.target); }
+        continue;
+      }
+      if (desired.has(item.target)) fail('E_STATE', `State migration collides with a managed file: ${item.target}`);
+      desired.set(item.target, item.content);
+      migratedHuman.add(item.target);
+    }
+    // Preserve human README content; verified managed files may be updated.
+    const stateReadme = '.pbai4devs/state/README.md';
+    const currentStateReadme = read(target, stateReadme);
+    if (currentStateReadme && previous?.files?.[stateReadme] !== hash(currentStateReadme)) {
+      desired.set(stateReadme, currentStateReadme);
+      migratedHuman.add(stateReadme);
+      recordPreserved(stateReadme, 'existing-file');
+    }
     for (const [path, content] of desired) {
       if (!nativeManagedText(path) || canonicalEntrypoint(path)) continue;
       const current = read(target, path);
@@ -330,7 +572,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     const manifest = { schemaVersion: 1, version: bundled.length ? packageInfo.version : previous.version, language, files: {}, blocks: {} };
     if (mode !== 'sync' || clients !== undefined || previous?.clients !== undefined) manifest.clients = selected;
     for (const [path, content] of desired) {
-      if (path === 'README.md') continue;
+      if (path === 'README.md' || migratedHuman.has(path) || preservedHub.has(path)) continue;
       const block = blockDigest(path, content);
       if (block) manifest.blocks[path] = block;
       else manifest.files[path] = hash(content);
@@ -348,19 +590,22 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       const conflict = current && path !== statePath && !managed && !appendBlock;
       const changedBlock = current && knownBlocks[path] && !managed;
       if (conflict || changedBlock) conflicts.push(path);
-      changes.push({ path, action: current ? 'update' : 'create', content, beforeHash: current ? hash(current) : null });
+      const migrated = migration?.files.find(item => item.target === path);
+      changes.push({ path, action: current ? 'update' : 'create', content, beforeHash: current ? hash(current) : null, ...(migrated ? { mode: migrated.mode } : {}) });
     }
     const wholeRecords = [previous?.files || {}, derivedEntries, derivedFiles];
     for (const path of new Set(wholeRecords.flatMap(record => Object.keys(record)))) if (!desired.has(path)) {
+      if (migration && path.startsWith('.pbai4devs/estado/')) continue;
       if (path === '.gitignore') { recordPreserved(path, 'project-owned'); continue; }
       if (aliasedEntrypoint(path)) continue;
       const current = read(target, path); if (!current) continue;
       const known = wholeRecords.some(record => record[path] === hash(current));
-      if (nativeManagedText(path) && !known) { recordPreserved(path, 'existing-file'); continue; }
-      if (!known) conflicts.push(path);
+      if (stagedContains(target, stagedHuman, path)) { recordPreserved(path, 'staged-content-differs'); continue; }
+      if (!known) { recordPreserved(path, 'edited-managed-file'); continue; }
       changes.push({ path, action: 'remove', content: null, beforeHash: hash(current) });
     }
     for (const [recordedPath, digest] of Object.entries(knownBlocks)) {
+      if (migration && recordedPath.startsWith('.pbai4devs/estado/')) continue;
       const path = canonicalEntrypoint(recordedPath) ? entryPaths.get(canonicalEntrypoint(recordedPath)) : recordedPath;
       if (desired.has(path)) continue;
       if (changes.some(change => change.path === path)) continue;
@@ -404,12 +649,53 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       if (preserved.has(full) || !known || !generatedReference(current)) { recordPreserved(full, 'existing-file'); continue; }
       changes.push({ path: full, action: 'remove', content: null, beforeHash: hash(current) });
     }
-    const legacy = '.pbai4devs/adapters/README.md', legacyContent = read(target, legacy);
-    if (legacyContent) {
-      const known = legacyContent.toString('utf8').includes('# Adaptadores') && /Antigravity|metadados/.test(legacyContent.toString('utf8'));
-      if (!known) conflicts.push(legacy);
-      changes.push({ path: legacy, action: 'remove', content: null, beforeHash: hash(legacyContent) });
+    const legacy = '.pbai4devs/adapters/README.md', legacyRoot = '.pbai4devs/adapters';
+    const legacyRootInfo = stat(join(target, legacyRoot));
+    const legacyInfo = legacyRootInfo?.isDirectory() ? stat(join(target, legacy)) : null;
+    if (legacyRootInfo && !legacyRootInfo.isDirectory()) recordPreserved(legacyRoot, legacyRootInfo.isSymbolicLink() ? 'symbolic-link' : 'existing-file');
+    if (legacyInfo && !legacyInfo.isFile()) recordPreserved(legacy, legacyInfo.isSymbolicLink() ? 'symbolic-link' : 'existing-directory');
+    const legacyContent = legacyInfo?.isFile() ? read(target, legacy) : null;
+    if (legacyContent && !changes.some(change => change.path === legacy)) {
+      if (!stagedContains(target, stagedHuman, legacy) && previous?.files?.[legacy] === hash(legacyContent)) changes.push({ path: legacy, action: 'remove', content: null, beforeHash: hash(legacyContent) });
+      else recordPreserved(legacy, stagedContains(target, stagedHuman, legacy) ? 'staged-content-differs' : 'existing-file');
     }
+    for (const item of migration?.files || []) changes.push({ path: item.path, action: 'remove', content: null, beforeHash: hash(item.content) });
+    // The generated catalogues must agree with the installed sources. A staged
+    // deletion has no indexed bytes to overwrite; allow their regeneration only
+    // when the current file exactly matches the previously owned digest.
+    const generatedCatalogues = new Set(['.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json']);
+    for (const change of changes) if (change.action === 'update' && generatedCatalogues.has(change.path)
+      && stagedContains(target, stagedHuman.deleted || new Set(), change.path)
+      && change.beforeHash && previous?.files?.[change.path] === change.beforeHash) change.stagedDeletionAllowed = true;
+    for (const change of changes) {
+      if (!stagedContains(target, stagedHuman, change.path)) continue;
+      const current = read(target, change.path);
+      if (change.action === 'update' && current && change.content && nativeManagedText(change.path)) {
+        // Preserve every byte outside a known managed block. Appending a block
+        // is also safe when the complete existing file is an exact prefix.
+        if (!nativeToml(change.path) && change.content.subarray(0, current.length).equals(current)) {
+          try {
+            const digest = managedBlockDigest(change.content);
+            const stripped = digest && stripManagedContent(change.content, digest);
+            const extra = stripped?.slice(current.toString('utf8').length);
+            if (stripped?.startsWith(current.toString('utf8')) && extra !== undefined && /^[\r\n]*$/.test(extra)) change.stagedBlockAllowed = true;
+          } catch { /* Invalid or unproven block: keep the path blocked. */ }
+        } else if (knownBlocks[change.path]) {
+          try {
+            const strip = nativeToml(change.path) ? stripTomlContent : stripManagedContent;
+            if (Buffer.from(strip(current, knownBlocks[change.path])).equals(change.content)) change.stagedBlockAllowed = true;
+          } catch { /* An edited block is not safe to remove. */ }
+        }
+      }
+      if (change.action === 'remove' && migration) {
+        const item = migration.files.find(file => file.path === change.path);
+        const copy = item && changes.find(candidate => candidate.path === item.target && candidate.action === 'create');
+        if (item && current?.equals(item.content) && copy?.content?.equals(item.content)
+          && changes.indexOf(copy) < changes.indexOf(change)) change.stagedMigrationTarget = item.target;
+      }
+    }
+    const stagedChanges = changes.filter(change => stagedContains(target, stagedHuman, change.path) && !change.stagedDeletionAllowed && !change.stagedBlockAllowed && !change.stagedMigrationTarget);
+    if (stagedChanges.length) fail('E_STAGED', `Staged content differs from the working tree for planned changes: ${stagedChanges.map(change => `${change.action} ${change.path}`).join(', ')}. Preserve and review these paths before updating.`);
     const retiredRoots = adapterRoots.filter(root => !active.roots.includes(root) && changes.some(change => change.action === 'remove' && change.path.startsWith(`${root}/`) && (previous?.files[change.path] || previous?.blocks[change.path])));
     const ownedOutputs = [...new Set([...synchronized.ownedOutputs, ...ownedEntrypoints, statePath])].filter(path => !mixedPaths.has(path) && !overlapsPreserved(path));
     const hashes = {};
@@ -419,12 +705,13 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       const current = read(target, path);
       if (current) { const source = current.toString('utf8'), block = extractBlock(source, '# BEGIN AGENT IGNORE', '# END AGENT IGNORE'); if (block && source.trim() === block.trim() && hash(block) === previous.blocks[path]) hashes[path] = hash(current); }
     }
-    if (previous) hashes[statePath] = hash(read(target, statePath));
+    if (previous && !migration) hashes[statePath] = hash(read(target, statePath));
     const untrack = existsSync(target) ? planUntrack(target, hashes) : null;
+    if (migration && untrack?.paths.length) fail('E_STATE', 'State migration would change the Git index; preserve and resolve tracked outputs first.');
     const localIgnore = planLocalIgnore(target, { outputs: ownedOutputs, templateRoot: stage });
     const localIgnoreCheck = checkLocalIgnore(localIgnore, { replacedBlocks: replacedIgnoreBlocks(target, changes, previous) });
     conflicts.push(...(untrack?.conflicts || []), ...localIgnoreCheck.missing);
-    return { target, language, mode, changes, conflicts: [...new Set(conflicts)].sort(), canApply: (!conflicts.length || force) && !untrack?.conflicts?.length && !localIgnoreCheck.missing.length, manifest, retiredRoots, ownedOutputs, untrack, localIgnore, localIgnoreCheck, preserved: [...preserved.values()].sort((a, b) => a.path.localeCompare(b.path)) };
+    return { target, language, mode, changes, conflicts: [...new Set(conflicts)].sort(), canApply: (!conflicts.length || force) && !untrack?.conflicts?.length && !localIgnoreCheck.missing.length, manifest, retiredRoots, ownedOutputs, untrack, localIgnore, localIgnoreCheck, migration, preserved: [...preserved.values()].sort((a, b) => a.path.localeCompare(b.path)) };
   } finally { rmSync(stage, { recursive: true, force: true }); }
 }
 
@@ -432,6 +719,35 @@ export function applyPlan(plan) {
   if (!plan.canApply) fail('E_CONFLICT', text(plan.language, 'conflict'));
   assertLocalIgnoreUnchanged(plan.localIgnore);
   const { target } = plan;
+  const stagedHuman = stagedDivergences(target);
+  const currentState = loadState(target);
+  const stagedChanges = plan.changes.filter(change => {
+    if (!stagedContains(target, stagedHuman, change.path)) return false;
+    const current = read(target, change.path);
+    if ((current ? hash(current) : null) !== change.beforeHash) fail('E_CHANGED', `File changed after planning: ${change.path}`);
+    if (!current) return true;
+    if (change.stagedDeletionAllowed && stagedContains(target, stagedHuman.deleted || new Set(), change.path)
+      && currentState?.files?.[change.path] === change.beforeHash) return false;
+    if (change.stagedBlockAllowed) return false; // Exact source and planned bytes were checked above.
+    if (change.stagedMigrationTarget) {
+      const copy = plan.changes.find(candidate => candidate.path === change.stagedMigrationTarget && candidate.action === 'create');
+      if (copy?.content?.equals(current) && plan.changes.indexOf(copy) < plan.changes.indexOf(change)
+        && !stat(safePath(target, change.stagedMigrationTarget))) return false;
+    }
+    return true;
+  });
+  if (stagedChanges.length) fail('E_STAGED', `Staged content differs from the working tree for planned changes: ${stagedChanges.map(change => `${change.action} ${change.path}`).join(', ')}. Preserve and review these paths before updating.`);
+  if (plan.migration) {
+    if (stat(safePath(target, '.pbai4devs/state'))) fail('E_CHANGED', 'State destination appeared after planning.');
+    for (const directory of plan.migration.directories) {
+      const info = stat(safePath(target, directory.path));
+      if (!info?.isDirectory() || (info.mode & 0o777) !== directory.mode || JSON.stringify(readdirSync(safePath(target, directory.path)).sort()) !== JSON.stringify(directory.names)) fail('E_CHANGED', `State directory changed after planning: ${directory.path}`);
+    }
+    for (const item of plan.migration.files) {
+      const info = stat(safePath(target, item.path));
+      if (!info?.isFile() || (info.mode & 0o777) !== item.mode || hash(readFileSync(safePath(target, item.path))) !== hash(item.content)) fail('E_CHANGED', `State file changed after planning: ${item.path}`);
+    }
+  }
   const backup = `.agent-tests/agentdevkit/backups/${Date.now()}-${randomUUID()}`;
   safePath(target, backup);
   for (const change of plan.changes) safePath(target, change.path);
@@ -456,11 +772,36 @@ export function applyPlan(plan) {
       const file = safePath(target, change.path);
       const content = change.content;
       const signature = { path: change.path, hash: content === null ? null : hash(content) };
-      if (content === null) { rmSync(file, { force: true }); applied.push(signature); }
-      else atomicWrite(target, change.path, content, beforeModes.get(change.path), mode => {
+      if (content === null) {
+        const migrated = plan.migration?.files.find(item => item.path === change.path);
+        if (migrated) {
+          const copy = plan.changes.find(candidate => candidate.path === migrated.target && candidate.action === 'create');
+          const copied = read(target, migrated.target);
+          if (!copy?.content || !copied?.equals(copy.content)
+            || migrated.path !== legacyStatePath && !copied.equals(before.get(change.path))) {
+            fail('E_CHANGED', `Migrated copy changed before removing: ${change.path}`);
+          }
+        }
+        rmSync(file, { force: true }); applied.push(signature);
+      }
+      else atomicWrite(target, change.path, content, beforeModes.get(change.path) ?? change.mode, mode => {
         signature.mode = mode; applied.push(signature);
       }, () => assertOriginal(change.path));
     }
+    if (plan.migration) {
+      for (const directory of plan.migration.directories) {
+        const destination = directory.path.replace(/^\.pbai4devs\/estado/, '.pbai4devs/state');
+        const file = safePath(target, destination), existing = stat(file);
+        if (existing && !existing.isDirectory()) fail('E_CHANGED', `Invalid state destination: ${destination}`);
+        if (!existing) mkdirSync(file, { recursive: true, mode: directory.mode });
+        chmodSync(file, directory.mode);
+      }
+      for (const directory of [...plan.migration.directories].sort((a, b) => b.path.length - a.path.length)) {
+        const file = safePath(target, directory.path), info = stat(file);
+        if (!info?.isDirectory() || readdirSync(file).length) fail('E_CHANGED', `State directory changed during migration: ${directory.path}`);
+        rmdirSync(file); removedDirectories.push({ path: directory.path, mode: directory.mode });
+      }
+    }
     pruneRemovedDirectories(plan, directory => removedDirectories.push(directory));
     const changesFallback = plan.changes.some(change => change.path === '.gitignore');
     // Metadata is committed last; its writer rolls back partial writes itself.
@@ -498,6 +839,11 @@ export function applyPlan(plan) {
         else rollbackErrors.push(failure);
       }
     }
+    if (plan.migration) for (const directory of [...plan.migration.directories].sort((a, b) => b.path.length - a.path.length)) {
+      const destination = directory.path.replace(/^\.pbai4devs\/estado/, '.pbai4devs/state');
+      try { const file = safePath(target, destination); if (stat(file)?.isDirectory() && !readdirSync(file).length) rmdirSync(file); }
+      catch (failure) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(failure.code)) rollbackErrors.push(failure); }
+    }
     if (preserved.length) {
       try { error.rollbackPreservedPaths = preserved; } catch { /* Preserve a exceção original. */ }
     }