fix(publish): own-repo base remote + stash the dirty target tree (#83)

Two publish preconditions were unmet on a normal own-repo cycle, so it failed
until the operator did manual git surgery (hit contributing into Wyrd).

1. Hardcoded `upstream` remote. The new-PR path branched off a remote literally
   named `upstream` (`fetch upstream`, `checkout -B … upstream/<base>`). A fork has
   upstream=canonical / origin=fork, but contribution_model=own-repo (#75) has only
   origin, so publish died on the fetch. Now `[publisher].base_remote` (default
   upstream; rendered `origin` for own-repo, `upstream` for fork) drives both, and
   _check_repo requires only the remotes the path actually uses (base + push), so
   own-repo needs no second remote. The stack path requires only the brief's remote.

2. Clean-tree requirement vs. Do/Check dirtying it. publish re-applies the fix from
   patch.diff onto a fresh branch (it doesn't use the working tree), but `checkout -B`
   + the old _check_repo clean-guard aborted on a dirty tree — and Do edits the target
   in place + repo-scoped gates run against the working tree, so the tree is always
   dirty at publish, with nothing reverting it. publish now STASHES the tree (incl.
   untracked) before checkout/apply and RESTORES it after / on failure (both the
   new-PR and stack paths), so edit-in-place and a clean publish checkout coexist.

Tests: base_remote configurable (own-repo branches off origin, no upstream assumed);
a real-git publish over a DIRTY checkout succeeds and restores the operator's edits +
untracked file on the original branch, with the fix branch pushed. Suite green (145).

Closes #83.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Eduard Ralph <15236434+eduralph@users.noreply.github.com>

Author: eduralph

template/pdca.toml.jinja

@@ -65,6 +65,10 @@ issue_trailer = "Fixes #{id}"
 [publisher]
 fix_branch_pattern = "fix/{id}-{slug}"
 feature_branch_pattern = "enhancement/{id}-{slug}"
+# The remote the new-PR path branches the fix off of (issue #83). A fork branches off
+# `upstream` (canonical) and pushes to `origin` (the fork); an own-repo target has only
+# `origin`. Defaulted from contribution_model; change it if your remotes differ.
+base_remote = "{{ 'upstream' if contribution_model == 'fork' else 'origin' }}"
 
 [publisher.checkouts]
 # "<org/repo>" = "../<checkout-dir>"   # only the exceptions to the sibling default

template/src/pdca_harness/config.py

@@ -82,6 +82,11 @@ class Config:
     # Branch patterns are .format(id=, slug=) strings; issue_trailer is .format(id=).
     fix_branch_pattern: str = "fix/{id}-{slug}"
     feature_branch_pattern: str = "enhancement/{id}-{slug}"
+    # The remote the new-PR path branches the fix off of (issue #83). A fork branches off
+    # ``upstream`` (the canonical repo); an own-repo target has only ``origin``. The
+    # rendered pdca.toml sets it per contribution_model; default ``upstream`` preserves the
+    # prior fork behavior for a config lacking the key.
+    base_remote: str = "upstream"
     issue_trailer: str = "Fixes #{id}"  # commit/PR trailer; "" → none enforced
     repo_checkouts: dict[str, str] = field(default_factory=dict)  # repo_spec → local path
     gates_checks: list[dict] = field(default_factory=list)
@@ -199,6 +204,7 @@ def leaf(name: str) -> LeafConfig:
             notes_cmd=tracker.get("notes_cmd", ""),
             fix_branch_pattern=publisher_cfg.get("fix_branch_pattern", "fix/{id}-{slug}"),
             feature_branch_pattern=publisher_cfg.get("feature_branch_pattern", "enhancement/{id}-{slug}"),
+            base_remote=publisher_cfg.get("base_remote", "upstream"),
             issue_trailer=tracker.get("issue_trailer", "Fixes #{id}"),
             repo_checkouts=dict(publisher_cfg.get("checkouts", {})),
             gate_target_default=gates.get("target_default", ""),

template/src/pdca_harness/publish.py

@@ -129,9 +129,10 @@ def publish(
     repo = _checkout_path(cfg, repo_spec)
 
     git = lambda *a: ["git", "-C", str(repo), *a]
+    base_remote = cfg.base_remote
     steps = [
-        git("fetch", "upstream"),
-        git("checkout", "-B", branch, f"upstream/{base}"),
+        git("fetch", base_remote),
+        git("checkout", "-B", branch, f"{base_remote}/{base}"),
         git("apply", str((d / "patch.diff").resolve())),
         # `commit -a` stages only modified-tracked files and would silently drop the
         # patch's NEW files (the regression test — the most important file in a fix
@@ -155,22 +156,31 @@ def publish(
 
     if dry_run:
         print(f"publish --dry-run — {d.name} → draft PR on {repo_spec} ({branch} → {base}):")
+        print(f"  # stash the target working tree (Do/Check leave it dirty), restore it after")
         for c in steps + ([pr_cmd] if open_pr else []):
             print("  " + " ".join(shlex.quote(x) for x in c))
         return 0
 
-    # Real run: mutate the local checkout — guard it is present and clean first.
-    rc = _check_repo(repo, repo_spec)
+    # Real run: the checkout must exist with the base + push remotes. Do/Check edit the
+    # target in place, so the tree is normally dirty — stash it (publish re-applies the
+    # fix from patch.diff onto a fresh branch, it doesn't use the working tree) and
+    # restore it afterward, so edit-in-place and a clean publish checkout coexist (#83).
+    rc = _check_repo(repo, repo_spec, required_remotes={base_remote, "origin"})
     if rc != 0:
         return rc
 
-    for c in steps:
-        print("→ " + " ".join(c[3:]))  # drop the `git -C <repo>` prefix in the echo
-        if subprocess.run(c).returncode != 0:
-            hint = " (patch may not apply against upstream/%s — rebase the fix)" % base \
-                if c[3] == "apply" else ""
-            print(f"publish: step failed: {' '.join(c)}{hint}", file=sys.stderr)
-            return 1
+    orig_ref = _current_ref(repo)
+    stashed = _stash_worktree(repo)
+    try:
+        for c in steps:
+            print("→ " + " ".join(c[3:]))  # drop the `git -C <repo>` prefix in the echo
+            if subprocess.run(c).returncode != 0:
+                hint = " (patch may not apply against %s/%s — rebase the fix)" % (base_remote, base) \
+                    if c[3] == "apply" else ""
+                print(f"publish: step failed: {' '.join(c)}{hint}", file=sys.stderr)
+                return 1
+    finally:
+        _restore_worktree(repo, orig_ref, stashed)
 
     pr_url = ""
     pr_failed = False
@@ -250,13 +260,14 @@ def _publish_stacked(
     if dry_run:
         print(f"publish --dry-run — {d.name} → commit stacked onto {repo_spec} "
               f"PR branch {branch} (base {base_ref}):")
+        print(f"  # stash the target working tree (Do/Check leave it dirty), restore it after")
         for c in steps:
             print("  " + " ".join(shlex.quote(x) for x in c))
         print("  " + " ".join(shlex.quote(x) for x in pr_list)
               + "   # resolve the existing open PR (no new PR is created)")
         return 0
 
-    rc = _check_repo(repo, repo_spec)
+    rc = _check_repo(repo, repo_spec, required_remotes={remote})
     if rc != 0:
         return rc
 
@@ -268,15 +279,21 @@ def _publish_stacked(
               "'Onto branch' brief field to use the default new-PR flow.", file=sys.stderr)
         return 1
 
-    for c in steps:
-        print("→ " + " ".join(c[3:]))  # drop the `git -C <repo>` prefix in the echo
-        if subprocess.run(c).returncode != 0:
-            hint = ""
-            if c[3:5] == ["apply", "--check"]:
-                hint = (f" — the patch no longer applies to {base_ref} (it advanced since "
-                        "the fix was built and tested; rebuild/re-Check against the PR branch)")
-            print(f"publish: step failed: {' '.join(c)}{hint}", file=sys.stderr)
-            return 1
+    # Stash the (Do/Check-dirtied) tree so checkout -B + apply run clean; restore after (#83).
+    orig_ref = _current_ref(repo)
+    stashed = _stash_worktree(repo)
+    try:
+        for c in steps:
+            print("→ " + " ".join(c[3:]))  # drop the `git -C <repo>` prefix in the echo
+            if subprocess.run(c).returncode != 0:
+                hint = ""
+                if c[3:5] == ["apply", "--check"]:
+                    hint = (f" — the patch no longer applies to {base_ref} (it advanced since "
+                            "the fix was built and tested; rebuild/re-Check against the PR branch)")
+                print(f"publish: step failed: {' '.join(c)}{hint}", file=sys.stderr)
+                return 1
+    finally:
+        _restore_worktree(repo, orig_ref, stashed)
 
     (d / "publish.json").write_text(json.dumps({
         "mode": "stacked",
@@ -396,28 +413,60 @@ def _t4_passes(cfg: Config, d: Path) -> bool:
     return True
 
 
-def _check_repo(repo: Path, repo_spec: str) -> int:
-    """The local checkout must exist, be clean, and have upstream + origin remotes."""
+def _check_repo(repo: Path, repo_spec: str, required_remotes=("upstream", "origin")) -> int:
+    """The local checkout must exist and have the remotes this publish path needs.
+
+    A dirty tree is NOT a failure (issue #83): Do/Check edit the target in place, so the
+    tree is normally dirty at publish time — :func:`_stash_worktree` cleans it for the
+    checkout and :func:`_restore_worktree` puts it back. ``required_remotes`` is the set
+    this path actually uses (base + push), so own-repo (no ``upstream``) is accepted.
+    """
     hint = (f"create/clone the checkout for '{repo_spec}' at {repo} "
             "(or set [publisher.checkouts] in pdca.toml if it lives elsewhere)")
     if not (repo / ".git").exists():
         print(f"publish: checkout not found: {repo} — {hint}", file=sys.stderr)
         return 1
-    porcelain = subprocess.run(["git", "-C", str(repo), "status", "--porcelain"],
-                               capture_output=True, text=True).stdout.strip()
-    if porcelain:
-        print(f"publish: {repo} has uncommitted changes — clean it first:\n{porcelain}",
-              file=sys.stderr)
-        return 1
     remotes = subprocess.run(["git", "-C", str(repo), "remote"],
                              capture_output=True, text=True).stdout.split()
-    for r in ("upstream", "origin"):
+    for r in required_remotes:
         if r not in remotes:
             print(f"publish: {repo} has no '{r}' remote — {hint}", file=sys.stderr)
             return 1
     return 0
 
 
+def _current_ref(repo: Path) -> str:
+    """The checkout's current branch (or commit SHA if detached) — to return to after publish."""
+    r = subprocess.run(["git", "-C", str(repo), "symbolic-ref", "--quiet", "--short", "HEAD"],
+                       capture_output=True, text=True)
+    ref = r.stdout.strip()
+    if ref:
+        return ref
+    return subprocess.run(["git", "-C", str(repo), "rev-parse", "HEAD"],
+                          capture_output=True, text=True).stdout.strip()
+
+
+def _stash_worktree(repo: Path) -> bool:
+    """Stash the target's dirty tree (incl. untracked) so ``checkout -B`` + ``apply`` run on
+    a clean base; return True iff something was stashed (the caller restores it). Publish
+    re-applies the fix from ``patch.diff``, so the working-tree edits are not needed here."""
+    dirty = bool(subprocess.run(["git", "-C", str(repo), "status", "--porcelain"],
+                                capture_output=True, text=True).stdout.strip())
+    if dirty:
+        subprocess.run(["git", "-C", str(repo), "stash", "push", "--include-untracked",
+                        "-m", "pdca-publish"], capture_output=True, text=True)
+    return dirty
+
+
+def _restore_worktree(repo: Path, orig_ref: str, stashed: bool) -> None:
+    """Return the checkout to where publish found it: back on ``orig_ref`` with the stashed
+    edits popped — so Do/Check's edit-in-place survives a publish. Best-effort."""
+    subprocess.run(["git", "-C", str(repo), "checkout", "--quiet", orig_ref],
+                   capture_output=True, text=True)
+    if stashed:
+        subprocess.run(["git", "-C", str(repo), "stash", "pop"], capture_output=True, text=True)
+
+
 _BY_RE = re.compile(r"^- By / date:\s*(.+?)\s*/", re.MULTILINE)
 
 

template/tests/test_publish_slice.py

@@ -155,6 +155,59 @@ def test_commit_is_signed_off_both_paths(self) -> None:
             self.assertIn("commit -s -F", out, f"{iid}: commit not signed off")
             self.assertNotIn("commit -F", out)  # the unsigned form is gone
 
+    def test_base_remote_is_configurable(self) -> None:
+        # Own-repo (#83): branch the fix off `origin` (no `upstream` remote needed).
+        self.cfg.base_remote = "origin"
+        _bundle(self.cfg, "OWN", brief_body=_FIX_BRIEF, accepted=True)
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            publish.publish(self.cfg, "OWN", dry_run=True)
+        out = buf.getvalue()
+        self.assertIn("fetch origin", out)
+        self.assertIn("checkout -B fix/OWN-my-fix origin/main", out)
+        self.assertNotIn("upstream", out)  # no upstream remote assumed
+
+    def test_publish_succeeds_with_dirty_target_tree(self) -> None:
+        # Own-repo, dirty tree (#83): Do/Check edit the target in place, so publish must
+        # stash → publish off a clean checkout → restore, not abort on the dirty tree.
+        import subprocess as sp
+        repo = self.tmp / "checkout"
+        origin = self.tmp / "origin.git"
+        sp.run(["git", "init", "-q", "--bare", str(origin)], check=True)
+        sp.run(["git", "clone", "-q", str(origin), str(repo)], check=True)
+        run = lambda *a: sp.run(["git", "-C", str(repo), *a], check=True, capture_output=True)
+        run("config", "user.email", "t@example.com")
+        run("config", "user.name", "T")
+        run("config", "commit.gpgsign", "false")
+        (repo / "file.txt").write_text("base\n", encoding="utf-8")
+        run("add", "-A"); run("commit", "-q", "-m", "base")
+        run("branch", "-M", "main"); run("push", "-q", "-u", "origin", "main")
+        # The builder edits in place + leaves an untracked file (the dirty cycle state).
+        (repo / "file.txt").write_text("base\nbuilder edit\n", encoding="utf-8")
+        (repo / "untracked.txt").write_text("u\n", encoding="utf-8")
+
+        self.cfg.base_remote = "origin"
+        self.cfg.repo_checkouts = {"example-org/example-repo": str(repo)}
+        d = _bundle(self.cfg, "DIRTY", brief_body=_FIX_BRIEF, accepted=True)
+        (d / "patch.diff").write_text(
+            "diff --git a/file.txt b/file.txt\n--- a/file.txt\n+++ b/file.txt\n"
+            "@@ -1 +1,2 @@\n base\n+fix line\n", encoding="utf-8")
+
+        buf = io.StringIO()
+        with redirect_stdout(buf), redirect_stderr(buf):
+            rc = publish.publish(self.cfg, "DIRTY", open_pr=False, by="T", today="2026-06-05")
+        self.assertEqual(rc, 0, buf.getvalue())
+        # The operator's dirty edits are restored — edit-in-place survives publish.
+        self.assertEqual((repo / "file.txt").read_text(encoding="utf-8"), "base\nbuilder edit\n")
+        self.assertTrue((repo / "untracked.txt").exists())
+        cur = sp.run(["git", "-C", str(repo), "branch", "--show-current"],
+                     capture_output=True, text=True).stdout.strip()
+        self.assertEqual(cur, "main")  # back on the original branch
+        # The fix branch was pushed to origin.
+        refs = sp.run(["git", "-C", str(repo), "ls-remote", "--heads", "origin"],
+                      capture_output=True, text=True).stdout
+        self.assertIn("fix/DIRTY-my-fix", refs)
+
     def test_pr_head_is_fork_owner_qualified(self) -> None:
         """Regression (#23b): a fork-based PR's --head must be OWNER:BRANCH, else gh
         resolves the branch against the base repo and fails 'Head ref must be a