@3lineas/grooveskills 1.6.0 → 1.7.1

package/dist/{chunk-HUG3MG3P.js → chunk-SP3ESDM5.js}

@@ -1,3 +1,8 @@
+// src/main.ts
+import { basename as basename3 } from "path";
+import { userInfo as userInfo2 } from "os";
+import picocolors5 from "picocolors";
+
 // src/domains/detector/project-detector.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { join as join2 } from "path";
@@ -37,11 +42,11 @@ function detectDependencies(targetPath) {
     try {
       const raw = readFileSync(packageJsonPath, "utf-8");
       const parsed = JSON.parse(raw);
-      for (const dep of Object.keys(parsed.dependencies ?? {})) {
-        detected.add(dep);
+      for (const dependencyName of Object.keys(parsed.dependencies ?? {})) {
+        detected.add(dependencyName);
       }
-      for (const dep of Object.keys(parsed.devDependencies ?? {})) {
-        detected.add(dep);
+      for (const dependencyName of Object.keys(parsed.devDependencies ?? {})) {
+        detected.add(dependencyName);
       }
     } catch {
     }
@@ -94,6 +99,13 @@ var SKILL_CATALOG = [
     dependencies: [],
     directoryName: "ux-writing"
   },
+  {
+    id: "docs-standards",
+    name: "Documentation & ADR Standards",
+    description: "English documentation standard, relative POSIX links, resilient Mermaid diagrams, ADR lifecycle, and intent-focused docstrings",
+    dependencies: [],
+    directoryName: "docs-standards"
+  },
   {
     id: "typescript-clean",
     name: "TypeScript Clean Code (TS 5.5+)",
@@ -243,6 +255,7 @@ function detectProjectContext(targetPath) {
     "odd-ai",
     "best-practices",
     "ux-writing",
+    "docs-standards",
     "error-handling-logging",
     "clean-architecture-ddd",
     "external-service-adapters",
@@ -257,7 +270,9 @@ function detectProjectContext(targetPath) {
     if (skill.dependencies.length === 0) {
       continue;
     }
-    const hasMatch = skill.dependencies.some((dep) => dependencies.includes(dep));
+    const hasMatch = skill.dependencies.some(
+      (dependencyName) => dependencies.includes(dependencyName)
+    );
     if (hasMatch && !suggestedSkillIds.includes(skill.id)) {
       suggestedSkillIds.push(skill.id);
     }
@@ -276,21 +291,21 @@ function detectProjectContext(targetPath) {
 }
 
 // src/domains/ui/ui-orchestrator.ts
-import * as p5 from "@clack/prompts";
-import pc3 from "picocolors";
+import * as prompts6 from "@clack/prompts";
+import picocolors4 from "picocolors";
 
 // src/domains/ui/banners.ts
-import pc from "picocolors";
+import picocolors from "picocolors";
 function renderBanner() {
-  const title = pc.bold(pc.white(" GROOVE SKILLS "));
-  const badge = pc.bgMagenta(pc.black(title));
-  const subtitle = pc.dim("Multi-Agent AI Skills & Architectural Standards");
+  const title = picocolors.bold(picocolors.white(" GROOVE SKILLS "));
+  const badge = picocolors.bgMagenta(picocolors.black(title));
+  const subtitle = picocolors.dim("Multi-Agent AI Skills & Architectural Standards");
   return `${badge}  ${subtitle}
 `;
 }
 
 // src/domains/ui/prompt-skills.ts
-import * as p from "@clack/prompts";
+import * as prompts from "@clack/prompts";
 async function promptSkills(suggestedSkillIds) {
   const selectableSkills = SKILL_CATALOG.filter((skill) => !skill.isCoreHarness);
   const options = selectableSkills.map((skill) => {
@@ -301,7 +316,7 @@ async function promptSkills(suggestedSkillIds) {
       hint: isSuggested ? "Suggested based on your project stack" : skill.description
     };
   });
-  const selected = await p.multiselect({
+  const selected = await prompts.multiselect({
     message: "Which skills would you like to install in this project?",
     options,
     initialValues: suggestedSkillIds,
@@ -311,7 +326,7 @@ async function promptSkills(suggestedSkillIds) {
 }
 
 // src/domains/ui/prompt-agents.ts
-import * as p2 from "@clack/prompts";
+import * as prompts2 from "@clack/prompts";
 async function promptAgents(detectedAgents) {
   const options = [
     { value: "antigravity", label: "Antigravity", hint: ".agents/skills (Google Agentic IDE)" },
@@ -320,7 +335,7 @@ async function promptAgents(detectedAgents) {
     { value: "gemini", label: "Gemini Code Assist", hint: ".gemini/skills (Google Gemini)" }
   ];
   const initialValues = detectedAgents.length > 0 ? detectedAgents : ["antigravity"];
-  const selected = await p2.multiselect({
+  const selected = await prompts2.multiselect({
     message: "Which AI agents should be configured?",
     options,
     initialValues,
@@ -330,16 +345,16 @@ async function promptAgents(detectedAgents) {
 }
 
 // src/domains/ui/prompt-language.ts
-import * as p3 from "@clack/prompts";
+import * as prompts3 from "@clack/prompts";
 async function promptLanguage(defaultLanguage = "es") {
   const options = [
-    { value: "es", label: "Espa\xF1ol (Spanish)", hint: "Recomendado para proyectos en espa\xF1ol" },
+    { value: "es", label: "Espa\xF1ol (Spanish)", hint: "Recommended for Spanish-speaking projects" },
     { value: "en", label: "English", hint: "Standard international English" },
-    { value: "pt", label: "Portugu\xEAs (Portuguese)", hint: "Portugu\xEAs para o Brasil e Portugal" },
-    { value: "it", label: "Italiano (Italian)", hint: "Comunicazione in lingua italiana" },
-    { value: "fr", label: "Fran\xE7ais (French)", hint: "Communication en langue fran\xE7aise" }
+    { value: "pt", label: "Portugu\xEAs (Portuguese)", hint: "Portuguese for Brazil and Portugal" },
+    { value: "it", label: "Italiano (Italian)", hint: "Italian language communication" },
+    { value: "fr", label: "Fran\xE7ais (French)", hint: "French language communication" }
   ];
-  const selected = await p3.select({
+  const selected = await prompts3.select({
     message: "Which language should AI agents use for user-facing copy and communication?",
     options,
     initialValue: defaultLanguage
@@ -348,9 +363,9 @@ async function promptLanguage(defaultLanguage = "es") {
 }
 
 // src/domains/ui/prompt-confirm-overwrite.ts
-import * as p4 from "@clack/prompts";
+import * as prompts4 from "@clack/prompts";
 async function promptConfirmOverwrite() {
-  return await p4.confirm({
+  return await prompts4.confirm({
     message: "Some skills already exist in this project. Would you like to overwrite them with the latest version?",
     initialValue: true
   });
@@ -360,10 +375,10 @@ async function promptConfirmOverwrite() {
 import { lstatSync } from "fs";
 import { join as join3 } from "path";
 var AGENT_DESTINATION_MAP = {
-  antigravity: (dir) => join3(".agents", "skills", dir),
-  claude: (dir) => join3(".claude", "skills", dir),
-  cursor: (dir) => join3(".cursor", "rules", `${dir}.mdc`),
-  gemini: (dir) => join3(".gemini", "skills", dir)
+  antigravity: (directoryName) => join3(".agents", "skills", directoryName),
+  claude: (directoryName) => join3(".claude", "skills", directoryName),
+  cursor: (directoryName) => join3(".cursor", "rules", `${directoryName}.mdc`),
+  gemini: (directoryName) => join3(".gemini", "skills", directoryName)
 };
 function verifySkillExists(targetPath, skillDirectoryName, agents) {
   for (const agent of agents) {
@@ -379,10 +394,10 @@ function verifySkillExists(targetPath, skillDirectoryName, agents) {
 }
 
 // src/domains/installer/install-orchestrator.ts
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 
 // src/domains/adapters/skill-reference-builder.ts
-import { existsSync as existsSync3, lstatSync as lstatSync2, mkdirSync, readFileSync as readFileSync3, rmSync, unlinkSync, writeFileSync } from "fs";
+import { existsSync as existsSync5, lstatSync as lstatSync3, mkdirSync, readFileSync as readFileSync3, rmSync as rmSync2, unlinkSync } from "fs";
 import { join as join5 } from "path";
 
 // src/domains/project-store/project-paths.ts
@@ -403,12 +418,195 @@ function getProjectConfigPath(targetPath) {
   return join4(getProjectStoreDir(targetPath), "config.json");
 }
 
+// src/domains/fs/safe-file-writer.ts
+import { chmodSync, existsSync as existsSync4, renameSync, rmSync, writeFileSync } from "fs";
+
+// src/domains/fs/inspect-file-access.ts
+import { execFileSync } from "child_process";
+import { accessSync, constants, existsSync as existsSync3, lstatSync as lstatSync2 } from "fs";
+import { dirname } from "path";
+var UF_IMMUTABLE = 2;
+var SF_IMMUTABLE = 131072;
+function resolveNearestExistingDir(startDir) {
+  let current = startDir;
+  while (!existsSync3(current)) {
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return current;
+}
+function detectMacOsImmutableFlag(filePath, lstat) {
+  const rawFlags = lstat.flags;
+  if (typeof rawFlags === "number") {
+    return Boolean(rawFlags & (UF_IMMUTABLE | SF_IMMUTABLE));
+  }
+  if (process.platform !== "darwin") {
+    return false;
+  }
+  try {
+    const out = execFileSync("stat", ["-f", "%f", filePath], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    const parsedFlags = Number.parseInt(out, 10);
+    if (Number.isNaN(parsedFlags)) {
+      return false;
+    }
+    return Boolean(parsedFlags & (UF_IMMUTABLE | SF_IMMUTABLE));
+  } catch {
+    return false;
+  }
+}
+function inspectFileAccess(filePath) {
+  const currentUid = typeof process.getuid === "function" ? process.getuid() : null;
+  const parentDir = dirname(filePath);
+  const checkDir = resolveNearestExistingDir(parentDir);
+  let dirWritable = false;
+  try {
+    accessSync(checkDir, constants.W_OK);
+    dirWritable = true;
+  } catch {
+    dirWritable = false;
+  }
+  let lstat = null;
+  try {
+    lstat = lstatSync2(filePath);
+  } catch {
+    lstat = null;
+  }
+  if (!lstat) {
+    return {
+      filePath,
+      exists: false,
+      isSymlink: false,
+      ownedByCurrentUser: true,
+      ownerUid: null,
+      currentUid,
+      mode: null,
+      immutableFlag: false,
+      dirWritable,
+      parentDir
+    };
+  }
+  const isSymlink = lstat.isSymbolicLink();
+  const ownerUid = lstat.uid;
+  const ownedByCurrentUser = currentUid === null || ownerUid === currentUid;
+  const mode = lstat.mode & 511;
+  const immutableFlag = detectMacOsImmutableFlag(filePath, lstat);
+  return {
+    filePath,
+    exists: true,
+    isSymlink,
+    ownedByCurrentUser,
+    ownerUid,
+    currentUid,
+    mode,
+    immutableFlag,
+    dirWritable,
+    parentDir
+  };
+}
+function formatOwnerName(uid) {
+  if (uid === 0) {
+    return "root";
+  }
+  if (uid === null) {
+    return "another user";
+  }
+  return `uid ${uid}`;
+}
+
+// src/errors/file-permission-error.ts
+function buildDiagnosisReason(diagnosis) {
+  if (diagnosis.immutableFlag) {
+    return "immutable flag (uchg) is set";
+  }
+  if (diagnosis.exists && !diagnosis.ownedByCurrentUser) {
+    return `owned by ${formatOwnerName(diagnosis.ownerUid)}`;
+  }
+  if (!diagnosis.dirWritable) {
+    return `parent directory '${diagnosis.parentDir}' is not writable`;
+  }
+  return "permission denied";
+}
+function buildSuggestedFix(diagnosis) {
+  if (diagnosis.immutableFlag) {
+    return `chflags nouchg "${diagnosis.filePath}"`;
+  }
+  if (diagnosis.exists && !diagnosis.ownedByCurrentUser) {
+    return `sudo chown "$(id -un)" "${diagnosis.filePath}"`;
+  }
+  if (!diagnosis.dirWritable) {
+    return `chmod u+w "${diagnosis.parentDir}"`;
+  }
+  return `chmod u+w "${diagnosis.filePath}"`;
+}
+var FilePermissionError = class extends Error {
+  code = "EACCES";
+  filePath;
+  diagnosis;
+  suggestedFixCommand;
+  constructor(filePath, diagnosis) {
+    const resolved = diagnosis ?? inspectFileAccess(filePath);
+    const reason = buildDiagnosisReason(resolved);
+    super(`Cannot write to ${filePath} (${reason})`);
+    this.name = "FilePermissionError";
+    this.filePath = filePath;
+    this.diagnosis = resolved;
+    this.suggestedFixCommand = buildSuggestedFix(resolved);
+  }
+};
+
+// src/domains/fs/safe-file-writer.ts
+function safeWriteFileSync(filePath, content, options) {
+  const chmodFunction = options?.chmodImpl ?? chmodSync;
+  try {
+    writeFileSync(filePath, content, "utf-8");
+    return { strategy: "direct", previousOwnerUid: null };
+  } catch (error) {
+    const nodeError = error;
+    if (nodeError.code !== "EACCES" && nodeError.code !== "EPERM") {
+      throw error;
+    }
+  }
+  const diagnosis = inspectFileAccess(filePath);
+  if (diagnosis.exists && diagnosis.ownedByCurrentUser && !diagnosis.immutableFlag) {
+    try {
+      const targetMode = (diagnosis.mode ?? 420) | 128;
+      chmodFunction(filePath, targetMode);
+      writeFileSync(filePath, content, "utf-8");
+      return { strategy: "chmod", previousOwnerUid: diagnosis.ownerUid };
+    } catch {
+    }
+  }
+  if (diagnosis.exists && diagnosis.dirWritable && !diagnosis.immutableFlag) {
+    const tempPath = `${filePath}.groove-tmp-${process.pid}-${Date.now()}`;
+    try {
+      const preservedMode = (diagnosis.mode ?? 420) | 128;
+      writeFileSync(tempPath, content, { encoding: "utf-8", mode: preservedMode });
+      renameSync(tempPath, filePath);
+      return { strategy: "replaced", previousOwnerUid: diagnosis.ownerUid };
+    } catch {
+      if (existsSync4(tempPath)) {
+        try {
+          rmSync(tempPath, { force: true });
+        } catch {
+        }
+      }
+    }
+  }
+  throw new FilePermissionError(filePath, diagnosis);
+}
+
 // src/domains/adapters/skill-reference-builder.ts
 function removeExistingPathSafely(path) {
-  const fileExists = existsSync3(path);
+  const fileExists = existsSync5(path);
   if (!fileExists) {
     try {
-      const lstat = lstatSync2(path);
+      const lstat = lstatSync3(path);
       if (lstat.isSymbolicLink()) {
         unlinkSync(path);
       }
@@ -417,13 +615,13 @@ function removeExistingPathSafely(path) {
     return;
   }
   try {
-    const lstat = lstatSync2(path);
+    const lstat = lstatSync3(path);
     if (lstat.isSymbolicLink()) {
       unlinkSync(path);
       return;
     }
     if (lstat.isDirectory()) {
-      rmSync(path, { recursive: true, force: true });
+      rmSync2(path, { recursive: true, force: true });
       return;
     }
     unlinkSync(path);
@@ -431,7 +629,7 @@ function removeExistingPathSafely(path) {
   }
 }
 function extractSkillDescription(canonicalSkillMdPath, fallback) {
-  if (!existsSync3(canonicalSkillMdPath)) {
+  if (!existsSync5(canonicalSkillMdPath)) {
     return fallback;
   }
   try {
@@ -445,8 +643,14 @@ function extractSkillDescription(canonicalSkillMdPath, fallback) {
   }
   return fallback;
 }
-function writeAgentSkillReference(targetPath, agentRelativeSkillsDir, skill) {
+function writeAgentSkillReference(targetPath, agentRelativeSkillsDir, skill, transaction) {
   const agentSkillFolder = join5(targetPath, agentRelativeSkillsDir, skill.directoryName);
+  const targetFile = join5(agentSkillFolder, "SKILL.md");
+  if (transaction) {
+    transaction.recordCreatedDir(join5(targetPath, agentRelativeSkillsDir));
+    transaction.recordCreatedDir(agentSkillFolder);
+    transaction.recordBeforeWrite(targetFile);
+  }
   removeExistingPathSafely(agentSkillFolder);
   mkdirSync(agentSkillFolder, { recursive: true });
   const canonicalSkillMd = join5(getProjectSkillsDir(targetPath), skill.directoryName, "SKILL.md");
@@ -465,16 +669,19 @@ Canonical skill specification stored in \`.grooveskills/\`.
 
 > **Instruction**: Read \`.grooveskills/skills/${skill.directoryName}/SKILL.md\` before executing tasks matching this skill.
 `;
-  const targetFile = join5(agentSkillFolder, "SKILL.md");
-  writeFileSync(targetFile, referenceContent, "utf-8");
+  safeWriteFileSync(targetFile, referenceContent);
   return targetFile;
 }
-function writeCursorRuleReference(targetPath, cursorRelativeRulesDir, skill) {
+function writeCursorRuleReference(targetPath, cursorRelativeRulesDir, skill, transaction) {
   const rulesDir = join5(targetPath, cursorRelativeRulesDir);
-  if (!existsSync3(rulesDir)) {
+  const targetFile = join5(rulesDir, `${skill.id}.mdc`);
+  if (transaction) {
+    transaction.recordCreatedDir(rulesDir);
+    transaction.recordBeforeWrite(targetFile);
+  }
+  if (!existsSync5(rulesDir)) {
     mkdirSync(rulesDir, { recursive: true });
   }
-  const targetFile = join5(rulesDir, `${skill.id}.mdc`);
   removeExistingPathSafely(targetFile);
   const canonicalSkillMd = join5(getProjectSkillsDir(targetPath), skill.directoryName, "SKILL.md");
   const description = extractSkillDescription(canonicalSkillMd, skill.description);
@@ -493,7 +700,7 @@ Canonical rule specification stored in \`.grooveskills/\`.
 
 > **Instruction**: Read \`.grooveskills/skills/${skill.directoryName}/SKILL.md\` before executing tasks matching this rule.
 `;
-  writeFileSync(targetFile, referenceContent, "utf-8");
+  safeWriteFileSync(targetFile, referenceContent);
   return targetFile;
 }
 
@@ -502,8 +709,8 @@ var AntigravityAdapter = class {
   id = "antigravity";
   name = "Antigravity";
   targetRelativeDir = ".agents/skills";
-  async installSkill(targetPath, skill, _skillSourceDir) {
-    const file = writeAgentSkillReference(targetPath, this.targetRelativeDir, skill);
+  async installSkill(targetPath, skill, _skillSourceDir, transaction) {
+    const file = writeAgentSkillReference(targetPath, this.targetRelativeDir, skill, transaction);
     return [file];
   }
 };
@@ -513,8 +720,8 @@ var ClaudeAdapter = class {
   id = "claude";
   name = "Claude Code";
   targetRelativeDir = ".claude/skills";
-  async installSkill(targetPath, skill, _skillSourceDir) {
-    const file = writeAgentSkillReference(targetPath, this.targetRelativeDir, skill);
+  async installSkill(targetPath, skill, _skillSourceDir, transaction) {
+    const file = writeAgentSkillReference(targetPath, this.targetRelativeDir, skill, transaction);
     return [file];
   }
 };
@@ -524,8 +731,8 @@ var CursorAdapter = class {
   id = "cursor";
   name = "Cursor";
   targetRelativeDir = ".cursor/rules";
-  async installSkill(targetPath, skill, _skillSourceDir) {
-    const file = writeCursorRuleReference(targetPath, this.targetRelativeDir, skill);
+  async installSkill(targetPath, skill, _skillSourceDir, transaction) {
+    const file = writeCursorRuleReference(targetPath, this.targetRelativeDir, skill, transaction);
     return [file];
   }
 };
@@ -535,38 +742,38 @@ var GeminiAdapter = class {
   id = "gemini";
   name = "Gemini Code Assist";
   targetRelativeDir = ".gemini/skills";
-  async installSkill(targetPath, skill, _skillSourceDir) {
-    const file = writeAgentSkillReference(targetPath, this.targetRelativeDir, skill);
+  async installSkill(targetPath, skill, _skillSourceDir, transaction) {
+    const file = writeAgentSkillReference(targetPath, this.targetRelativeDir, skill, transaction);
     return [file];
   }
 };
 
 // src/domains/project-store/sync-project-store.ts
-import { cpSync, existsSync as existsSync5, mkdirSync as mkdirSync2, rmSync as rmSync2 } from "fs";
+import { cpSync, existsSync as existsSync7, mkdirSync as mkdirSync2, rmSync as rmSync3 } from "fs";
 import { join as join7 } from "path";
 
 // src/domains/installer/resolve-skills-source.ts
 import { fileURLToPath } from "url";
-import { dirname, resolve, join as join6 } from "path";
-import { existsSync as existsSync4 } from "fs";
+import { dirname as dirname2, resolve, join as join6 } from "path";
+import { existsSync as existsSync6 } from "fs";
 function resolveSkillsSourceRoot() {
   const currentFilePath = fileURLToPath(import.meta.url);
-  const currentDir = dirname(currentFilePath);
+  const currentDir = dirname2(currentFilePath);
   const candidateFromDist = resolve(currentDir, "../skills");
-  if (existsSync4(candidateFromDist)) {
+  if (existsSync6(candidateFromDist)) {
     return candidateFromDist;
   }
   const candidateFromSrc = resolve(currentDir, "../../../skills");
-  if (existsSync4(candidateFromSrc)) {
+  if (existsSync6(candidateFromSrc)) {
     return candidateFromSrc;
   }
   let searchDir = currentDir;
-  for (let i = 0; i < 5; i++) {
+  for (let depth = 0; depth < 5; depth++) {
     const candidate = join6(searchDir, "skills");
-    if (existsSync4(candidate)) {
+    if (existsSync6(candidate)) {
       return candidate;
     }
-    const parent = dirname(searchDir);
+    const parent = dirname2(searchDir);
     if (parent === searchDir) {
       break;
     }
@@ -578,16 +785,19 @@ function resolveSkillsSourceRoot() {
 }
 
 // src/domains/project-store/sync-project-store.ts
-function syncProjectStore(targetPath, selectedSkillIds, _selectedAgents) {
+function syncProjectStore(targetPath, selectedSkillIds, _selectedAgents, transaction) {
   const bundledSkillsDir = resolveSkillsSourceRoot();
   const projectSkillsDir = getProjectSkillsDir(targetPath);
-  if (!existsSync5(projectSkillsDir)) {
+  if (transaction) {
+    transaction.recordCreatedDir(projectSkillsDir);
+  }
+  if (!existsSync7(projectSkillsDir)) {
     mkdirSync2(projectSkillsDir, { recursive: true });
   }
   const legacyCursorRules = join7(targetPath, ".grooveskills", "cursor-rules");
-  if (existsSync5(legacyCursorRules)) {
+  if (existsSync7(legacyCursorRules)) {
     try {
-      rmSync2(legacyCursorRules, { recursive: true, force: true });
+      rmSync3(legacyCursorRules, { recursive: true, force: true });
     } catch {
     }
   }
@@ -598,14 +808,17 @@ function syncProjectStore(targetPath, selectedSkillIds, _selectedAgents) {
     }
     const sourceSkillDir = join7(bundledSkillsDir, skill.directoryName);
     const destSkillDir = join7(projectSkillsDir, skill.directoryName);
-    if (existsSync5(sourceSkillDir)) {
+    if (transaction) {
+      transaction.recordCreatedDir(destSkillDir);
+    }
+    if (existsSync7(sourceSkillDir)) {
       cpSync(sourceSkillDir, destSkillDir, { recursive: true });
     }
   }
 }
 
 // src/domains/harness/install-harness.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync10, mkdirSync as mkdirSync3 } from "fs";
 import { join as join10 } from "path";
 
 // src/domains/harness/harness-languages.ts
@@ -654,14 +867,14 @@ var SUPPORTED_LANGUAGES = {
 
 // src/domains/harness/harness-templates.ts
 function buildContextTemplate(detectedDependencies, language = "es", profile) {
-  const depsFormatted = detectedDependencies.length > 0 ? detectedDependencies.map((d) => `- \`${d}\``).join("\n") : "- (No external dependencies detected)";
-  const langConfig = SUPPORTED_LANGUAGES[language];
+  const dependenciesFormatted = detectedDependencies.length > 0 ? detectedDependencies.map((dependencyName) => `- \`${dependencyName}\``).join("\n") : "- (No external dependencies detected)";
+  const languageConfig = SUPPORTED_LANGUAGES[language];
   const projectName = profile?.projectName ?? "Project";
-  const pkgManager = profile?.packageManager ?? "npm";
+  const packageManager = profile?.packageManager ?? "npm";
   const commandLines = [];
   if (profile?.commands) {
-    for (const [key, cmd] of Object.entries(profile.commands)) {
-      commandLines.push(`- **${key}**: \`${cmd}\``);
+    for (const [commandKey, commandValue] of Object.entries(profile.commands)) {
+      commandLines.push(`- **${commandKey}**: \`${commandValue}\``);
     }
   }
   const commandsSection = commandLines.length > 0 ? commandLines.join("\n") : `- Build: Refer to \`package.json\` scripts.
@@ -669,62 +882,62 @@ function buildContextTemplate(detectedDependencies, language = "es", profile) {
 - Tests: Refer to test runner configuration.`;
   const aliasLines = [];
   if (profile?.pathAliases) {
-    for (const [alias, target] of Object.entries(profile.pathAliases)) {
-      aliasLines.push(`- \`${alias}\` -> \`${target}\``);
+    for (const [aliasPattern, aliasTarget] of Object.entries(profile.pathAliases)) {
+      aliasLines.push(`- \`${aliasPattern}\` -> \`${aliasTarget}\``);
     }
   }
   const aliasesSection = aliasLines.length > 0 ? `
 ### Path Aliases
 ${aliasLines.join("\n")}
 ` : "";
-  const dirLines = [];
+  const directoryLines = [];
   if (profile?.sourceDirectories && profile.sourceDirectories.length > 0) {
-    for (const dir of profile.sourceDirectories) {
-      dirLines.push(`- \`${dir}/\``);
+    for (const directoryName of profile.sourceDirectories) {
+      directoryLines.push(`- \`${directoryName}/\``);
     }
   }
-  const dirsSection = dirLines.length > 0 ? `
+  const directoriesSection = directoryLines.length > 0 ? `
 ### Source Modules
-${dirLines.join("\n")}
+${directoryLines.join("\n")}
 ` : "";
   return `# Project Context & Architecture: ${projectName}
 
 This file provides AI agents with instant architectural orientation for this project.
 
 ## 1. Stack & Dependencies
-- **Package Manager**: \`${pkgManager}\`
-${depsFormatted}
+- **Package Manager**: \`${packageManager}\`
+${dependenciesFormatted}
 
 ## 2. Directory Structure Conventions
 - Follow single-responsibility per file (<200 lines).
 - Maintain direct imports with path aliases; avoid barrel files.
 - Keep domain boundaries explicit and clean.
-${aliasesSection}${dirsSection}
+${aliasesSection}${directoriesSection}
 ## 3. Communication & User Copy Language
-- **Configured Language**: ${langConfig.nativeName} (\`${language}\`).
-- **Policy**: ${langConfig.instruction}
+- **Configured Language**: ${languageConfig.nativeName} (\`${language}\`).
+- **Policy**: ${languageConfig.instruction}
 
 ## 4. Essential Commands
 ${commandsSection}
 `;
 }
 function buildDecisionsTemplate(language = "es") {
-  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-  const langConfig = SUPPORTED_LANGUAGES[language];
+  const currentDate = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const languageConfig = SUPPORTED_LANGUAGES[language];
   return `# Architecture Decision Records (ADR)
 
 An append-only log of significant technical and architectural choices.
 
 | Date | Title | Decision | Reason & Consequences |
 | :--- | :--- | :--- | :--- |
-| ${now} | Adopt GrooveSkills Harness | Initialized \`.grooveskills/\` control plane with ODD | Clean, encapsulated agent memory, 3-lane ODD flow, and ${langConfig.nativeName} copy standard |
+| ${currentDate} | Adopt GrooveSkills Harness | Initialized \`.grooveskills/\` control plane with ODD | Clean, encapsulated agent memory, 3-lane ODD flow, and ${languageConfig.nativeName} copy standard |
 `;
 }
 function buildOnboardingTaskTemplate(projectName = "Project") {
-  const now = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const currentDate = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   return `---
 status: pending
-createdAt: ${now}
+createdAt: ${currentDate}
 ---
 
 # 00 \u2014 Initial Project Onboarding & Architecture Exploration: ${projectName}
@@ -780,7 +993,7 @@ By [Output / Technical Change], [Outcome / Verifiable Behavior] will occur, prov
 `;
 }
 function buildAgentHarnessBlock(language = "es") {
-  const langConfig = SUPPORTED_LANGUAGES[language];
+  const languageConfig = SUPPORTED_LANGUAGES[language];
   return `<!-- grooveskills:harness:start -->
 # GrooveSkills Harness \u2014 Agent Rules & Memory
 
@@ -793,9 +1006,9 @@ This project uses the **GrooveSkills Harness** located in \`.grooveskills/\`.
 - **Lane 2 (Task)**: Direct implementation. Declare Outcome Hypothesis and checklist in \`.grooveskills/memory/tasks/<slug>.md\`. Only check off tasks with observed evidence under \`Evidence\`.
 - **Lane 3 (Spec)**: Ambiguous or high-impact architecture. Clarify and validate the spec in \`.grooveskills/memory/tasks/<slug>.md\` before writing code.
 
-## 2. User Communication Language (${langConfig.nativeName})
-- **Language**: \`${language}\` (${langConfig.nativeName}).
-- **Requirement**: ${langConfig.instruction}
+## 2. User Communication Language (${languageConfig.nativeName})
+- **Language**: \`${language}\` (${languageConfig.nativeName}).
+- **Requirement**: ${languageConfig.instruction}
 
 ## 3. Memory Locations
 - Architecture context: \`.grooveskills/memory/context.md\`
@@ -805,11 +1018,11 @@ This project uses the **GrooveSkills Harness** located in \`.grooveskills/\`.
 }
 
 // src/domains/harness/scan-project-onboarding.ts
-import { existsSync as existsSync6, readdirSync as readdirSync2, readFileSync as readFileSync4 } from "fs";
+import { existsSync as existsSync8, readdirSync as readdirSync2, readFileSync as readFileSync4 } from "fs";
 import { basename, join as join8 } from "path";
 function detectProjectName(targetPath) {
   const packageJsonPath = join8(targetPath, "package.json");
-  if (existsSync6(packageJsonPath)) {
+  if (existsSync8(packageJsonPath)) {
     try {
       const raw = readFileSync4(packageJsonPath, "utf-8");
       const parsed = JSON.parse(raw);
@@ -820,7 +1033,7 @@ function detectProjectName(targetPath) {
     }
   }
   const cargoPath = join8(targetPath, "Cargo.toml");
-  if (existsSync6(cargoPath)) {
+  if (existsSync8(cargoPath)) {
     try {
       const cargoRaw = readFileSync4(cargoPath, "utf-8");
       const nameMatch = cargoRaw.match(/name\s*=\s*"([^"]+)"/);
@@ -831,12 +1044,12 @@ function detectProjectName(targetPath) {
     }
   }
   const pyprojectPath = join8(targetPath, "pyproject.toml");
-  if (existsSync6(pyprojectPath)) {
+  if (existsSync8(pyprojectPath)) {
     try {
-      const pyRaw = readFileSync4(pyprojectPath, "utf-8");
-      const pyMatch = pyRaw.match(/name\s*=\s*"([^"]+)"/);
-      if (pyMatch?.[1]) {
-        return pyMatch[1];
+      const pyprojectRaw = readFileSync4(pyprojectPath, "utf-8");
+      const nameMatch = pyprojectRaw.match(/name\s*=\s*"([^"]+)"/);
+      if (nameMatch?.[1]) {
+        return nameMatch[1];
       }
     } catch {
     }
@@ -844,32 +1057,32 @@ function detectProjectName(targetPath) {
   return basename(targetPath) || "project";
 }
 function detectPackageManager(targetPath) {
-  if (existsSync6(join8(targetPath, "pnpm-lock.yaml"))) {
+  if (existsSync8(join8(targetPath, "pnpm-lock.yaml"))) {
     return "pnpm";
   }
-  if (existsSync6(join8(targetPath, "bun.lockb")) || existsSync6(join8(targetPath, "bun.lock"))) {
+  if (existsSync8(join8(targetPath, "bun.lockb")) || existsSync8(join8(targetPath, "bun.lock"))) {
     return "bun";
   }
-  if (existsSync6(join8(targetPath, "yarn.lock"))) {
+  if (existsSync8(join8(targetPath, "yarn.lock"))) {
     return "yarn";
   }
-  if (existsSync6(join8(targetPath, "package-lock.json"))) {
+  if (existsSync8(join8(targetPath, "package-lock.json"))) {
     return "npm";
   }
-  if (existsSync6(join8(targetPath, "Cargo.lock")) || existsSync6(join8(targetPath, "Cargo.toml"))) {
+  if (existsSync8(join8(targetPath, "Cargo.lock")) || existsSync8(join8(targetPath, "Cargo.toml"))) {
     return "cargo";
   }
-  if (existsSync6(join8(targetPath, "uv.lock"))) {
+  if (existsSync8(join8(targetPath, "uv.lock"))) {
     return "uv";
   }
-  if (existsSync6(join8(targetPath, "poetry.lock"))) {
+  if (existsSync8(join8(targetPath, "poetry.lock"))) {
     return "poetry";
   }
   return "npm";
 }
-function detectCommands(targetPath, pkgManager) {
+function detectCommands(targetPath, packageManager) {
   const packageJsonPath = join8(targetPath, "package.json");
-  if (!existsSync6(packageJsonPath)) {
+  if (!existsSync8(packageJsonPath)) {
     return {};
   }
   try {
@@ -877,7 +1090,7 @@ function detectCommands(targetPath, pkgManager) {
     const parsed = JSON.parse(raw);
     const scripts = parsed.scripts ?? {};
     const commands = {};
-    const runner = pkgManager === "npm" ? "npm run" : pkgManager;
+    const runner = packageManager === "npm" ? "npm run" : packageManager;
     if (scripts.build) {
       commands.build = `${runner} build`;
     }
@@ -904,7 +1117,7 @@ function detectCommands(targetPath, pkgManager) {
 }
 function detectPathAliases(targetPath) {
   const tsconfigPath = join8(targetPath, "tsconfig.json");
-  if (!existsSync6(tsconfigPath)) {
+  if (!existsSync8(tsconfigPath)) {
     return {};
   }
   try {
@@ -912,9 +1125,9 @@ function detectPathAliases(targetPath) {
     const parsed = JSON.parse(raw);
     const paths = parsed.compilerOptions?.paths ?? {};
     const aliases = {};
-    for (const [key, targets] of Object.entries(paths)) {
-      if (Array.isArray(targets) && typeof targets[0] === "string") {
-        aliases[key] = targets[0];
+    for (const [aliasKey, aliasTargets] of Object.entries(paths)) {
+      if (Array.isArray(aliasTargets) && typeof aliasTargets[0] === "string") {
+        aliases[aliasKey] = aliasTargets[0];
       }
     }
     return aliases;
@@ -924,7 +1137,7 @@ function detectPathAliases(targetPath) {
 }
 function detectSourceDirectories(targetPath) {
   const srcPath = join8(targetPath, "src");
-  const scanTarget = existsSync6(srcPath) ? srcPath : targetPath;
+  const scanTarget = existsSync8(srcPath) ? srcPath : targetPath;
   try {
     const entries = readdirSync2(scanTarget, { withFileTypes: true });
     return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).filter((name) => !name.startsWith(".") && name !== "node_modules" && name !== "dist");
@@ -948,53 +1161,76 @@ function scanProjectOnboarding(targetPath) {
 }
 
 // src/domains/harness/upsert-agent-instructions.ts
-import { existsSync as existsSync7, readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync5 } from "fs";
 import { join as join9 } from "path";
 var START_MARKER = "<!-- grooveskills:harness:start -->";
 var END_MARKER = "<!-- grooveskills:harness:end -->";
-function applyHarnessBlock(filePath, language = "es") {
+function writeWithTransaction(filePath, content, transaction) {
+  const outcome = safeWriteFileSync(filePath, content);
+  if (outcome.strategy === "replaced" && transaction) {
+    transaction.recordReplacedFile(filePath, outcome.previousOwnerUid);
+  }
+}
+function applyHarnessBlock(filePath, language = "es", transaction) {
+  if (transaction) {
+    transaction.recordBeforeWrite(filePath);
+  }
   const block = buildAgentHarnessBlock(language);
-  if (!existsSync7(filePath)) {
-    writeFileSync2(filePath, `${block}
-`, "utf-8");
+  if (!existsSync9(filePath)) {
+    writeWithTransaction(filePath, `${block}
+`, transaction);
     return;
   }
   const existingContent = readFileSync5(filePath, "utf-8");
   if (existingContent.includes(START_MARKER) && existingContent.includes(END_MARKER)) {
     const regex = new RegExp(`${START_MARKER}[\\s\\S]*?${END_MARKER}`, "g");
     const updated = existingContent.replace(regex, block);
-    writeFileSync2(filePath, updated, "utf-8");
+    writeWithTransaction(filePath, updated, transaction);
     return;
   }
   const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
-  writeFileSync2(filePath, `${existingContent}${separator}${block}
-`, "utf-8");
+  writeWithTransaction(filePath, `${existingContent}${separator}${block}
+`, transaction);
 }
-function upsertAgentInstructions(targetPath, selectedAgents, language = "es") {
+function upsertAgentInstructions(targetPath, selectedAgents, language = "es", transaction) {
   const updatedFiles = [];
   const agentsMdPath = join9(targetPath, "AGENTS.md");
-  applyHarnessBlock(agentsMdPath, language);
+  applyHarnessBlock(agentsMdPath, language, transaction);
   updatedFiles.push(agentsMdPath);
   if (selectedAgents.includes("claude")) {
     const claudeMdPath = join9(targetPath, "CLAUDE.md");
-    applyHarnessBlock(claudeMdPath, language);
+    applyHarnessBlock(claudeMdPath, language, transaction);
     updatedFiles.push(claudeMdPath);
   }
   return updatedFiles;
 }
 
 // src/domains/harness/install-harness.ts
+function writeTrackedFile(filePath, content, transaction) {
+  if (transaction) {
+    transaction.recordBeforeWrite(filePath);
+  }
+  const outcome = safeWriteFileSync(filePath, content);
+  if (outcome.strategy === "replaced" && transaction) {
+    transaction.recordReplacedFile(filePath, outcome.previousOwnerUid);
+  }
+}
 function installHarness(options) {
   const memoryDir = getProjectMemoryDir(options.targetPath);
   const tasksDir = getProjectTasksDir(options.targetPath);
   const language = options.language ?? "es";
   const forceOnboarding = Boolean(options.forceOnboarding);
-  if (!existsSync8(tasksDir)) {
+  const transaction = options.transaction;
+  if (transaction) {
+    transaction.recordCreatedDir(memoryDir);
+    transaction.recordCreatedDir(tasksDir);
+  }
+  if (!existsSync10(tasksDir)) {
     mkdirSync3(tasksDir, { recursive: true });
   }
   const createdFiles = [];
   const contextPath = join10(memoryDir, "context.md");
-  const shouldWriteContext = !existsSync8(contextPath) || forceOnboarding;
+  const shouldWriteContext = !existsSync10(contextPath) || forceOnboarding;
   if (shouldWriteContext) {
     const profile = scanProjectOnboarding(options.targetPath);
     const contextContent = buildContextTemplate(
@@ -1002,30 +1238,31 @@ function installHarness(options) {
       language,
       profile
     );
-    writeFileSync3(contextPath, contextContent, "utf-8");
+    writeTrackedFile(contextPath, contextContent, transaction);
     createdFiles.push(contextPath);
     const onboardingTaskPath = join10(tasksDir, "00-onboarding.md");
-    writeFileSync3(
+    writeTrackedFile(
       onboardingTaskPath,
       buildOnboardingTaskTemplate(profile.projectName),
-      "utf-8"
+      transaction
     );
     createdFiles.push(onboardingTaskPath);
   }
   const decisionsPath = join10(memoryDir, "decisions.md");
-  if (!existsSync8(decisionsPath)) {
-    writeFileSync3(decisionsPath, buildDecisionsTemplate(language), "utf-8");
+  if (!existsSync10(decisionsPath)) {
+    writeTrackedFile(decisionsPath, buildDecisionsTemplate(language), transaction);
     createdFiles.push(decisionsPath);
   }
   const templateTaskPath = join10(tasksDir, "_template.md");
-  if (!existsSync8(templateTaskPath)) {
-    writeFileSync3(templateTaskPath, buildTaskTemplate(), "utf-8");
+  if (!existsSync10(templateTaskPath)) {
+    writeTrackedFile(templateTaskPath, buildTaskTemplate(), transaction);
     createdFiles.push(templateTaskPath);
   }
   const instructions = upsertAgentInstructions(
     options.targetPath,
     options.selectedAgents,
-    language
+    language,
+    transaction
   );
   createdFiles.push(...instructions);
   return {
@@ -1035,14 +1272,14 @@ function installHarness(options) {
 }
 
 // src/domains/harness/write-project-config.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync6 } from "fs";
 function readExistingConfig(configPath) {
   const fallback = {
     skills: [],
     agents: [],
     harness: false
   };
-  if (!existsSync9(configPath)) {
+  if (!existsSync11(configPath)) {
     return fallback;
   }
   try {
@@ -1058,8 +1295,11 @@ function readExistingConfig(configPath) {
     return fallback;
   }
 }
-function writeProjectConfig(targetPath, newSkills, newAgents, harnessEnabled, language) {
+function writeProjectConfig(targetPath, newSkills, newAgents, harnessEnabled, language, transaction) {
   const configPath = getProjectConfigPath(targetPath);
+  if (transaction) {
+    transaction.recordBeforeWrite(configPath);
+  }
   const existing = readExistingConfig(configPath);
   const mergedSkills = Array.from(/* @__PURE__ */ new Set([...existing.skills, ...newSkills]));
   const mergedAgents = Array.from(/* @__PURE__ */ new Set([...existing.agents, ...newAgents]));
@@ -1073,11 +1313,164 @@ function writeProjectConfig(targetPath, newSkills, newAgents, harnessEnabled, la
     skills: mergedSkills,
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  writeFileSync4(configPath, `${JSON.stringify(config, null, 2)}
-`, "utf-8");
+  const outcome = safeWriteFileSync(configPath, `${JSON.stringify(config, null, 2)}
+`);
+  if (outcome.strategy === "replaced" && transaction) {
+    transaction.recordReplacedFile(configPath, outcome.previousOwnerUid);
+  }
   return configPath;
 }
 
+// src/domains/fs/install-transaction.ts
+import { existsSync as existsSync12, readdirSync as readdirSync3, readFileSync as readFileSync7, rmSync as rmSync4 } from "fs";
+var InstallTransaction = class {
+  originalFiles = /* @__PURE__ */ new Map();
+  createdDirs = [];
+  replacedFiles = [];
+  recordBeforeWrite(filePath) {
+    if (this.originalFiles.has(filePath)) {
+      return;
+    }
+    if (existsSync12(filePath)) {
+      try {
+        this.originalFiles.set(filePath, readFileSync7(filePath, "utf-8"));
+      } catch {
+        this.originalFiles.set(filePath, null);
+      }
+    } else {
+      this.originalFiles.set(filePath, null);
+    }
+  }
+  recordCreatedDir(dirPath) {
+    if (!existsSync12(dirPath) && !this.createdDirs.includes(dirPath)) {
+      this.createdDirs.push(dirPath);
+    }
+  }
+  recordReplacedFile(filePath, previousOwnerUid) {
+    if (!this.replacedFiles.some((item) => item.filePath === filePath)) {
+      this.replacedFiles.push({ filePath, previousOwnerUid });
+    }
+  }
+  getReplacedFiles() {
+    return [...this.replacedFiles];
+  }
+  rollback() {
+    const restoredFiles = [];
+    const removedFiles = [];
+    const removedDirs = [];
+    const failures = [];
+    for (const [filePath, content] of this.originalFiles.entries()) {
+      try {
+        if (content === null) {
+          if (existsSync12(filePath)) {
+            rmSync4(filePath, { force: true });
+            removedFiles.push(filePath);
+          }
+          continue;
+        }
+        if (existsSync12(filePath)) {
+          try {
+            const currentContent = readFileSync7(filePath, "utf-8");
+            if (currentContent === content) {
+              continue;
+            }
+          } catch {
+          }
+        }
+        safeWriteFileSync(filePath, content);
+        restoredFiles.push(filePath);
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        failures.push({ path: filePath, reason });
+      }
+    }
+    const sortedDirs = [...this.createdDirs].sort(
+      (firstDir, secondDir) => secondDir.length - firstDir.length
+    );
+    for (const directoryPath of sortedDirs) {
+      try {
+        if (existsSync12(directoryPath) && readdirSync3(directoryPath).length === 0) {
+          rmSync4(directoryPath, { recursive: true, force: true });
+          removedDirs.push(directoryPath);
+        }
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        failures.push({ path: directoryPath, reason });
+      }
+    }
+    return {
+      restoredFiles,
+      removedFiles,
+      removedDirs,
+      failures,
+      isClean: failures.length === 0
+    };
+  }
+};
+
+// src/domains/fs/preflight-write-check.ts
+import { join as join11 } from "path";
+function canRecoverOrWriteTarget(filePath) {
+  const diagnosis = inspectFileAccess(filePath);
+  if (diagnosis.immutableFlag) {
+    throw new FilePermissionError(filePath, diagnosis);
+  }
+  if (!diagnosis.exists) {
+    if (!diagnosis.dirWritable) {
+      throw new FilePermissionError(filePath, diagnosis);
+    }
+    return;
+  }
+  const ownerWritable = diagnosis.ownedByCurrentUser && ((diagnosis.mode ?? 0) & 128) !== 0;
+  if (ownerWritable) {
+    return;
+  }
+  if (diagnosis.ownedByCurrentUser) {
+    return;
+  }
+  if (diagnosis.dirWritable) {
+    return;
+  }
+  throw new FilePermissionError(filePath, diagnosis);
+}
+function runPreflightWriteCheck(options) {
+  const memoryDir = getProjectMemoryDir(options.targetPath);
+  const tasksDir = getProjectTasksDir(options.targetPath);
+  const candidatePaths = [
+    join11(options.targetPath, "AGENTS.md")
+  ];
+  if (options.selectedAgents.includes("claude")) {
+    candidatePaths.push(join11(options.targetPath, "CLAUDE.md"));
+  }
+  candidatePaths.push(
+    getProjectConfigPath(options.targetPath),
+    join11(memoryDir, "context.md"),
+    join11(memoryDir, "decisions.md"),
+    join11(tasksDir, "00-onboarding.md"),
+    join11(tasksDir, "_template.md")
+  );
+  for (const filePath of candidatePaths) {
+    canRecoverOrWriteTarget(filePath);
+  }
+}
+
+// src/errors/install-transaction-error.ts
+var InstallTransactionError = class extends Error {
+  stage;
+  causeError;
+  rollbackReport;
+  suggestedFix;
+  constructor(options) {
+    const rawMessage = options.cause instanceof Error ? options.cause.message : String(options.cause);
+    super(`Error during stage '${options.stage}': ${rawMessage}`);
+    this.name = "InstallTransactionError";
+    this.stage = options.stage;
+    this.causeError = options.cause;
+    this.rollbackReport = options.rollbackReport;
+    this.suggestedFix = options.suggestedFix;
+  }
+};
+
 // src/domains/installer/install-orchestrator.ts
 var ADAPTER_REGISTRY = {
   antigravity: new AntigravityAdapter(),
@@ -1085,7 +1478,20 @@ var ADAPTER_REGISTRY = {
   cursor: new CursorAdapter(),
   gemini: new GeminiAdapter()
 };
+function formatSuggestedFix(cause) {
+  if (cause instanceof FilePermissionError) {
+    return cause.suggestedFixCommand;
+  }
+  const nodeError = cause;
+  if (nodeError?.code === "EACCES" || nodeError?.code === "EPERM") {
+    if (nodeError.path) {
+      return `chmod u+w "${nodeError.path}"`;
+    }
+  }
+  return void 0;
+}
 async function installSkills(options) {
+  const transaction = new InstallTransaction();
   const skillsToInstall = [...options.selectedSkillIds];
   if (!skillsToInstall.includes("groove-harness")) {
     skillsToInstall.push("groove-harness");
@@ -1093,62 +1499,90 @@ async function installSkills(options) {
   if (!skillsToInstall.includes("odd-ai")) {
     skillsToInstall.push("odd-ai");
   }
-  syncProjectStore(options.targetPath, skillsToInstall, options.selectedAgents);
-  const projectSkillsDir = getProjectSkillsDir(options.targetPath);
-  const createdFiles = [];
-  for (const skillId of skillsToInstall) {
-    const skill = SKILL_CATALOG.find((item) => item.id === skillId);
-    if (!skill) {
-      continue;
-    }
-    const skillSourceDir = join11(projectSkillsDir, skill.directoryName);
-    for (const agentId of options.selectedAgents) {
-      const adapter = ADAPTER_REGISTRY[agentId];
-      if (!adapter) {
+  let currentStage = "Preflight check";
+  try {
+    runPreflightWriteCheck({
+      targetPath: options.targetPath,
+      selectedAgents: options.selectedAgents
+    });
+    currentStage = "Syncing skills store (.grooveskills/skills)";
+    syncProjectStore(options.targetPath, skillsToInstall, options.selectedAgents, transaction);
+    const projectSkillsDir = getProjectSkillsDir(options.targetPath);
+    const createdFiles = [];
+    currentStage = "Configuring agent references (.agents, .claude, etc.)";
+    for (const skillId of skillsToInstall) {
+      const skill = SKILL_CATALOG.find((catalogItem) => catalogItem.id === skillId);
+      if (!skill) {
         continue;
       }
-      const files = await adapter.installSkill(options.targetPath, skill, skillSourceDir);
-      createdFiles.push(...files);
+      const skillSourceDir = join12(projectSkillsDir, skill.directoryName);
+      for (const agentId of options.selectedAgents) {
+        const adapter = ADAPTER_REGISTRY[agentId];
+        if (!adapter) {
+          continue;
+        }
+        const files = await adapter.installSkill(
+          options.targetPath,
+          skill,
+          skillSourceDir,
+          transaction
+        );
+        createdFiles.push(...files);
+      }
     }
+    currentStage = "Installing Groove Harness (context, decisions, tasks, and instructions)";
+    const harnessResult = installHarness({
+      targetPath: options.targetPath,
+      selectedAgents: options.selectedAgents,
+      selectedSkillIds: skillsToInstall,
+      detectedDependencies: options.detectedDependencies || [],
+      language: options.language,
+      forceOnboarding: options.forceOnboarding,
+      transaction
+    });
+    createdFiles.push(...harnessResult.createdFiles);
+    currentStage = "Persisting project configuration (.grooveskills/config.json)";
+    const configPath = writeProjectConfig(
+      options.targetPath,
+      skillsToInstall,
+      options.selectedAgents,
+      true,
+      options.language,
+      transaction
+    );
+    createdFiles.push(configPath);
+    return {
+      installedSkills: skillsToInstall,
+      configuredAgents: options.selectedAgents,
+      createdFiles,
+      harnessInitialized: harnessResult.onboardingInitialized,
+      language: options.language,
+      replacedFiles: transaction.getReplacedFiles()
+    };
+  } catch (cause) {
+    const rollbackReport = transaction.rollback();
+    const suggestedFix = formatSuggestedFix(cause);
+    throw new InstallTransactionError({
+      stage: currentStage,
+      cause,
+      rollbackReport,
+      suggestedFix
+    });
   }
-  const harnessResult = installHarness({
-    targetPath: options.targetPath,
-    selectedAgents: options.selectedAgents,
-    selectedSkillIds: skillsToInstall,
-    detectedDependencies: options.detectedDependencies || [],
-    language: options.language,
-    forceOnboarding: options.forceOnboarding
-  });
-  createdFiles.push(...harnessResult.createdFiles);
-  const configPath = writeProjectConfig(
-    options.targetPath,
-    skillsToInstall,
-    options.selectedAgents,
-    true,
-    options.language
-  );
-  createdFiles.push(configPath);
-  return {
-    installedSkills: skillsToInstall,
-    configuredAgents: options.selectedAgents,
-    createdFiles,
-    harnessInitialized: harnessResult.onboardingInitialized,
-    language: options.language
-  };
 }
 
 // src/domains/ui/render-onboarding-prompt.ts
-import pc2 from "picocolors";
+import picocolors2 from "picocolors";
 function formatOnboardingPrompt(language = "es") {
-  const langConfig = SUPPORTED_LANGUAGES[language] ?? SUPPORTED_LANGUAGES.es;
-  const title = langConfig.onboardingPromptTitle;
-  const prompt = langConfig.onboardingPrompt;
-  const separator = pc2.cyan("\u2500".repeat(60));
+  const languageConfig = SUPPORTED_LANGUAGES[language] ?? SUPPORTED_LANGUAGES.es;
+  const title = languageConfig.onboardingPromptTitle;
+  const prompt = languageConfig.onboardingPrompt;
+  const separator = picocolors2.cyan("\u2500".repeat(60));
   const formattedOutput = [
     separator,
-    pc2.bold(pc2.yellow(title)),
+    picocolors2.bold(picocolors2.yellow(title)),
     "",
-    pc2.green(prompt),
+    picocolors2.green(prompt),
     separator
   ].join("\n");
   return {
@@ -1158,53 +1592,130 @@ function formatOnboardingPrompt(language = "es") {
   };
 }
 
+// src/domains/ui/render-install-report.ts
+import { basename as basename2 } from "path";
+import { userInfo } from "os";
+import * as prompts5 from "@clack/prompts";
+import picocolors3 from "picocolors";
+function getCurrentUsername() {
+  try {
+    return userInfo().username;
+  } catch {
+    return process.env.USER || process.env.LOGNAME || "current user";
+  }
+}
+function formatReplacedFileNotes(replacedFiles = []) {
+  if (replacedFiles.length === 0) {
+    return [];
+  }
+  const currentUser = getCurrentUsername();
+  return replacedFiles.map((replacedItem) => {
+    const fileName = basename2(replacedItem.filePath);
+    const previousOwner = formatOwnerName(replacedItem.previousOwnerUid);
+    return picocolors3.yellow(
+      `Note: ${fileName} was owned by ${previousOwner}. It was replaced atomically and is now owned by ${currentUser}.`
+    );
+  });
+}
+function renderInstallFailure(error) {
+  const { stage, causeError, rollbackReport, suggestedFix } = error;
+  const causeMessage = causeError instanceof Error ? causeError.message : String(causeError);
+  const nothingTouched = rollbackReport.restoredFiles.length === 0 && rollbackReport.removedFiles.length === 0 && rollbackReport.removedDirs.length === 0 && rollbackReport.failures.length === 0;
+  const lines = [
+    `${picocolors3.bold("Failed stage:")}  ${picocolors3.yellow(stage)}`,
+    `${picocolors3.bold("Cause:")}         ${picocolors3.red(causeMessage)}`
+  ];
+  if (nothingTouched) {
+    lines.push(`${picocolors3.bold("Rollback:")}      Nothing to roll back, no files were modified.`);
+  } else {
+    lines.push(
+      "",
+      picocolors3.bold("Rollback summary:"),
+      ` \u2022 Restored files: ${picocolors3.cyan(String(rollbackReport.restoredFiles.length))}`,
+      ` \u2022 Removed temporary files: ${picocolors3.cyan(String(rollbackReport.removedFiles.length))}`,
+      ` \u2022 Removed empty directories: ${picocolors3.cyan(String(rollbackReport.removedDirs.length))}`
+    );
+    if (!rollbackReport.isClean) {
+      lines.push("", picocolors3.red("Rollback was incomplete. These files may need manual review:"));
+      for (const failure of rollbackReport.failures) {
+        lines.push(` \u2022 ${failure.path} (${failure.reason})`);
+      }
+    }
+  }
+  if (suggestedFix) {
+    lines.push(`${picocolors3.bold("Suggested fix:")} ${picocolors3.green(suggestedFix)}`);
+  }
+  prompts5.note(lines.join("\n"), "Installation Aborted");
+  if (!rollbackReport.isClean) {
+    prompts5.outro(
+      picocolors3.red(
+        "Rollback was incomplete. Please review the files listed above and apply the suggested fix."
+      )
+    );
+    return;
+  }
+  prompts5.outro(
+    picocolors3.yellow(
+      nothingTouched ? "No files were modified. Apply the suggested fix and try again." : "Your project was restored to its previous state. Apply the suggested fix and try again."
+    )
+  );
+}
+
 // src/domains/ui/ui-orchestrator.ts
 async function resolveLanguageSelection(harnessExists, configuredLanguage, forceOnboarding) {
   if (harnessExists && !forceOnboarding) {
     return configuredLanguage ?? "es";
   }
-  const langChoice = await promptLanguage(configuredLanguage ?? "es");
-  if (p5.isCancel(langChoice)) {
-    p5.cancel("Installation cancelled. Have a wonderful day!");
+  const languageSelection = await promptLanguage(configuredLanguage ?? "es");
+  if (prompts6.isCancel(languageSelection)) {
+    prompts6.cancel("Installation cancelled. Have a wonderful day!");
     process.exit(0);
   }
-  return langChoice;
+  return languageSelection;
 }
 async function resolveOverwriteConfirmation(targetPath, selectedSkills, selectedAgents) {
   const anyExists = selectedSkills.some((skillId) => {
-    const meta = SKILL_CATALOG.find((s) => s.id === skillId);
-    return meta ? verifySkillExists(targetPath, meta.directoryName, selectedAgents) : false;
+    const skillMetadata = SKILL_CATALOG.find((skill) => skill.id === skillId);
+    return skillMetadata ? verifySkillExists(targetPath, skillMetadata.directoryName, selectedAgents) : false;
   });
   if (!anyExists) {
     return true;
   }
-  const confirm2 = await promptConfirmOverwrite();
-  if (p5.isCancel(confirm2) || !confirm2) {
-    p5.cancel("Installation stopped to protect existing skills.");
+  const overwriteConfirmed = await promptConfirmOverwrite();
+  if (prompts6.isCancel(overwriteConfirmed) || !overwriteConfirmed) {
+    prompts6.cancel("Installation stopped to protect existing skills.");
     process.exit(0);
   }
-  return Boolean(confirm2);
+  return Boolean(overwriteConfirmed);
 }
 async function runInteractiveUi(context, forceOnboarding = false) {
   console.log(renderBanner());
-  p5.intro(pc3.magenta("Welcome to GrooveSkills! Let's tailor your AI agents with clean architectural standards."));
+  prompts6.intro(
+    picocolors4.magenta(
+      "Welcome to GrooveSkills! Let's tailor your AI agents with clean architectural standards."
+    )
+  );
   if (context.detectedDependencies.length > 0) {
-    const harnessInfo = context.harnessExists && !forceOnboarding ? pc3.green(`Active (.grooveskills/memory, lang: ${context.configuredLanguage ?? "es"})`) : pc3.cyan("Will be initialized");
-    p5.note(
-      `Detected dependencies: ${context.detectedDependencies.map((d) => pc3.bold(d)).join(", ")}
-Active AI folders: ${context.detectedAgents.map((a) => pc3.green(a)).join(", ") || "None (will be created)"}
+    const harnessInfo = context.harnessExists && !forceOnboarding ? picocolors4.green(
+      `Active (.grooveskills/memory, lang: ${context.configuredLanguage ?? "es"})`
+    ) : picocolors4.cyan("Will be initialized");
+    const formattedDependencies = context.detectedDependencies.map((dependencyName) => picocolors4.bold(dependencyName)).join(", ");
+    const formattedAgents = context.detectedAgents.map((agentName) => picocolors4.green(agentName)).join(", ") || "None (will be created)";
+    prompts6.note(
+      `Detected dependencies: ${formattedDependencies}
+Active AI folders: ${formattedAgents}
 GrooveSkills Harness: ${harnessInfo}`,
       "Project Environment"
     );
   }
   const selectedSkills = await promptSkills(context.suggestedSkillIds);
-  if (p5.isCancel(selectedSkills)) {
-    p5.cancel("Installation cancelled. Have a wonderful day!");
+  if (prompts6.isCancel(selectedSkills)) {
+    prompts6.cancel("Installation cancelled. Have a wonderful day!");
     process.exit(0);
   }
   const selectedAgents = await promptAgents(context.detectedAgents);
-  if (p5.isCancel(selectedAgents)) {
-    p5.cancel("Installation cancelled. Have a wonderful day!");
+  if (prompts6.isCancel(selectedAgents)) {
+    prompts6.cancel("Installation cancelled. Have a wonderful day!");
     process.exit(0);
   }
   const selectedLanguage = await resolveLanguageSelection(
@@ -1217,37 +1728,59 @@ GrooveSkills Harness: ${harnessInfo}`,
     selectedSkills,
     selectedAgents
   );
-  const s = p5.spinner();
-  s.start("Installing and adapting skills across your configured AI agents...");
-  const result = await installSkills({
-    targetPath: context.targetPath,
-    selectedSkillIds: selectedSkills,
-    selectedAgents,
-    forceOverwrite,
-    enableHarness: true,
-    detectedDependencies: context.detectedDependencies,
-    language: selectedLanguage,
-    forceOnboarding
-  });
-  s.stop(pc3.green("All skills and harness have been successfully configured!"));
-  const harnessStatus = result.harnessInitialized ? pc3.green(`Initialized in .grooveskills/ (Language: ${selectedLanguage})`) : pc3.cyan(`Preserved in .grooveskills/ (Language: ${selectedLanguage})`);
-  p5.note(
-    `Configured skills: ${result.installedSkills.map((s2) => pc3.bold(s2)).join(", ")}
-Target agents: ${result.configuredAgents.map((a) => pc3.cyan(a)).join(", ")}
-GrooveSkills Harness: ${harnessStatus}`,
-    "Installation Summary"
-  );
-  if (result.harnessInitialized) {
-    const promptRender = formatOnboardingPrompt(selectedLanguage);
-    p5.note(
-      pc3.green(promptRender.prompt),
-      promptRender.title
+  const installSpinner = prompts6.spinner();
+  installSpinner.start("Installing and adapting skills across your configured AI agents...");
+  try {
+    const installResult = await installSkills({
+      targetPath: context.targetPath,
+      selectedSkillIds: selectedSkills,
+      selectedAgents,
+      forceOverwrite,
+      enableHarness: true,
+      detectedDependencies: context.detectedDependencies,
+      language: selectedLanguage,
+      forceOnboarding
+    });
+    installSpinner.stop(
+      picocolors4.green("All skills and harness have been successfully configured!")
+    );
+    const harnessStatus = installResult.harnessInitialized ? picocolors4.green(`Initialized in .grooveskills/ (Language: ${selectedLanguage})`) : picocolors4.cyan(`Preserved in .grooveskills/ (Language: ${selectedLanguage})`);
+    const formattedInstalledSkills = installResult.installedSkills.map((skillId) => picocolors4.bold(skillId)).join(", ");
+    const formattedConfiguredAgents = installResult.configuredAgents.map((agentId) => picocolors4.cyan(agentId)).join(", ");
+    const summaryLines = [
+      `Configured skills: ${formattedInstalledSkills}`,
+      `Target agents: ${formattedConfiguredAgents}`,
+      `GrooveSkills Harness: ${harnessStatus}`,
+      ...formatReplacedFileNotes(installResult.replacedFiles)
+    ];
+    prompts6.note(summaryLines.join("\n"), "Installation Summary");
+    if (installResult.harnessInitialized) {
+      const promptRender = formatOnboardingPrompt(selectedLanguage);
+      prompts6.note(picocolors4.green(promptRender.prompt), promptRender.title);
+    }
+    prompts6.outro(
+      picocolors4.green(
+        "Your AI programming pair is now empowered with your team's architectural habits! \u{1F680}"
+      )
     );
+  } catch (error) {
+    installSpinner.stop(picocolors4.yellow("Installation could not be completed."));
+    if (error instanceof InstallTransactionError) {
+      renderInstallFailure(error);
+      return;
+    }
+    throw error;
   }
-  p5.outro(pc3.green("Your AI programming pair is now empowered with your team's architectural habits! \u{1F680}"));
 }
 
 // src/main.ts
+function resolveUsername() {
+  try {
+    return userInfo2().username;
+  } catch {
+    return process.env.USER || process.env.LOGNAME || "current user";
+  }
+}
 async function runGrooveSkills(options = {}) {
   const targetPath = process.cwd();
   const context = detectProjectContext(targetPath);
@@ -1267,6 +1800,18 @@ async function runGrooveSkills(options = {}) {
       language,
       forceOnboarding: options.forceOnboarding
     });
+    if (result.replacedFiles && result.replacedFiles.length > 0) {
+      const currentUser = resolveUsername();
+      for (const replacedItem of result.replacedFiles) {
+        const fileName = basename3(replacedItem.filePath);
+        const previousOwner = formatOwnerName(replacedItem.previousOwnerUid);
+        console.log(
+          picocolors5.yellow(
+            `Note: ${fileName} was owned by ${previousOwner}. It was replaced atomically and is now owned by ${currentUser}.`
+          )
+        );
+      }
+    }
     if (result.harnessInitialized) {
       const promptRender = formatOnboardingPrompt(language);
       console.log(`
@@ -1279,6 +1824,7 @@ ${promptRender.formattedOutput}
 }
 
 export {
+  InstallTransactionError,
   runGrooveSkills
 };
-//# sourceMappingURL=chunk-HUG3MG3P.js.map
+//# sourceMappingURL=chunk-SP3ESDM5.js.map