code-agnostic 0.3.7__tar.gz → 0.3.8__tar.gz

{code_agnostic-0.3.7 → code_agnostic-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-agnostic
-Version: 0.3.7
+Version: 0.3.8
 Summary: Centralized hub for LLM coding config: MCP, skills, rules, and agents.
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -19,6 +19,8 @@ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: jsonschema>=4.0; extra == "dev"
 Requires-Dist: ruff>=0.8.0; extra == "dev"
 Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: types-jsonschema>=4.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
 Dynamic: license-file
 
 # code-agnostic
@@ -115,15 +117,15 @@ code-agnostic apply
 | Native repo config include for workspace `AGENTS.md` | yes | -- | -- | -- |
 | Repo/subdir gets shared workspace instructions today | yes | -- | yes | yes |
 | Nested `AGENTS.md` discovery | -- | yes | yes | -- |
-| Workspace propagation | yes | -- | yes | yes |
+| Workspace propagation | yes | yes | yes | yes |
 | Import from | yes | yes | yes | yes |
 | Interactive import (TUI) | yes | yes | yes | yes |
 
-Cursor workspace propagation is intentionally disabled to avoid duplicate MCP initialization in multi-root workspaces: https://forum.cursor.com/t/mcp-multi-root-workspace-causes-duplicate-mcp-server-initialization-4x-createclient-actions/144003
+Cursor workspace propagation writes repo-local MCP, skills, and agents when those resources exist in the workspace source config.
 
 OpenCode workspace configs include the shared workspace `AGENTS.md` natively via `instructions`, so repos under the workspace get both repo-local and shared workspace instructions. Codex repos receive workspace instructions through a generated `AGENTS.override.md`, which is added to each repo's `.git/info/exclude`. Claude Code receives workspace instructions through generated `CLAUDE.local.md` files, never by editing committed `CLAUDE.md`.
 
-Cursor documents `AGENTS.md` support in project roots and subdirectories. `code-agnostic` still disables Cursor workspace propagation, so it does not copy or link the shared workspace `AGENTS.md` into child repos; Cursor will load repo-local or nested `AGENTS.md` files that already exist in the opened project. Codex documents nested `AGENTS.md` discovery, but not a native config include for an extra workspace file.
+Cursor documents `AGENTS.md` support in project roots and subdirectories. `code-agnostic` does not copy or link the shared workspace `AGENTS.md` into child repos; Cursor will load repo-local or nested `AGENTS.md` files that already exist in the opened project. Codex documents nested `AGENTS.md` discovery, but not a native config include for an extra workspace file.
 
 ## Features
 
@@ -211,9 +213,9 @@ That command should copy the skill into the source of truth and then run the nor
 
 ### Workspaces
 
-Register workspace directories. Workspace rules are compiled into a canonical `AGENTS.md` at the workspace root. Repos keep their own repo-specific `AGENTS.md`; Codex receives the workspace rules through generated, git-excluded `AGENTS.override.md` files, while OpenCode workspace configs reference the shared workspace file through `instructions`. Claude receives generated `CLAUDE.local.md` files and project MCP entries in `~/.claude.json["projects"][absolute_repo_path]["mcpServers"]`. Repo-local app config, skills, and agents are propagated for OpenCode, Codex, and Claude.
+Register workspace directories. Workspace rules are compiled into a canonical `AGENTS.md` at the workspace root. Repos keep their own repo-specific `AGENTS.md`; Codex receives the workspace rules through generated, git-excluded `AGENTS.override.md` files, while OpenCode workspace configs reference the shared workspace file through `instructions`. Claude receives generated `CLAUDE.local.md` files and project MCP entries in `~/.claude.json["projects"][absolute_repo_path]["mcpServers"]`. Repo-local app config, skills, and agents are propagated for OpenCode, Cursor, Codex, and Claude.
 
-`.cursor` workspace propagation is intentionally disabled to avoid duplicate MCP initialization when opening multi-root workspaces in Cursor (related issue: https://forum.cursor.com/t/mcp-multi-root-workspace-causes-duplicate-mcp-server-initialization-4x-createclient-actions/144003).
+Cursor propagation intentionally stays to repo-local MCP, skills, and agents; it does not copy the shared workspace `AGENTS.md` into child repos.
 
 ```bash
 code-agnostic workspaces add --name myproject --path ~/code/myproject

{code_agnostic-0.3.7 → code_agnostic-0.3.8}/README.md

@@ -92,15 +92,15 @@ code-agnostic apply
 | Native repo config include for workspace `AGENTS.md` | yes | -- | -- | -- |
 | Repo/subdir gets shared workspace instructions today | yes | -- | yes | yes |
 | Nested `AGENTS.md` discovery | -- | yes | yes | -- |
-| Workspace propagation | yes | -- | yes | yes |
+| Workspace propagation | yes | yes | yes | yes |
 | Import from | yes | yes | yes | yes |
 | Interactive import (TUI) | yes | yes | yes | yes |
 
-Cursor workspace propagation is intentionally disabled to avoid duplicate MCP initialization in multi-root workspaces: https://forum.cursor.com/t/mcp-multi-root-workspace-causes-duplicate-mcp-server-initialization-4x-createclient-actions/144003
+Cursor workspace propagation writes repo-local MCP, skills, and agents when those resources exist in the workspace source config.
 
 OpenCode workspace configs include the shared workspace `AGENTS.md` natively via `instructions`, so repos under the workspace get both repo-local and shared workspace instructions. Codex repos receive workspace instructions through a generated `AGENTS.override.md`, which is added to each repo's `.git/info/exclude`. Claude Code receives workspace instructions through generated `CLAUDE.local.md` files, never by editing committed `CLAUDE.md`.
 
-Cursor documents `AGENTS.md` support in project roots and subdirectories. `code-agnostic` still disables Cursor workspace propagation, so it does not copy or link the shared workspace `AGENTS.md` into child repos; Cursor will load repo-local or nested `AGENTS.md` files that already exist in the opened project. Codex documents nested `AGENTS.md` discovery, but not a native config include for an extra workspace file.
+Cursor documents `AGENTS.md` support in project roots and subdirectories. `code-agnostic` does not copy or link the shared workspace `AGENTS.md` into child repos; Cursor will load repo-local or nested `AGENTS.md` files that already exist in the opened project. Codex documents nested `AGENTS.md` discovery, but not a native config include for an extra workspace file.
 
 ## Features
 
@@ -188,9 +188,9 @@ That command should copy the skill into the source of truth and then run the nor
 
 ### Workspaces
 
-Register workspace directories. Workspace rules are compiled into a canonical `AGENTS.md` at the workspace root. Repos keep their own repo-specific `AGENTS.md`; Codex receives the workspace rules through generated, git-excluded `AGENTS.override.md` files, while OpenCode workspace configs reference the shared workspace file through `instructions`. Claude receives generated `CLAUDE.local.md` files and project MCP entries in `~/.claude.json["projects"][absolute_repo_path]["mcpServers"]`. Repo-local app config, skills, and agents are propagated for OpenCode, Codex, and Claude.
+Register workspace directories. Workspace rules are compiled into a canonical `AGENTS.md` at the workspace root. Repos keep their own repo-specific `AGENTS.md`; Codex receives the workspace rules through generated, git-excluded `AGENTS.override.md` files, while OpenCode workspace configs reference the shared workspace file through `instructions`. Claude receives generated `CLAUDE.local.md` files and project MCP entries in `~/.claude.json["projects"][absolute_repo_path]["mcpServers"]`. Repo-local app config, skills, and agents are propagated for OpenCode, Cursor, Codex, and Claude.
 
-`.cursor` workspace propagation is intentionally disabled to avoid duplicate MCP initialization when opening multi-root workspaces in Cursor (related issue: https://forum.cursor.com/t/mcp-multi-root-workspace-causes-duplicate-mcp-server-initialization-4x-createclient-actions/144003).
+Cursor propagation intentionally stays to repo-local MCP, skills, and agents; it does not copy the shared workspace `AGENTS.md` into child repos.
 
 ```bash
 code-agnostic workspaces add --name myproject --path ~/code/myproject

{code_agnostic-0.3.7 → code_agnostic-0.3.8}/code_agnostic/__init__.py

@@ -1,3 +1,3 @@
 __all__ = ["__version__"]
 
-__version__ = "0.3.7"
+__version__ = "0.3.8"

{code_agnostic-0.3.7 → code_agnostic-0.3.8}/code_agnostic/agents/codex.py

@@ -69,10 +69,13 @@ def serialize_codex_agent(agent: Agent) -> str:
     description = agent.metadata.description or agent.metadata.name or agent.name
 
     doc = tomlkit.document()
-    doc.add("name", agent.metadata.name or agent.name)
-    doc.add("description", description)
+    doc.add("name", tomlkit.item(agent.metadata.name or agent.name))
+    doc.add("description", tomlkit.item(description))
     if agent.metadata.nickname_candidates:
-        doc.add("nickname_candidates", list(agent.metadata.nickname_candidates))
+        doc.add(
+            "nickname_candidates",
+            tomlkit.item(list(agent.metadata.nickname_candidates)),
+        )
     model = agent.metadata.effective_value("codex", "model")
     if model:
         doc.add("model", model)

{code_agnostic-0.3.7 → code_agnostic-0.3.8}/code_agnostic/apps/app_id.py

@@ -63,7 +63,7 @@ APP_CATALOG: dict[AppId, AppMetadata] = {
         toggleable=True,
         importable=True,
         supports_import_agents=True,
-        supports_workspace_propagation=False,
+        supports_workspace_propagation=True,
         project_dir_name=CURSOR_PROJECT_DIRNAME,
         config_filename=CURSOR_CONFIG_FILENAME,
     ),

{code_agnostic-0.3.7 → code_agnostic-0.3.8}/code_agnostic/apps/claude/service.py

@@ -8,10 +8,6 @@ from code_agnostic.agents.parser import parse_agent
 from code_agnostic.apps.app_id import AppId, app_label
 from code_agnostic.apps.claude.config_repository import ClaudeConfigRepository
 from code_agnostic.apps.claude.mapper import ClaudeMCPMapper
-from code_agnostic.apps.common.compiled_planning import (
-    find_replaceable_symlink_ancestor,
-    plan_owned_compiled_text_action,
-)
 from code_agnostic.apps.common.framework import RegisteredAppConfigService
 from code_agnostic.apps.common.interfaces.mapper import IAppMCPMapper
 from code_agnostic.apps.common.interfaces.repositories import IAppConfigRepository
@@ -135,7 +131,7 @@ class ClaudeConfigService(RegisteredAppConfigService):
         removable_links: list[Path],
     ) -> tuple[list[Action], list[Path], list[str]]:
         compiler = ClaudeSkillCompiler()
-        return self._plan_owned_text_actions(
+        return self._plan_compiled_text_actions(
             sources=sources,
             target_dir=target_dir,
             scope=scope,
@@ -173,7 +169,7 @@ class ClaudeConfigService(RegisteredAppConfigService):
             agent = parse_agent(source)
             return claude_agent_target_path(target_dir, agent), compiler.compile(agent)
 
-        return self._plan_owned_text_actions(
+        return self._plan_compiled_text_actions(
             sources=sources,
             target_dir=target_dir,
             scope=scope,
@@ -186,63 +182,3 @@ class ClaudeConfigService(RegisteredAppConfigService):
             update_detail="update compiled claude agent",
             conflict_message="Claude agent sync skipped (conflict): {target}",
         )
-
-    def _plan_owned_text_actions(
-        self,
-        *,
-        sources: list[Path],
-        target_dir: Path,
-        scope: str,
-        app: str,
-        managed_paths: list[Path],
-        removable_links: list[Path],
-        compile_source,
-        create_detail: str,
-        noop_detail: str,
-        update_detail: str,
-        conflict_message: str,
-    ) -> tuple[list[Action], list[Path], list[str]]:
-        managed_path_set = {path.resolve(strict=False) for path in managed_paths}
-        removable_link_set = {path.resolve(strict=False) for path in removable_links}
-        actions: list[Action] = []
-        desired_paths: list[Path] = []
-        skipped: list[str] = []
-        scheduled_removals: set[Path] = set()
-
-        for source in sources:
-            target, payload = compile_source(source)
-            desired_paths.append(target)
-            replaceable_symlink = find_replaceable_symlink_ancestor(target, target_dir)
-            if (
-                replaceable_symlink is not None
-                and replaceable_symlink not in scheduled_removals
-            ):
-                scheduled_removals.add(replaceable_symlink)
-                removable_link_set.add(replaceable_symlink.resolve(strict=False))
-                actions.append(
-                    Action(
-                        kind=ActionKind.REMOVE_SYMLINK,
-                        path=replaceable_symlink,
-                        status=ActionStatus.REMOVE,
-                        detail=f"replace compiled {scope} symlink",
-                        app=app,
-                        scope=scope,
-                    )
-                )
-            action = plan_owned_compiled_text_action(
-                target=target,
-                payload=payload,
-                managed_paths=managed_path_set,
-                removable_link_paths=removable_link_set,
-                managed_root=target_dir,
-                scope=scope,
-                app=app,
-                create_detail=create_detail,
-                noop_detail=noop_detail,
-                update_detail=update_detail,
-            )
-            actions.append(action)
-            if action.status == ActionStatus.CONFLICT:
-                skipped.append(conflict_message.format(target=target))
-
-        return actions, desired_paths, skipped

code_agnostic-0.3.8/code_agnostic/apps/common/compiled_planning.py

@@ -0,0 +1,115 @@
+from pathlib import Path
+
+from code_agnostic.generated_artifacts import (
+    ArtifactKind,
+    GeneratedArtifact,
+    OwnershipPolicy,
+    plan_generated_artifact,
+)
+from code_agnostic.models import Action
+
+
+def find_replaceable_symlink_ancestor(target: Path, managed_root: Path) -> Path | None:
+    current = target
+    while True:
+        if current.is_symlink() and (
+            current == managed_root or current.is_relative_to(managed_root)
+        ):
+            return current
+        if current.parent == current:
+            return None
+        current = current.parent
+
+
+def plan_compiled_text_action(
+    *,
+    target: Path,
+    payload: str,
+    managed_paths: set[Path],
+    removable_link_paths: set[Path] | None = None,
+    managed_root: Path | None = None,
+    scope: str,
+    app: str,
+    create_detail: str,
+    noop_detail: str,
+    update_detail: str,
+    conflict_detail: str = "non-managed path exists",
+) -> Action:
+    return _plan_text_action(
+        ownership=OwnershipPolicy.MANAGED_REPLACE,
+        target=target,
+        payload=payload,
+        managed_paths=managed_paths,
+        removable_link_paths=removable_link_paths,
+        managed_root=managed_root,
+        scope=scope,
+        app=app,
+        create_detail=create_detail,
+        noop_detail=noop_detail,
+        update_detail=update_detail,
+        conflict_detail=conflict_detail,
+    )
+
+
+def plan_owned_compiled_text_action(
+    *,
+    target: Path,
+    payload: str,
+    managed_paths: set[Path],
+    removable_link_paths: set[Path] | None = None,
+    managed_root: Path | None = None,
+    scope: str,
+    app: str,
+    create_detail: str,
+    noop_detail: str,
+    update_detail: str,
+    conflict_detail: str = "non-managed path exists",
+) -> Action:
+    return _plan_text_action(
+        ownership=OwnershipPolicy.OWNED_ONLY,
+        target=target,
+        payload=payload,
+        managed_paths=managed_paths,
+        removable_link_paths=removable_link_paths,
+        managed_root=managed_root,
+        scope=scope,
+        app=app,
+        create_detail=create_detail,
+        noop_detail=noop_detail,
+        update_detail=update_detail,
+        conflict_detail=conflict_detail,
+    )
+
+
+def _plan_text_action(
+    *,
+    ownership: OwnershipPolicy,
+    target: Path,
+    payload: str,
+    managed_paths: set[Path],
+    removable_link_paths: set[Path] | None,
+    managed_root: Path | None,
+    scope: str,
+    app: str,
+    create_detail: str,
+    noop_detail: str,
+    update_detail: str,
+    conflict_detail: str,
+) -> Action:
+    return plan_generated_artifact(
+        GeneratedArtifact(
+            path=target,
+            kind=ArtifactKind.TEXT,
+            payload=payload,
+            ownership=ownership,
+            managed_root=managed_root,
+            scope=scope,
+            app=app,
+            create_detail=create_detail,
+            noop_detail=noop_detail,
+            update_detail=update_detail,
+            conflict_detail=conflict_detail,
+        ),
+        managed_paths=managed_paths,
+        removable_link_paths=removable_link_paths,
+    )

{code_agnostic-0.3.7 → code_agnostic-0.3.8}/code_agnostic/apps/common/interfaces/repositories.py

@@ -20,6 +20,16 @@ class IAppConfigRepository(ABC):
     def config_path(self) -> Path:
         raise NotImplementedError
 
+    @property
+    @abstractmethod
+    def skills_dir(self) -> Path:
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def agents_dir(self) -> Path:
+        raise NotImplementedError
+
     @abstractmethod
     def load_config(self) -> dict[str, Any]:
         raise NotImplementedError

{code_agnostic-0.3.7 → code_agnostic-0.3.8}/code_agnostic/apps/common/interfaces/service.py

@@ -6,7 +6,6 @@ from typing import Any
 from code_agnostic.apps.app_id import AppId, app_scope
 from code_agnostic.apps.common.compiled_planning import (
     find_replaceable_symlink_ancestor,
-    plan_compiled_text_action,
 )
 from code_agnostic.apps.common.interfaces.mapper import IAppMCPMapper
 from code_agnostic.apps.common.interfaces.repositories import IAppConfigRepository
@@ -18,6 +17,12 @@ from code_agnostic.apps.common.symlink_planning import (
     plan_stale_files_group,
     plan_stale_group,
 )
+from code_agnostic.generated_artifacts import (
+    ArtifactKind,
+    GeneratedArtifact,
+    OwnershipPolicy,
+    plan_generated_artifact,
+)
 from code_agnostic.models import Action, ActionKind, ActionStatus, SyncPlan
 
 
@@ -92,7 +97,10 @@ class IAppConfigService(ABC):
         raise NotImplementedError
 
     def agent_action_removable_links(self, removable_links: list[Path]) -> list[Path]:
-        return []
+        return removable_links
+
+    def compiled_resource_ownership_policy(self) -> OwnershipPolicy:
+        return OwnershipPolicy.OWNED_ONLY
 
     @staticmethod
     def _normalize_managed_group(value: Any) -> dict[str, Any]:
@@ -119,14 +127,18 @@ class IAppConfigService(ABC):
         desired_paths: list[Path] = []
         skipped: list[str] = []
         scheduled_removals: set[Path] = set()
+        ownership = self.compiled_resource_ownership_policy()
 
         for source in sources:
             target, payload = compile_source(source)
             desired_paths.append(target)
             replaceable_symlink = find_replaceable_symlink_ancestor(target, target_dir)
-            if (
-                replaceable_symlink is not None
-                and replaceable_symlink not in scheduled_removals
+            can_replace_symlink = replaceable_symlink is not None and (
+                ownership != OwnershipPolicy.OWNED_ONLY
+                or replaceable_symlink.resolve(strict=False) in removable_link_set
+            )
+            if replaceable_symlink is not None and (
+                can_replace_symlink and replaceable_symlink not in scheduled_removals
             ):
                 scheduled_removals.add(replaceable_symlink)
                 removable_link_set.add(replaceable_symlink.resolve(strict=False))
@@ -140,17 +152,21 @@ class IAppConfigService(ABC):
                         scope=scope,
                     )
                 )
-            action = plan_compiled_text_action(
-                target=target,
-                payload=payload,
+            action = plan_generated_artifact(
+                GeneratedArtifact(
+                    path=target,
+                    kind=ArtifactKind.TEXT,
+                    payload=payload,
+                    ownership=ownership,
+                    managed_root=target_dir,
+                    scope=scope,
+                    app=app,
+                    create_detail=create_detail,
+                    noop_detail=noop_detail,
+                    update_detail=update_detail,
+                ),
                 managed_paths=managed_path_set,
                 removable_link_paths=removable_link_set,
-                managed_root=target_dir,
-                scope=scope,
-                app=app,
-                create_detail=create_detail,
-                noop_detail=noop_detail,
-                update_detail=update_detail,
             )
             actions.append(action)
             if action.status == ActionStatus.CONFLICT:

{code_agnostic-0.3.7 → code_agnostic-0.3.8}/code_agnostic/apps/opencode/service.py

@@ -119,6 +119,8 @@ class OpenCodeConfigService(RegisteredAppConfigService):
         from code_agnostic.errors import InvalidJsonFormatError
         from code_agnostic.utils import read_json_safe
 
+        if self._base_config_path is None:
+            return {}
         if not self._base_config_path.exists():
             return {}
         payload, error = read_json_safe(self._base_config_path)

{code_agnostic-0.3.7 → code_agnostic-0.3.8}/code_agnostic/cli/commands/workspaces.py

@@ -114,12 +114,17 @@ def workspaces_git_exclude(obj: dict[str, str], workspace: str | None) -> None:
         workspace_path = Path(item["path"])
         if not workspace_path.exists() or not workspace_path.is_dir():
             continue
-        entries = exclude_service.compute_entries(item["name"], enabled_apps)
         repos = workspace_service.discover_git_repos(workspace_path)
         for repo in repos:
             git_dir = workspace_service.resolve_git_dir(repo)
             if git_dir is None:
                 continue
+            entries = exclude_service.compute_entries_for_repo(
+                item["name"],
+                enabled_apps,
+                workspace_path=workspace_path,
+                repo_path=repo,
+            )
             exclude_path = git_dir / "info" / "exclude"
             added, changed = ensure_exclude_entries(exclude_path, entries)
             processed += 1

code_agnostic-0.3.8/code_agnostic/generated_artifacts.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from code_agnostic.models import Action, ActionKind, ActionStatus
+
+
+class ArtifactKind(str, Enum):
+    TEXT = "text"
+
+
+class OwnershipPolicy(str, Enum):
+    OWNED_ONLY = "owned_only"
+    MANAGED_REPLACE = "managed_replace"
+    MERGE_NATIVE_CONFIG = "merge_native_config"
+
+
+@dataclass(frozen=True)
+class GeneratedArtifact:
+    path: Path
+    kind: ArtifactKind
+    payload: Any
+    ownership: OwnershipPolicy
+    scope: str
+    app: str
+    create_detail: str
+    noop_detail: str
+    update_detail: str
+    conflict_detail: str = "non-managed path exists"
+    managed_root: Path | None = None
+
+
+def plan_generated_artifact(
+    artifact: GeneratedArtifact,
+    *,
+    managed_paths: set[Path],
+    removable_link_paths: set[Path] | None = None,
+) -> Action:
+    if artifact.kind != ArtifactKind.TEXT:
+        raise NotImplementedError(
+            f"Unsupported generated artifact kind: {artifact.kind}"
+        )
+    if not isinstance(artifact.payload, str):
+        raise TypeError("Text generated artifacts require a string payload")
+
+    managed_path_set = {path.resolve(strict=False) for path in managed_paths}
+    removable = {path.resolve(strict=False) for path in (removable_link_paths or set())}
+    has_symlink_ancestor, is_removable_ancestor = _symlink_ancestor_state(
+        artifact.path, removable, artifact.managed_root
+    )
+
+    if artifact.ownership == OwnershipPolicy.OWNED_ONLY:
+        target_key = artifact.path.resolve(strict=False)
+        is_managed_target = target_key in managed_path_set or _is_under_any(
+            target_key, removable
+        )
+        if not is_managed_target and not is_removable_ancestor:
+            if (
+                not artifact.path.exists()
+                and not artifact.path.is_symlink()
+                and not has_symlink_ancestor
+            ):
+                return _action(artifact, ActionStatus.CREATE, artifact.create_detail)
+            return _action(artifact, ActionStatus.CONFLICT, artifact.conflict_detail)
+
+    return _plan_replace_text_artifact(
+        artifact,
+        has_symlink_ancestor=has_symlink_ancestor,
+        is_removable_ancestor=is_removable_ancestor,
+    )
+
+
+def _is_under_any(path: Path, ancestors: set[Path]) -> bool:
+    return any(
+        path == ancestor or path.is_relative_to(ancestor) for ancestor in ancestors
+    )
+
+
+def _symlink_ancestor_state(
+    target: Path, removable_link_paths: set[Path], managed_root: Path | None
+) -> tuple[bool, bool]:
+    current = target
+    found_symlink = False
+    while True:
+        in_managed_root = managed_root is None or (
+            current == managed_root or current.is_relative_to(managed_root)
+        )
+        if current.is_symlink() and in_managed_root:
+            found_symlink = True
+            if current.resolve(strict=False) in removable_link_paths:
+                return True, True
+        if current.parent == current:
+            return found_symlink, False
+        current = current.parent
+
+
+def _plan_replace_text_artifact(
+    artifact: GeneratedArtifact,
+    *,
+    has_symlink_ancestor: bool,
+    is_removable_ancestor: bool,
+) -> Action:
+    if has_symlink_ancestor and not is_removable_ancestor:
+        return _action(artifact, ActionStatus.CONFLICT, artifact.conflict_detail)
+
+    if not artifact.path.exists() and not artifact.path.is_symlink():
+        return _action(artifact, ActionStatus.CREATE, artifact.create_detail)
+
+    if artifact.path.is_file():
+        existing = artifact.path.read_text(encoding="utf-8")
+        if existing == artifact.payload:
+            return _action(artifact, ActionStatus.NOOP, artifact.noop_detail)
+        return _action(artifact, ActionStatus.UPDATE, artifact.update_detail)
+
+    return _action(artifact, ActionStatus.CONFLICT, artifact.conflict_detail)
+
+
+def _action(
+    artifact: GeneratedArtifact,
+    status: ActionStatus,
+    detail: str,
+) -> Action:
+    return Action(
+        kind=ActionKind.WRITE_TEXT,
+        path=artifact.path,
+        status=status,
+        detail=detail,
+        payload=artifact.payload,
+        app=artifact.app,
+        scope=artifact.scope,
+    )