fix: resolve PROJECT_ROOT by walking up to pyproject.toml (#5)

## Summary

- Fix PROJECT_ROOT resolution in `qa.py`, `setup.sh`, and `setup.ps1` —
walk up to `pyproject.toml` instead of assuming `SCRIPT_DIR.parent`
- Add `TestProjectRootWalkUp` test class with 5 tests covering scripts/,
.github/scripts/, arbitrary depth, and missing pyproject.toml
- Document as resolved decisions 22 (pull-based sync) and 23
(PROJECT_ROOT bug) in PLAN.md

## Problem

Scripts assumed `PROJECT_ROOT = SCRIPT_DIR.parent` (one level up). When
running from `.github/scripts/` (two levels deep, the synced location in
downstream repos), the parent resolved to `.github/` instead of the repo
root. This broke tool discovery and `cwd` for every subprocess call.

## Fix

Walk up from the script's directory until `pyproject.toml` is found.
Applied consistently to `qa.py`, `setup.sh`, and `setup.ps1`. The
`PROJECT_ROOT` env var override is preserved as an escape hatch.

## Test plan

- [x] `test_qa_from_scripts_dir` — walk-up from scripts/ (one level)
- [x] `test_qa_from_github_scripts_dir` — walk-up from .github/scripts/
(two levels)
- [x] `test_qa_discovers_checks_from_github_scripts` — full orchestrator
with all checks skipped
- [x] `test_no_pyproject_toml_fails` — clear error message when
pyproject.toml is missing
- [x] `test_deeply_nested_scripts` — walk-up from a/b/c/scripts/ (four
levels)

Author: NWarila

PLAN.md

@@ -969,6 +969,20 @@ conflicting — the template dogfoods what the org requires.
 
 21. **VSCode rulers at 120.** Matching ruff `line-length`. The previous 96/98
     rulers were resume-specific and are removed from the org standard.
+22. **Sync is pull-based, not push-based.** Each downstream repo owns a thin
+    workflow that calls `self-update.yml` as a reusable workflow. The template
+    publishes releases; consumers pull when ready. No cross-repo credentials,
+    no PATs, no push permissions. The original `sync-downstream.yml` required a
+    fine-grained PAT (`TEMPLATE_SYNC_PAT`) to clone and push to private
+    downstream repos, which was never configured and is bad practice for a
+    personal org.
+23. **PROJECT_ROOT is resolved by walking up to `pyproject.toml`, not by
+    assuming `SCRIPT_DIR.parent`.** Scripts can live at `scripts/` (one level
+    deep) or `.github/scripts/` (two levels deep). The old `SCRIPT_DIR.parent`
+    assumption resolved to `.github/` when running from the synced location,
+    breaking tool discovery and `cwd` for every subprocess call. The walk-up
+    pattern traverses parent directories until it finds `pyproject.toml`,
+    working from any depth. Applied to `qa.py`, `setup.sh`, and `setup.ps1`.
 
 ## Pilot Migration: `nwarila/resume`
 

scripts/qa.py

@@ -18,7 +18,20 @@
 from pathlib import Path
 
 SCRIPT_DIR = Path(__file__).resolve().parent
-PROJECT_ROOT = SCRIPT_DIR.parent
+
+
+def _find_project_root() -> Path:
+    """Walk up from SCRIPT_DIR to find the directory containing pyproject.toml."""
+    d = SCRIPT_DIR
+    while d != d.parent:
+        if (d / "pyproject.toml").exists():
+            return d
+        d = d.parent
+    print(f"Error: could not find pyproject.toml above {SCRIPT_DIR}", file=sys.stderr)
+    sys.exit(1)
+
+
+PROJECT_ROOT = _find_project_root()
 
 
 # ---------------------------------------------------------------------------

scripts/setup.ps1

@@ -3,7 +3,26 @@
 $ErrorActionPreference = 'Stop'
 
 $ScriptDir = Split-Path -Parent $PSCommandPath
-$ProjectRoot = if ($env:PROJECT_ROOT) { $env:PROJECT_ROOT } else { Split-Path -Parent $ScriptDir }
+
+# Walk up from ScriptDir to find the repo root (where pyproject.toml lives).
+# This works whether the script is at scripts/ or .github/scripts/.
+if ($env:PROJECT_ROOT) {
+    $ProjectRoot = $env:PROJECT_ROOT
+} else {
+    $SearchDir = $ScriptDir
+    $ProjectRoot = $null
+    while ($SearchDir -and $SearchDir -ne (Split-Path -Parent $SearchDir)) {
+        if (Test-Path (Join-Path $SearchDir 'pyproject.toml')) {
+            $ProjectRoot = $SearchDir
+            break
+        }
+        $SearchDir = Split-Path -Parent $SearchDir
+    }
+    if (-not $ProjectRoot) {
+        Write-Error "Could not find pyproject.toml above $ScriptDir"
+        exit 1
+    }
+}
 
 Write-Host "Project root: $ProjectRoot"
 Set-Location $ProjectRoot

scripts/setup.sh

@@ -4,7 +4,25 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+
+# Walk up from SCRIPT_DIR to find the repo root (where pyproject.toml lives).
+# This works whether the script is at scripts/ or .github/scripts/.
+if [ -n "${PROJECT_ROOT:-}" ]; then
+    : # Already set via env var
+else
+    _dir="$SCRIPT_DIR"
+    while [ "$_dir" != "/" ]; do
+        if [ -f "$_dir/pyproject.toml" ]; then
+            PROJECT_ROOT="$_dir"
+            break
+        fi
+        _dir="$(dirname "$_dir")"
+    done
+    if [ -z "${PROJECT_ROOT:-}" ]; then
+        echo "Error: could not find pyproject.toml above $SCRIPT_DIR" >&2
+        exit 1
+    fi
+fi
 
 echo "Project root: ${PROJECT_ROOT}"
 cd "$PROJECT_ROOT"

tests/conftest.py

@@ -113,4 +113,8 @@ def test_main_runs() -> None:
     scripts_dst = tmp_path / "scripts"
     shutil.copytree(scripts_src, scripts_dst)
 
+    # Also copy to .github/scripts/ (simulating the synced path in downstream repos)
+    gh_scripts_dst = tmp_path / ".github" / "scripts"
+    shutil.copytree(scripts_src, gh_scripts_dst)
+
     return tmp_path

tests/test_scripts.py

@@ -12,9 +12,11 @@
 from pathlib import Path
 
 
-def _run_script(project: Path, script_name: str, *extra_args: str) -> subprocess.CompletedProcess[str]:
+def _run_script(
+    project: Path, script_name: str, *extra_args: str, scripts_dir: str = "scripts"
+) -> subprocess.CompletedProcess[str]:
     """Run a check script inside the given project directory."""
-    script = project / "scripts" / script_name
+    script = project / scripts_dir / script_name
     return subprocess.run(  # noqa: S603 - controlled test invocation of local scripts
         [sys.executable, str(script), *extra_args],
         cwd=project,
@@ -151,3 +153,73 @@ def test_skip_flag(self, tmp_project: Path) -> None:
             "package",
         )
         assert "SKIP" in result.stdout
+
+
+class TestProjectRootWalkUp:
+    """Tests that scripts find PROJECT_ROOT from both scripts/ and .github/scripts/.
+
+    Before the fix, scripts assumed PROJECT_ROOT = SCRIPT_DIR.parent (one level
+    up).  This broke when running from .github/scripts/ (two levels deep) because
+    the parent resolved to .github/ instead of the repo root.  The walk-up logic
+    traverses upward until it finds pyproject.toml.
+    """
+
+    def test_qa_from_scripts_dir(self, tmp_project: Path) -> None:
+        """qa.py finds PROJECT_ROOT from the standard scripts/ location."""
+        result = _run_script(tmp_project, "qa.py", "--help")
+        assert result.returncode == 0
+
+    def test_qa_from_github_scripts_dir(self, tmp_project: Path) -> None:
+        """qa.py finds PROJECT_ROOT from the synced .github/scripts/ location."""
+        result = _run_script(tmp_project, "qa.py", "--help", scripts_dir=".github/scripts")
+        assert result.returncode == 0
+
+    def test_qa_discovers_checks_from_github_scripts(self, tmp_project: Path) -> None:
+        """qa.py discovers check_*.py siblings when running from .github/scripts/."""
+        result = _run_script(
+            tmp_project,
+            "qa.py",
+            "--skip",
+            "lint",
+            "--skip",
+            "types",
+            "--skip",
+            "tests",
+            "--skip",
+            "security",
+            "--skip",
+            "spelling",
+            "--skip",
+            "package",
+            scripts_dir=".github/scripts",
+        )
+        # All checks skipped = success; proves the script loaded and found pyproject.toml
+        assert result.returncode == 0
+        assert "SKIP" in result.stdout
+        assert "could not find pyproject.toml" not in result.stderr
+
+    def test_no_pyproject_toml_fails(self, tmp_path: Path) -> None:
+        """qa.py fails with a clear error when pyproject.toml is missing."""
+        scripts_dir = tmp_path / "deep" / "nested" / "scripts"
+        scripts_dir.mkdir(parents=True)
+        source_qa = Path(__file__).resolve().parent.parent / "scripts" / "qa.py"
+        (scripts_dir / "qa.py").write_text(source_qa.read_text())
+
+        result = subprocess.run(  # noqa: S603
+            [sys.executable, str(scripts_dir / "qa.py"), "--help"],
+            cwd=tmp_path,
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode != 0
+        assert "could not find pyproject.toml" in result.stderr
+
+    def test_deeply_nested_scripts(self, tmp_project: Path) -> None:
+        """Walk-up works from an arbitrarily deep location."""
+        import shutil
+
+        deep = tmp_project / "a" / "b" / "c" / "scripts"
+        shutil.copytree(tmp_project / "scripts", deep)
+
+        result = _run_script(tmp_project, "qa.py", "--help", scripts_dir="a/b/c/scripts")
+        assert result.returncode == 0