@pennyfarthing/core 11.4.0 → 12.0.0

package/pennyfarthing-dist/src/pf/tests/test_dist_root.py

@@ -0,0 +1,720 @@
+"""Tests for get_dist_root() unified path resolution.
+
+Stories 120-5, 120-7: Fix npm path resolution assuming monorepo layout.
+
+These tests verify that pennyfarthing-dist/ can be located in both
+monorepo development and npm-installed consumer contexts.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from pf.common.config import get_dist_root
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def monorepo_layout(tmp_path: Path) -> Path:
+    """Create a directory tree simulating monorepo development layout.
+
+    Structure:
+        tmp/
+          pennyfarthing-dist/
+            agents/
+              sm.md
+            workflows/
+              tdd.yaml
+            gates/
+              red-gate.md
+            personas/
+              themes/
+                mash.yaml
+            guides/
+              agent-behavior.md
+            skills/
+              skill-registry.yaml
+            command-registry.yaml
+          .pennyfarthing/   (would be a symlink in real usage)
+    """
+    dist = tmp_path / "pennyfarthing-dist"
+    dist.mkdir()
+
+    # Agents
+    agents = dist / "agents"
+    agents.mkdir()
+    (agents / "sm.md").write_text("# SM Agent\n")
+
+    # Workflows
+    workflows = dist / "workflows"
+    workflows.mkdir()
+    (workflows / "tdd.yaml").write_text("workflow:\n  name: tdd\n")
+
+    # Gates
+    gates = dist / "gates"
+    gates.mkdir()
+    (gates / "red-gate.md").write_text("# Red Gate\n")
+
+    # Personas/themes
+    themes = dist / "personas" / "themes"
+    themes.mkdir(parents=True)
+    (themes / "mash.yaml").write_text("name: mash\n")
+
+    # Guides
+    guides = dist / "guides"
+    guides.mkdir()
+    (guides / "agent-behavior.md").write_text("# Behavior\n")
+
+    # Skills
+    skills = dist / "skills"
+    skills.mkdir()
+    (skills / "skill-registry.yaml").write_text("version: 1\n")
+
+    # Command registry
+    (dist / "command-registry.yaml").write_text("commands: []\n")
+
+    return tmp_path
+
+
+@pytest.fixture
+def npm_layout(tmp_path: Path) -> Path:
+    """Create a directory tree simulating npm-installed consumer project.
+
+    Structure:
+        tmp/
+          .pennyfarthing/
+            config.local.yaml
+          node_modules/
+            @pennyfarthing/
+              core/
+                pennyfarthing-dist/
+                  agents/
+                    sm.md
+                  workflows/
+                    tdd.yaml
+                  gates/
+                    red-gate.md
+                  personas/
+                    themes/
+                      mash.yaml
+                  guides/
+                    agent-behavior.md
+                  skills/
+                    skill-registry.yaml
+                  command-registry.yaml
+    """
+    # Consumer project marker
+    pf_config = tmp_path / ".pennyfarthing"
+    pf_config.mkdir()
+    (pf_config / "config.local.yaml").write_text("theme: mash\n")
+
+    # npm-installed dist
+    dist = (
+        tmp_path
+        / "node_modules"
+        / "@pennyfarthing"
+        / "core"
+        / "pennyfarthing-dist"
+    )
+    dist.mkdir(parents=True)
+
+    # Agents (sm.md must pass validation; others are stubs for cross-ref)
+    agents = dist / "agents"
+    agents.mkdir()
+    (agents / "sm.md").write_text(
+        "# SM Agent\n"
+        "<role>Scrum Master</role>\n"
+        "<critical>Follow workflow</critical>\n"
+        "<helpers>Use haiku subagents</helpers>\n"
+        "<skills>Sprint management</skills>\n"
+    )
+    (agents / "tea.md").write_text("# TEA Agent\n")
+    (agents / "dev.md").write_text("# Dev Agent\n")
+    (agents / "reviewer.md").write_text("# Reviewer Agent\n")
+
+    # Workflows (with full phase data for get_phase_owner tests)
+    workflows = dist / "workflows"
+    workflows.mkdir()
+    (workflows / "tdd.yaml").write_text(
+        "workflow:\n"
+        "  name: tdd\n"
+        "  description: Test-driven development\n"
+        "  phases:\n"
+        "    - name: setup\n"
+        "      agent: sm\n"
+        "    - name: red\n"
+        "      agent: tea\n"
+        "    - name: green\n"
+        "      agent: dev\n"
+        "    - name: review\n"
+        "      agent: reviewer\n"
+        "    - name: finish\n"
+        "      agent: sm\n"
+    )
+
+    # Gates
+    gates = dist / "gates"
+    gates.mkdir()
+    (gates / "red-gate.md").write_text("# Red Gate\n")
+
+    # Personas/themes
+    themes = dist / "personas" / "themes"
+    themes.mkdir(parents=True)
+    (themes / "mash.yaml").write_text("name: mash\nagents:\n  tea:\n    character: Radar\n")
+
+    # Guides
+    guides = dist / "guides"
+    guides.mkdir()
+    (guides / "agent-behavior.md").write_text(
+        "# Behavior Guide\n"
+        "<team-mode>\n"
+        "TeamCreate for team creation. Spawn teammates with Task tool. "
+        "SendMessage for communication. TeamDelete for cleanup.\n"
+        "</team-mode>\n"
+    )
+
+    # Skills
+    skills = dist / "skills"
+    skills.mkdir()
+    (skills / "skill-registry.yaml").write_text(
+        "version: \"1.0.0\"\nskills:\n  pf-testing:\n    name: pf-testing\n"
+    )
+    (skills / "skill-registry.schema.json").write_text('{"type": "object"}')
+
+    # Commands
+    commands = dist / "commands"
+    commands.mkdir()
+    (commands / "example.md").write_text("# Example Command\n")
+
+    # Command registry
+    (dist / "command-registry.yaml").write_text("commands:\n  example:\n    file: example.md\n")
+
+    return tmp_path
+
+
+@pytest.fixture
+def bare_project(tmp_path: Path) -> Path:
+    """Create a directory tree with no pennyfarthing-dist anywhere.
+
+    Structure:
+        tmp/
+          .pennyfarthing/
+            config.local.yaml
+          src/
+            app.py
+    """
+    pf_config = tmp_path / ".pennyfarthing"
+    pf_config.mkdir()
+    (pf_config / "config.local.yaml").write_text("theme: mash\n")
+
+    src = tmp_path / "src"
+    src.mkdir()
+    (src / "app.py").write_text("print('hello')\n")
+
+    return tmp_path
+
+
+# ---------------------------------------------------------------------------
+# AC1: get_dist_root() resolves correctly in both contexts
+# ---------------------------------------------------------------------------
+
+
+class TestGetDistRootMonorepo:
+    """AC1: get_dist_root() in monorepo development layout."""
+
+    def test_finds_pennyfarthing_dist_at_project_root(
+        self, monorepo_layout: Path
+    ) -> None:
+        """Should find pennyfarthing-dist/ directly under project root."""
+        result = get_dist_root(project_root=monorepo_layout)
+        assert result is not None
+        assert result.is_dir()
+        assert result.name == "pennyfarthing-dist"
+        assert result == monorepo_layout / "pennyfarthing-dist"
+
+    def test_returned_path_contains_agents(self, monorepo_layout: Path) -> None:
+        """Resolved dist root should contain expected subdirectories."""
+        result = get_dist_root(project_root=monorepo_layout)
+        assert result is not None
+        assert (result / "agents").is_dir()
+        assert (result / "workflows").is_dir()
+        assert (result / "gates").is_dir()
+
+    def test_returned_path_is_absolute(self, monorepo_layout: Path) -> None:
+        """Resolved path should be absolute, not relative."""
+        result = get_dist_root(project_root=monorepo_layout)
+        assert result is not None
+        assert result.is_absolute()
+
+
+class TestGetDistRootNpm:
+    """AC1/AC5: get_dist_root() in npm-installed consumer project."""
+
+    def test_finds_dist_in_node_modules(self, npm_layout: Path) -> None:
+        """Should find pennyfarthing-dist/ inside node_modules/@pennyfarthing/core/."""
+        result = get_dist_root(project_root=npm_layout)
+        assert result is not None
+        assert result.is_dir()
+        assert result.name == "pennyfarthing-dist"
+
+    def test_npm_path_contains_expected_content(self, npm_layout: Path) -> None:
+        """Resolved npm dist root should contain expected subdirectories."""
+        result = get_dist_root(project_root=npm_layout)
+        assert result is not None
+        assert (result / "agents").is_dir()
+        assert (result / "workflows").is_dir()
+        assert (result / "gates").is_dir()
+        assert (result / "personas" / "themes").is_dir()
+
+    def test_no_symlink_required(self, npm_layout: Path) -> None:
+        """AC5: Should resolve without any symlink workaround."""
+        # Verify no pennyfarthing-dist symlink exists at project root
+        assert not (npm_layout / "pennyfarthing-dist").exists()
+        # But get_dist_root still works
+        result = get_dist_root(project_root=npm_layout)
+        assert result is not None
+        assert result.is_dir()
+
+    def test_npm_returned_path_is_absolute(self, npm_layout: Path) -> None:
+        """Resolved npm path should be absolute."""
+        result = get_dist_root(project_root=npm_layout)
+        assert result is not None
+        assert result.is_absolute()
+
+
+class TestGetDistRootPrecedence:
+    """AC1: Precedence when multiple layouts coexist."""
+
+    def test_prefers_monorepo_over_npm(self, tmp_path: Path) -> None:
+        """When both monorepo and npm layouts exist, prefer monorepo (direct)."""
+        # Create both layouts
+        direct = tmp_path / "pennyfarthing-dist"
+        direct.mkdir()
+        (direct / "agents").mkdir()
+
+        npm = (
+            tmp_path
+            / "node_modules"
+            / "@pennyfarthing"
+            / "core"
+            / "pennyfarthing-dist"
+        )
+        npm.mkdir(parents=True)
+        (npm / "agents").mkdir()
+
+        result = get_dist_root(project_root=tmp_path)
+        assert result is not None
+        # Should prefer the direct monorepo path
+        assert result == direct
+
+
+class TestGetDistRootFromFile:
+    """AC1: Resolution relative to __file__ (inside pennyfarthing-dist/pf/)."""
+
+    def test_resolves_from_file_inside_dist(self, monorepo_layout: Path) -> None:
+        """When called from within pennyfarthing-dist/pf/, should resolve up."""
+        # Simulate a module at pennyfarthing-dist/pf/common/config.py
+        pf_dir = monorepo_layout / "pennyfarthing-dist" / "pf" / "common"
+        pf_dir.mkdir(parents=True)
+
+        # get_dist_root with project_root should still resolve
+        result = get_dist_root(project_root=monorepo_layout)
+        assert result is not None
+        assert result == monorepo_layout / "pennyfarthing-dist"
+
+
+class TestGetDistRootNotFound:
+    """AC1: Behavior when pennyfarthing-dist/ is not found anywhere."""
+
+    def test_returns_none_when_not_found(self, bare_project: Path) -> None:
+        """Should return None when no pennyfarthing-dist/ exists."""
+        result = get_dist_root(project_root=bare_project)
+        assert result is None
+
+    def test_returns_none_for_empty_directory(self, tmp_path: Path) -> None:
+        """Should return None for a totally empty directory."""
+        result = get_dist_root(project_root=tmp_path)
+        assert result is None
+
+    def test_auto_detects_project_root_when_not_given(
+        self, monorepo_layout: Path
+    ) -> None:
+        """When project_root is None, should auto-detect via get_project_root()."""
+        # Patch get_project_root to return our monorepo layout
+        with patch(
+            "pf.common.config.get_project_root", return_value=monorepo_layout
+        ):
+            result = get_dist_root()  # No project_root argument
+            assert result is not None
+            assert result == monorepo_layout / "pennyfarthing-dist"
+
+    def test_returns_none_when_project_root_detection_fails(self) -> None:
+        """Should return None (not raise) when get_project_root() fails.
+
+        Reviewer finding: get_dist_root() propagates FileNotFoundError
+        when project_root is None and get_project_root() raises.
+        Docstring promises None return on failure.
+        """
+        with patch(
+            "pf.common.config.get_project_root",
+            side_effect=FileNotFoundError("no root"),
+        ):
+            result = get_dist_root()  # Should return None, not raise
+            assert result is None
+
+
+# ---------------------------------------------------------------------------
+# AC2: Call sites resolve correctly in npm context
+# These tests call the ACTUAL module functions, not get_dist_root() directly.
+# ---------------------------------------------------------------------------
+
+
+class TestCallSitesNpmResolution:
+    """AC2: Verify actual modules work correctly in npm-installed context.
+
+    These tests import and call the ACTUAL module functions against an
+    npm-layout directory. They fail when modules hardcode
+    `root / "pennyfarthing-dist" / ...` instead of using get_dist_root().
+    """
+
+    def test_agent_validator_finds_agents_in_npm(self, npm_layout: Path) -> None:
+        """agent.run() should find and validate agents in npm layout."""
+        from pf.validate.adapters.agent import run
+
+        report = run(npm_layout, fix=False, strict=False)
+        # Should NOT report "agents directory not found" error
+        has_dir_not_found = any(
+            "not found" in d.lower() for d in report.details
+        )
+        assert not has_dir_not_found, (
+            f"Agent validator failed to find agents in npm layout: {report.details}"
+        )
+        # Should find and validate at least 1 agent file
+        assert report.passed > 0 or report.warnings > 0, (
+            "Agent validator found 0 files in npm layout — call site not refactored"
+        )
+
+    def test_workflow_validator_finds_workflows_in_npm(
+        self, npm_layout: Path
+    ) -> None:
+        """workflow.run() should find and validate workflows in npm layout."""
+        from pf.validate.adapters.workflow import run
+
+        report = run(npm_layout, fix=False, strict=False)
+        has_dir_not_found = any(
+            "not found" in d.lower() for d in report.details
+        )
+        assert not has_dir_not_found, (
+            f"Workflow validator failed to find workflows in npm layout: {report.details}"
+        )
+
+    def test_skill_command_discovers_registry_in_npm(
+        self, npm_layout: Path
+    ) -> None:
+        """skill_command.discover_skill_registry() should find registry in npm."""
+        from pf.validate.adapters.skill_command import discover_skill_registry
+
+        result = discover_skill_registry(npm_layout)
+        assert result is not None, (
+            "discover_skill_registry returned None for npm layout — "
+            "call site not refactored to use get_dist_root()"
+        )
+        assert result.is_file()
+
+    def test_gate_file_resolves_in_npm(self, npm_layout: Path) -> None:
+        """gate_file.resolve_gate_file() should find gates in npm layout."""
+        from pf.handoff.gate_file import resolve_gate_file
+
+        result = resolve_gate_file("gates/red-gate", project_root=npm_layout)
+        assert result.get("status") == "found", (
+            f"resolve_gate_file failed in npm layout: {result}"
+        )
+
+    def test_theme_discovery_includes_npm_path(self, npm_layout: Path) -> None:
+        """themes.discover_all_theme_dirs() should find themes in npm layout."""
+        from pf.common.themes import discover_all_theme_dirs
+
+        dirs = discover_all_theme_dirs(project_root=npm_layout)
+        # Should include the npm-installed themes directory
+        npm_themes = (
+            npm_layout
+            / "node_modules"
+            / "@pennyfarthing"
+            / "core"
+            / "pennyfarthing-dist"
+            / "personas"
+            / "themes"
+        )
+        assert any(d == npm_themes or d.resolve() == npm_themes.resolve() for d in dirs), (
+            f"discover_all_theme_dirs did not include npm themes path. "
+            f"Got: {dirs}"
+        )
+
+    def test_workflow_get_phase_owner_in_npm(self, npm_layout: Path) -> None:
+        """workflow.get_phase_owner() should resolve workflow in npm layout."""
+        from pf.prime.workflow import get_phase_owner
+
+        owner = get_phase_owner("tdd", "red", npm_layout)
+        assert owner == "tea", (
+            f"get_phase_owner returned {owner!r} in npm layout — "
+            "expected 'tea'. Call site not refactored."
+        )
+
+    def test_loader_finds_agent_in_npm(self, npm_layout: Path) -> None:
+        """loader.load_agent_definition() should find agents in npm layout."""
+        from pf.prime.loader import load_agent_definition
+
+        content = load_agent_definition("sm", project_root=npm_layout)
+        assert content is not None, (
+            "load_agent_definition returned None for npm layout — "
+            "call site not refactored to use get_dist_root()"
+        )
+        assert "SM Agent" in content
+
+    def test_loader_finds_behavior_guide_in_npm(self, npm_layout: Path) -> None:
+        """loader.load_behavior_guide() should find guide in npm layout."""
+        from pf.prime.loader import load_behavior_guide
+
+        content = load_behavior_guide(project_root=npm_layout)
+        assert content is not None, (
+            "load_behavior_guide returned None for npm layout — "
+            "call site not refactored to use get_dist_root()"
+        )
+
+    def test_team_mode_validator_finds_guides_in_npm(
+        self, npm_layout: Path
+    ) -> None:
+        """team_mode.run() should find and validate guides in npm layout."""
+        from pf.validate.adapters.team_mode import run
+
+        report = run(npm_layout, fix=False, strict=False)
+        # Should have actually found and validated files (passed > 0),
+        # not just produced an error about missing directories
+        assert report.passed > 0, (
+            f"team_mode validator found 0 valid files in npm layout — "
+            f"call site not refactored. Details: {report.details}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# AC3: Validate reports "0 files found" as warning
+# ---------------------------------------------------------------------------
+
+
+class TestValidateZeroFilesWarning:
+    """AC3: pf validate should warn when 0 files are discovered."""
+
+    def test_agent_validator_warns_on_zero_agents(self, tmp_path: Path) -> None:
+        """Agent validator should warn (not silently pass) when 0 agents found."""
+        from pf.validate.adapters.agent import run
+
+        # Create a pennyfarthing-dist with empty agents dir
+        dist = tmp_path / "pennyfarthing-dist"
+        agents = dist / "agents"
+        agents.mkdir(parents=True)
+
+        report = run(tmp_path, fix=False, strict=False)
+        # With 0 agents, should have a warning — not a clean pass
+        assert report.warnings > 0 or report.errors > 0, (
+            "Validator silently passed with 0 agent files — should warn"
+        )
+
+    def test_workflow_validator_warns_on_zero_workflows(
+        self, tmp_path: Path
+    ) -> None:
+        """Workflow validator should warn when 0 workflow files found."""
+        from pf.validate.adapters.workflow import run
+
+        # Create pennyfarthing-dist with empty workflows dir
+        dist = tmp_path / "pennyfarthing-dist"
+        workflows = dist / "workflows"
+        workflows.mkdir(parents=True)
+        # Also need agents dir for workflow validator
+        (dist / "agents").mkdir()
+
+        report = run(tmp_path, fix=False, strict=False)
+        assert report.warnings > 0 or report.errors > 0, (
+            "Validator silently passed with 0 workflow files — should warn"
+        )
+
+    def test_agent_validator_report_mentions_zero_files(
+        self, tmp_path: Path
+    ) -> None:
+        """Report details should mention that 0 files were found."""
+        from pf.validate.adapters.agent import run
+
+        dist = tmp_path / "pennyfarthing-dist"
+        agents = dist / "agents"
+        agents.mkdir(parents=True)
+
+        report = run(tmp_path, fix=False, strict=False)
+        # Should have a detail mentioning 0 files
+        detail_text = " ".join(report.details).lower()
+        assert "0" in detail_text or "no " in detail_text or "empty" in detail_text, (
+            f"Report details should mention 0 files found, got: {report.details}"
+        )
+
+    def test_zero_files_is_not_success(self, tmp_path: Path) -> None:
+        """A validator with 0 files should NOT report success."""
+        from pf.validate.adapters.agent import run
+
+        dist = tmp_path / "pennyfarthing-dist"
+        agents = dist / "agents"
+        agents.mkdir(parents=True)
+
+        report = run(tmp_path, fix=False, strict=False)
+        # success property is errors == 0, but with 0 files it should
+        # at minimum have a warning
+        assert report.warnings > 0 or not report.success, (
+            "0 files should not produce a clean success report"
+        )
+
+
+# ---------------------------------------------------------------------------
+# AC6: Integration test — npm-installed context
+# ---------------------------------------------------------------------------
+
+
+class TestIntegrationNpmContext:
+    """AC6: End-to-end integration verifying multiple modules in npm context.
+
+    These tests run actual pf operations against the npm-installed layout
+    to verify the full resolution chain works.
+    """
+
+    def test_validate_agent_end_to_end_npm(self, npm_layout: Path) -> None:
+        """Full agent validation should succeed in npm layout."""
+        from pf.validate.adapters.agent import run
+
+        report = run(npm_layout, fix=False, strict=False)
+        # After refactoring, should validate at least 1 agent successfully
+        assert report.passed >= 1, (
+            f"Expected at least 1 agent validated, got {report.passed}. "
+            f"Details: {report.details}"
+        )
+
+    def test_theme_resolution_end_to_end_npm(self, npm_layout: Path) -> None:
+        """Theme resolution should find themes in npm layout."""
+        from pf.common.themes import resolve_theme_path
+
+        result = resolve_theme_path("mash", project_root=npm_layout)
+        assert result is not None, (
+            "resolve_theme_path('mash') returned None in npm layout"
+        )
+        assert result.is_file()
+
+    def test_gate_resolution_end_to_end_npm(self, npm_layout: Path) -> None:
+        """Gate resolution should find built-in gates in npm layout."""
+        from pf.handoff.gate_file import resolve_gate_file
+
+        result = resolve_gate_file("gates/red-gate", project_root=npm_layout)
+        assert result.get("status") == "found", (
+            f"Gate resolution failed in npm layout: {result}"
+        )
+        assert "path" in result
+
+    def test_workflow_phase_lookup_end_to_end_npm(self, npm_layout: Path) -> None:
+        """Workflow phase lookup should resolve in npm layout."""
+        from pf.prime.workflow import get_phase_owner
+
+        # Verify multiple phases resolve correctly
+        assert get_phase_owner("tdd", "red", npm_layout) == "tea"
+        assert get_phase_owner("tdd", "green", npm_layout) == "dev"
+        assert get_phase_owner("tdd", "setup", npm_layout) == "sm"
+
+    def test_skill_registry_end_to_end_npm(self, npm_layout: Path) -> None:
+        """Skill registry discovery should work in npm layout."""
+        from pf.validate.adapters.skill_command import discover_skill_registry
+
+        path = discover_skill_registry(npm_layout)
+        assert path is not None, "Skill registry not found in npm layout"
+        assert path.is_file()
+
+
+# ---------------------------------------------------------------------------
+# Story 120-7: Remaining call sites
+# ---------------------------------------------------------------------------
+
+
+class TestRemainingCallSitesNpmResolution:
+    """Story 120-7: Verify remaining call sites use get_dist_root().
+
+    These cover the 4 modules that were not refactored in 120-5:
+    hooks_installer, cli help, tandem_awareness, statusline.
+    """
+
+    def test_hooks_installer_finds_dist_in_npm(self, npm_layout: Path) -> None:
+        """hooks_installer should find pennyfarthing-dist in npm layout."""
+        from pf.git.hooks_installer import install_git_hooks
+
+        # Create .git/hooks directory structure
+        git_dir = npm_layout / ".git"
+        git_dir.mkdir()
+        hooks_dir = git_dir / "hooks"
+        hooks_dir.mkdir()
+
+        # Create hooks source files and dispatcher template in dist
+        dist = (
+            npm_layout / "node_modules" / "@pennyfarthing" / "core"
+            / "pennyfarthing-dist"
+        )
+        hooks_source = dist / "scripts" / "hooks"
+        hooks_source.mkdir(parents=True)
+        (hooks_source / "dispatcher-template.sh").write_text(
+            "#!/bin/bash\n# __HOOK_NAME__ dispatcher\n"
+        )
+        (hooks_source / "pre-commit.sh").write_text("#!/bin/bash\n# pre-commit\n")
+
+        result = install_git_hooks(project_root=npm_layout)
+        assert result == 0, (
+            "install_git_hooks failed in npm layout — "
+            "call site not refactored to use get_dist_root()"
+        )
+
+    def test_tandem_awareness_finds_agents_in_npm(self, npm_layout: Path) -> None:
+        """tandem_awareness.run() should find agents in npm layout."""
+        from pf.validate.adapters.tandem_awareness import run
+
+        report = run(npm_layout, fix=False, strict=False)
+        has_dir_not_found = any(
+            "not found" in d.lower() for d in report.details
+        )
+        assert not has_dir_not_found, (
+            f"Tandem awareness failed to find agents in npm layout: {report.details}"
+        )
+
+    def test_cli_help_finds_registry_in_npm(self, npm_layout: Path) -> None:
+        """cli help_cmd should find command-registry.yaml in npm layout."""
+        import yaml
+
+        from pf.common.config import get_dist_root
+
+        # Verify the registry is reachable via get_dist_root
+        dist_root = get_dist_root(project_root=npm_layout)
+        assert dist_root is not None
+        registry_path = dist_root / "command-registry.yaml"
+        assert registry_path.is_file(), (
+            "command-registry.yaml not found via get_dist_root in npm layout"
+        )
+        data = yaml.safe_load(registry_path.read_text())
+        assert data is not None
+
+    def test_statusline_theme_resolves_in_npm(self, npm_layout: Path) -> None:
+        """statusline _get_character_display should find theme via dist fallback."""
+        from pf.hooks.statusline import _get_character_display
+
+        # Remove .pennyfarthing/personas/ to simulate npm without symlinks
+        # .pennyfarthing exists (config) but has no personas/themes symlink
+        # So the primary path fails and fallback via get_dist_root should work
+        display, theme_file = _get_character_display(str(npm_layout), "tea")
+        # Should resolve the theme file (even if character isn't found for tea,
+        # theme_file path should point to the dist location)
+        assert theme_file is not None, (
+            "statusline could not resolve theme file in npm layout"
+        )