agent-pmo 0.1.0__py3-none-any.whl

agent_pmo/__init__.py

@@ -0,0 +1,7 @@
+"""agent-pmo: a project management office for AI coding agents (specs, plans, decisions, tests, reviews, releases).
+
+Language-neutral and standard-library only (Python >= 3.11). Everything project-specific lives in the project's
+pm.toml; the kit's documentation is in docs/ (commands.md, configuration.md).
+"""
+
+__version__ = "0.1.0"

agent_pmo/__main__.py

@@ -0,0 +1,22 @@
+"""`agent-pmo` and `python -m agent_pmo`: the command-line entry point (Python >= 3.11, standard library only)."""
+
+import sys
+
+
+def run() -> int:
+    if sys.version_info < (3, 11):
+        sys.exit("agent-pmo needs Python 3.11 or newer (uses tomllib)")
+    if not sys.flags.utf8_mode:
+        import locale
+
+        if locale.getencoding().lower().replace("-", "") != "utf8":  # e.g. Windows code pages: docs are UTF-8 everywhere
+            import subprocess
+
+            return subprocess.call([sys.executable, "-X", "utf8", "-m", "agent_pmo", *sys.argv[1:]])
+    from .cli import main
+
+    return main()
+
+
+if __name__ == "__main__":
+    sys.exit(run())

agent_pmo/adherence.py

@@ -0,0 +1,455 @@
+"""Workflow adherence: did an agent follow every step of a workflow? Checked from the evidence the steps leave behind.
+
+Each check lists the workflow's steps (numbered as in .pm/workflows/<name>.md) with ok, missing or n/a and why. A
+missing step means it was skipped: do it. `report` runs the checks for every unit, backlog fix and change request
+and summarises them; the pre-push hook runs the check matching a pushed unit branch's status.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import gitx, md
+from .config import Config
+
+WORKFLOWS = ("setup", "implement", "test", "review", "change-request", "security", "fix", "oneoff", "adopt", "triage",
+             "discuss", "deploy")  # fmt: skip
+
+
+@dataclass
+class Step:
+    n: str
+    name: str
+    status: str  # ok | missing | n/a
+    detail: str = ""
+
+
+@dataclass
+class Result:
+    workflow: str
+    subject: str
+    steps: list[Step] = field(default_factory=list)
+
+    def add(self, n: str, name: str, ok: bool | None, detail: str = "") -> None:
+        self.steps.append(Step(n, name, "n/a" if ok is None else ("ok" if ok else "missing"), detail))
+
+    @property
+    def missing(self) -> list[Step]:
+        return [s for s in self.steps if s.status == "missing"]
+
+    @property
+    def passed(self) -> bool:
+        return not self.missing
+
+    def text(self) -> str:
+        counted = [s for s in self.steps if s.status != "n/a"]
+        lines = [f"{self.workflow} {self.subject}: {len(counted) - len(self.missing)}/{len(counted)} steps"
+                 + ("" if self.passed else f" — {len(self.missing)} missing (workflows/{self.workflow}.md)")]
+        mark = {"ok": "ok ", "missing": "MISSING", "n/a": "n/a"}
+        lines += [f"  {mark[s.status]:<7} step {s.n} {s.name}" + (f": {s.detail}" if s.detail else "") for s in self.steps]
+        return "\n".join(lines)
+
+
+# ---------------------------------------------------------------- helpers
+
+
+def _unit_commits(cfg: Config, unit: str, trailer: str = "Unit") -> list[dict[str, Any]]:
+    from . import trace
+
+    return [c for c in trace.commits(cfg) if c["trailers"].get(trailer) == unit]
+
+
+def _module(cfg: Config, name: str) -> Any:
+    from . import registry
+
+    mods = registry.load(cfg)
+    if name not in mods:
+        raise ValueError(f"unknown module {name!r}")
+    return mods[name]
+
+
+def _relevant(problems: list[str], *needles: str) -> list[str]:
+    return [p for p in problems if any(n and n in p for n in needles)]
+
+
+# ---------------------------------------------------------------- unit workflows
+
+
+def implement(cfg: Config, module: str, k: int, *, prepush: bool = False) -> Result:
+    from . import checks, coord, registry
+
+    m = _module(cfg, module)
+    inc = m.inc(k)
+    if inc is None:
+        raise ValueError(f"{module} has no increment {k}")
+    r = Result("implement", f"{module} inc {k}")
+    unit = f"{module} inc {k}"
+    commits = _unit_commits(cfg, unit)
+    held = {c.module: c for c in coord.claims(cfg, include_expired=True)} if coord.mode(cfg) != "off" else {}
+    claimed = module in held or any("Agent" in c["trailers"] for c in commits)
+    r.add("1", "claim the module (next implement --claim)", None if coord.mode(cfg) == "off" else claimed,
+          held[module].agent if module in held else ("" if claimed else "no claim and no Agent trailer"))  # fmt: skip
+    branch = gitx.current_branch(cfg.root)
+    pattern = re.compile(rf"^{re.escape(cfg.prefix.lower())}-\d{{4}}-{re.escape(module)}-inc{k}$")
+    on_branch = branch not in ("", "HEAD", cfg.default_branch, cfg.get("git.dev", "dev")) and f"inc{k}" in branch
+    r.add("3", "work on the unit branch <prefix>-NNNN-<module>-inc<k>", bool(pattern.match(branch)) if on_branch else None,
+          branch if on_branch else "")  # fmt: skip
+    files = re.findall(r"^- `([^`]+)`", registry.increment_body(cfg, m, k).split("**Files**", 1)[-1].split("**Tests**", 1)[0],
+                       re.M) if "**Files**" in registry.increment_body(cfg, m, k) else []  # fmt: skip
+    absent = [f for f in files if not (cfg.root / f).exists() and "(planned)" not in f]
+    r.add("4", "create the increment's files", not absent if inc.status != "planned" else None,
+          ("missing: " + ", ".join(absent)) if absent else "")  # fmt: skip
+    r.add("6", "status coded (or later) with every task ticked", inc.status != "planned" and not inc.open_tasks,
+          f"status {inc.status}, {inc.open_tasks} task(s) open")  # fmt: skip
+    ids = {c["trailers"].get("Change-Id") for c in commits}
+    log = (m.folder / "changelog.md").read_text() if (m.folder / "changelog.md").exists() else ""
+    r.add("6", "a changelog row for the unit's change", any(i and f"| {i} |" in log for i in ids),
+          "" if ids else "no commit carries this unit's trailers yet")  # fmt: skip
+    probs = _relevant(checks.run(cfg), m.folder.relative_to(cfg.root).as_posix(), m.dir.relative_to(cfg.root).as_posix(),
+                      f" {module} inc {k}")  # fmt: skip
+    r.add("7", "agent-pmo check clean for this module", not probs, "; ".join(probs[:3]))
+    feature = [c for c in commits if c["trailers"].get("Type") == "feature"]
+    r.add("8", "commit with trailers (Change-Id, Unit, Type feature, Implemented-By)",
+          any("Implemented-By" in c["trailers"] and "Change-Id" in c["trailers"] for c in feature),
+          "" if feature else "no commit with Unit + Type: feature")  # fmt: skip
+    return r
+
+
+def test(cfg: Config, module: str, k: int, *, prepush: bool = False) -> Result:
+    from . import reports
+
+    m = _module(cfg, module)
+    inc = m.inc(k)
+    r = Result("test", f"{module} inc {k}")
+    folder = m.folder / "test"
+    plans = reports.for_unit(reports.numbered(folder, "test_plan"), module, k)
+    reps = reports.for_unit(reports.numbered(folder, "test_report"), module, k)
+    r.add("2", "test plan, filled in", bool(plans) and md.PLACEHOLDER not in plans[-1].read_text(),
+          "" if plans else "no test plan")  # fmt: skip
+    latest = reps[-1].read_text() if reps else ""
+    r.add("6", "PASS test report, filled in (coverage of the plan, bugs found)",
+          "**Result:** PASS" in latest and md.PLACEHOLDER not in latest, "" if reps else "no test report")  # fmt: skip
+    r.add("7", "status tested (or reviewed)", inc.status in ("tested", "reviewed"), f"status {inc.status}")
+    log = (m.folder / "changelog.md").read_text() if (m.folder / "changelog.md").exists() else ""
+    r.add("7", "the changelog links the test report", bool(reps) and f"test/{reps[-1].name}" in log)
+    requests = reports.for_unit(reports.numbered(m.folder / "review", "request"), module, k)
+    r.add("8", "review requested (testing ends by triggering the review)", bool(requests))
+    commits = _unit_commits(cfg, f"{module} inc {k}")
+    r.add("9", "commit with Type: test", any(c["trailers"].get("Type") == "test" for c in commits))
+    return r
+
+
+def review(cfg: Config, module: str, k: int, *, prepush: bool = False) -> Result:
+    from . import review as rv
+    from . import security
+
+    m = _module(cfg, module)
+    inc = m.inc(k)
+    r = Result("review", f"{module} inc {k}")
+    sec = security.latest_module_report(m)
+    sec_text = sec.read_text() if sec else ""
+    r.add("2", "module security report: PASS and assessed", bool(sec) and "**Result:** PASS" in sec_text
+          and md.PLACEHOLDER not in sec_text, "" if sec else "no module security report")  # fmt: skip
+    from . import reports
+
+    r.add("3", "review request filed", bool(reports.for_unit(reports.numbered(m.folder / "review", "request"), module, k)))
+    probs = rv.review_problems(cfg, m, inc) if rv._reviews(m, k) else ["no code review"]
+    independent = [p for p in probs if "authored" in p or "reviewer model" in p]
+    r.add("5", "independent review by a different model (findings with backlog items)",
+          bool(rv._reviews(m, k)) and not independent and not [p for p in probs if "BL-" in p or "finding" in p],
+          "; ".join(probs[:2]))  # fmt: skip
+    from . import coderabbit
+
+    if coderabbit.enabled(cfg):
+        cr = coderabbit.unit_problems(cfg, m, k)
+        r.add("5", "CodeRabbit review fetched and every finding triaged", not cr, "; ".join(cr))
+    r.add("8", "approved as the rules require", bool(rv._reviews(m, k)) and not [p for p in probs if "approv" in p],
+          "; ".join(p for p in probs if "approv" in p)[:200])  # fmt: skip
+    r.add("9", "status reviewed and the changelog links the review", inc.status == "reviewed" and not
+          [p for p in probs if "changelog" in p], f"status {inc.status}")  # fmt: skip
+    commits = _unit_commits(cfg, f"{module} inc {k}")
+    r.add("9", "commit with Type: review and Reviewed-By", any(c["trailers"].get("Type") == "review" and
+                                                              "Reviewed-By" in c["trailers"] for c in commits))  # fmt: skip
+    if prepush or cfg.strategy == "local":
+        r.add("10", "landed (merged into the integration branch)", None if prepush else _landed(cfg, commits))
+    else:
+        r.add("10", "landed (agent PR merged into dev, review PR opened)", _landed(cfg, commits))
+    return r
+
+
+def _landed(cfg: Config, commits: list[dict[str, Any]]) -> bool | None:
+    if not commits:
+        return False
+    target = cfg.default_branch if cfg.strategy == "local" else cfg.get("git.dev", "dev")
+    remote = cfg.get("provider.remote", "origin")
+    for ref in (f"{remote}/{target}", target):
+        if gitx.ok(cfg.root, "rev-parse", "--verify", ref):
+            return gitx.ok(cfg.root, "merge-base", "--is-ancestor", commits[0]["sha"], ref)
+    return None
+
+
+# ---------------------------------------------------------------- other workflows
+
+
+def security_wf(cfg: Config, module: str) -> Result:
+    from . import security
+
+    m = _module(cfg, module)
+    r = Result("security", module)
+    why = security.module_report_problem(cfg, m)
+    r.add("1", "module security report for the current files", not why or "assessment" in why, why)
+    r.add("2", "assessment written", bool(security.latest_module_report(m)) and "assessment" not in why, why if "assessment" in why else "")
+    p = security.latest_module_report(m)
+    r.add("3", "no blocking findings (or accepted risks)", bool(p) and "**Result:** PASS" in p.read_text())
+    return r
+
+
+def change_request(cfg: Config, cr: str) -> Result:
+    from . import changes, decisions
+
+    path = changes.find(cfg, cr)
+    text = path.read_text()
+    r = Result("change-request", cr)
+    status = (re.search(r"^\*\*Status:\*\* `(\w+)`", text, re.M) or [None, "?"])[1]
+    r.add("1", "recorded with the user's request", md.PLACEHOLDER not in text.split("## Impact", 1)[0])
+    r.add("2", "impact written", md.PLACEHOLDER not in text.split("## Plan", 1)[0])
+    r.add("2", "assumptions resolved", not decisions.open_for(cfg, f"cr:{cr}"))
+
+    def section(name: str) -> str:
+        return text.split(f"## {name}", 1)[-1].split("\n## ", 1)[0] if f"## {name}" in text else ""
+
+    later = status in ("planned", "implemented", "tested", "reviewed", "done")
+    r.add("3", "specs updated (requirements changed)", bool(re.search(r"^- ", section("Requirements changed"), re.M)) if later else None)
+    r.add("4", "increments planned for it", bool(re.search(r"^- ", section("Plan"), re.M)) if later else None)
+    r.add("5", "status follows the increments", not [p for p in changes.cr_problems(cfg) if path.name in p])
+    return r
+
+
+def fix(cfg: Config, item_id: str) -> Result:
+    from . import backlog, registry, reports
+
+    item = backlog.find(cfg, item_id)
+    r = Result("fix", item_id)
+    commits = _unit_commits(cfg, item_id, "Backlog")
+    r.add("1", "backlog item with priority and detail", md.PLACEHOLDER not in item.path.read_text())
+    done = item.status in backlog.NEEDS_FIX_ID
+    r.add("3", "fixed, with the fix change id", done and item.fix_change_id not in ("", "—") if item.status not in
+          ("wontfix", "duplicate", "accepted-risk") else None, f"status {item.status}")  # fmt: skip
+    mods = registry.load(cfg)
+    mod = mods.get(item.module)
+    tested = mod and any(i.status in ("tested", "reviewed") for i in mod.increments)
+    regression = [p for p in reports.numbered(mod.folder / "test", "test_report") if item_id in p.read_text()] if mod else []
+    r.add("4", "regression test report for the tested module", bool(regression) if tested and done else None)
+    r.add("5", "commit with the Backlog trailer", bool(commits) if done else None)
+    r.add("5", "issue mirrored", item.issue_sync != "pending", item.issue_sync)
+    return r
+
+
+def setup(cfg: Config) -> Result:
+    from . import decisions, guide, registry, security, style
+
+    r = Result("setup", cfg.project)
+    r.add("1", "project described and confirmed (architecture goals)",
+          cfg.architecture.exists() and md.PLACEHOLDER not in cfg.architecture.read_text().split("## 2.", 1)[0])  # fmt: skip
+    r.add("3", "setup answers recorded as decisions", any(d.scope == "project" for d in decisions.decisions(cfg)))
+    opened = decisions.open_for(cfg, "project")
+    r.add("6/7", "no open project assumptions", not opened, ", ".join(a.id for a in opened))
+    r.add("5", "guides exist", all(p.exists() for p in guide.guide_paths(cfg)))
+    r.add("5", "components specified (at least one spec)", bool(registry.load(cfg)))
+    r.add("6", "coding style agreed", style.state(cfg)["agreed"] if style.required(cfg) else None)
+    missing = [k for k in security.required(cfg) if k != "secrets" and not cfg.get(f"security.{k}") and not security.waiver(cfg, k)]
+    r.add("4", "required security checks configured or waived (security tools)", not missing, ", ".join(missing))
+    hooks = cfg.get("hooks.pre_commit") or cfg.get("hooks.pre_push")
+    r.add("4", "git hooks installed", gitx.out(cfg.root, "config", "core.hooksPath") != "" if hooks else None)
+    return r
+
+
+def oneoff_wf(cfg: Config, where: str) -> Result:
+    from . import oneoff
+
+    path = oneoff.find(oneoff.base_dir(cfg.root, cfg.data), where)
+    st = oneoff.load(path)
+    r = Result("oneoff", st["name"])
+    r.add("2", "assumptions recorded instead of asking", bool(st["assumptions"]))
+    r.add("3", "plan: approach, tasks, test and run commands", bool(st["approach"] and st["tasks"] and st["test_commands"]
+                                                                    and st["run"]))  # fmt: skip
+    r.add("4", "every task done", all(t["status"] == "done" for t in st["tasks"]))
+    r.add("5", "tests run and passed", bool(st["tests"]) and all(t["rc"] == 0 for t in st["tests"]))
+    r.add("6", "REPORT.md written after the last change", (path / "REPORT.md").exists() and
+          (path / "REPORT.md").stat().st_mtime >= (path / oneoff.STATE).stat().st_mtime - 5)  # fmt: skip
+    r.add("4", "limitations and future scope noted", bool(st["limitations"] or st["future"]))
+    return r
+
+
+def adopt_wf(cfg: Config) -> Result:
+    from . import adopt
+
+    r = Result("adopt", cfg.project)
+    w = adopt.work(cfg.root)
+    plan = json.loads((w / "plan.json").read_text()) if (w / "plan.json").exists() else {}
+    r.add("2", "repository scanned", (w / "analysis.json").exists() or bool(plan.get("applied")))
+    r.add("3", "plan agreed with the user", bool(plan.get("finalised")))
+    snap = plan.get("snapshot") or {}
+    r.add("4", "old code kept on a pushed branch", bool(snap.get("branch")) and bool(snap.get("pushed")),
+          snap.get("branch", ""))  # fmt: skip
+    r.add("6", "applied: architecture, specs, baseline", bool(plan.get("applied")) and
+          (cfg.architecture_dir / "baseline.md").exists())  # fmt: skip
+    return r
+
+
+def triage_wf(cfg: Config) -> Result:
+    from . import triage
+
+    r = Result("triage", cfg.project)
+    p = triage.data_path(cfg)
+    rows = json.loads(p.read_text())["rows"] if p.exists() else []
+    r.add("1", "issues fetched and checked against the specs", p.exists())
+    vague = [f"#{x['number']}" for x in rows if x["status"] == "vague"]
+    r.add("3/4", "every vague issue decided by the user", not vague, ", ".join(vague))
+    return r
+
+
+def discuss_wf(cfg: Config, number: int) -> Result:
+    from . import discuss
+
+    st = discuss.load(cfg.root, number)
+    r = Result("discuss", f"issue #{number}")
+    r.add("2", "questions posted", any(p["type"] == "questions" for p in st["posts"]))
+    left = [q["id"] for q in st["questions"] if not q["answer"]]
+    r.add("3", "every question answered (verbatim)", not left, ", ".join(left))
+    r.add("4", "summary confirmed by the user", "summary" in st["approvals"])
+    r.add("5", "plan reviewed and approved by the user", "plan" in st["approvals"])
+    r.add("6", "applied to the specifications", st["phase"] == "applied", f"phase {st['phase']}")
+    return r
+
+
+def deploy_wf(cfg: Config) -> Result:
+    from . import deploy
+
+    r = Result("deploy", cfg.project)
+    st = deploy.state(cfg)
+    r.add("1-3", "deploy plan agreed and applied", st.get("agreed", False))
+    probs = deploy.problems(cfg) if st.get("agreed") else []
+    r.add("4", "generated files in step with the plan, every module placed", not probs if st.get("agreed") else None,
+          "; ".join(probs[:2]))  # fmt: skip
+    warn = deploy.credential_warnings(cfg)
+    r.add("6", "no deploy credentials on the agents' machine", not warn, "; ".join(warn))
+    return r
+
+
+# ---------------------------------------------------------------- entry points
+
+
+def run(cfg: Config, workflow: str, **kw: Any) -> Result:
+    if workflow in ("implement", "test", "review"):
+        if not kw.get("module") or not kw.get("increment"):
+            raise ValueError("--module and --increment")
+        fn = {"implement": implement, "test": test, "review": review}[workflow]
+        return fn(cfg, kw["module"], int(kw["increment"]), prepush=kw.get("prepush", False))
+    if workflow == "security":
+        return security_wf(cfg, kw["module"])
+    if workflow == "change-request":
+        return change_request(cfg, kw["cr"])
+    if workflow == "fix":
+        return fix(cfg, kw["backlog"])
+    if workflow == "setup":
+        return setup(cfg)
+    if workflow == "oneoff":
+        return oneoff_wf(cfg, kw.get("dir", ""))
+    if workflow == "adopt":
+        return adopt_wf(cfg)
+    if workflow == "triage":
+        return triage_wf(cfg)
+    if workflow == "discuss":
+        return discuss_wf(cfg, int(kw["issue"]))
+    if workflow == "deploy":
+        return deploy_wf(cfg)
+    raise ValueError(f"unknown workflow {workflow!r}; known: {', '.join(WORKFLOWS)}")
+
+
+def stage_checks(cfg: Config, module: str, k: int, *, prepush: bool = False) -> list[Result]:
+    """The checks that apply to an increment's current status: coded → implement, tested → +test, reviewed → +review."""
+    from . import registry
+
+    inc = registry.load(cfg)[module].inc(k)
+    out = []
+    if inc.status in ("coded", "tested", "reviewed"):
+        out.append(implement(cfg, module, k, prepush=prepush))
+    if inc.status in ("tested", "reviewed"):
+        out.append(test(cfg, module, k, prepush=prepush))
+    if inc.status == "reviewed":
+        out.append(review(cfg, module, k, prepush=prepush))
+    return out
+
+
+def report(cfg: Config) -> dict[str, Any]:
+    from . import backlog, changes, registry
+
+    results: list[Result] = []
+    for m in registry.load(cfg).values():
+        for inc in m.increments:
+            results += stage_checks(cfg, m.name, inc.number)
+    for item in backlog.items(cfg):
+        if item.status in backlog.NEEDS_FIX_ID:
+            results.append(fix(cfg, item.id))
+    for p in changes.all_crs(cfg):
+        cr = "-".join(p.name.split("-")[:2])
+        if not re.search(r"^\*\*Status:\*\* `(proposed|rejected)`", p.read_text(), re.M):
+            results.append(change_request(cfg, cr))
+    by: dict[str, dict[str, int]] = {}
+    for r in results:
+        b = by.setdefault(r.workflow, {"runs": 0, "passed": 0, "steps": 0, "missing": 0})
+        b["runs"] += 1
+        b["passed"] += r.passed
+        b["steps"] += len([s for s in r.steps if s.status != "n/a"])
+        b["missing"] += len(r.missing)
+    skipped: dict[str, int] = {}
+    for r in results:
+        for s in r.missing:
+            key = f"{r.workflow} step {s.n}: {s.name}"
+            skipped[key] = skipped.get(key, 0) + 1
+    return {"results": results, "by_workflow": by, "most_skipped": sorted(skipped.items(), key=lambda kv: -kv[1])[:10]}
+
+
+def report_text(data: dict[str, Any]) -> str:
+    lines = ["| Workflow | Runs | Followed fully | Steps done |", "|---|---|---|---|"]
+    for wf, b in sorted(data["by_workflow"].items()):
+        pct = 100 * (b["steps"] - b["missing"]) / b["steps"] if b["steps"] else 100
+        lines.append(f"| {wf} | {b['runs']} | {b['passed']} | {pct:.0f}% |")
+    if data["most_skipped"]:
+        lines += ["", "Most skipped steps:", *[f"- {k} ({n}×)" for k, n in data["most_skipped"]]]
+    failing = [r for r in data["results"] if not r.passed]
+    if failing:
+        lines += ["", "Not followed fully:", *[f"- {r.workflow} {r.subject}: " + "; ".join(f"step {s.n} {s.name}" for s in r.missing)
+                                              for r in failing]]  # fmt: skip
+    return "\n".join(lines)
+
+
+def prepush(cfg: Config, branches: list[str]) -> list[str]:
+    """Pre-push: for each pushed unit branch, the checks of its increment's status must pass."""
+    from . import registry
+
+    failures = []
+    mods = registry.load(cfg)
+    rx = re.compile(rf"^{re.escape(cfg.prefix.lower())}-\d{{4}}-(?P<module>[\w-]+?)-inc(?P<k>\d+)$")
+    for b in branches:
+        m = rx.match(b)
+        if not m or m.group("module") not in mods or mods[m.group("module")].inc(int(m.group("k"))) is None:
+            continue
+        for r in stage_checks(cfg, m.group("module"), int(m.group("k")), prepush=True):
+            if not r.passed:
+                failures.append("workflow not followed: " + r.text())
+    return failures
+
+
+def workflow_file(cfg: Config, name: str) -> Path:
+    from .config import RES
+
+    path = RES / "workflows" / f"{name}.md"
+    if not path.exists():
+        raise ValueError(f"no workflow {name!r}")
+    return path