feat(plan): source the tracker thread once via role="tracker" (#132)

Plan seeding fetched the tracker issue twice in one cycle: seed() ran the legacy
[tracker].notes_cmd (→ notes.json) AND, unconditionally, the [[plan.source]]
providers — so a GitHub-Issues project with a `github` source stored the issue
in both notes.json and sources/github-<id>.json, and a notes_cmd moved into a
`command` source ran twice. A project couldn't de-dupe by dropping notes_cmd
because notes.json is load-bearing by filename (the planner and the id-seeded
batch flow read it), and the providers only wrote into sources/.

Add a `role = "tracker"` declaration on a plan.source: a github/gitlab/command
source so marked writes the canonical notes.json itself (at the bundle root),
and seed() then skips the legacy notes_cmd. notes_cmd and a tracker-role
plan.source are mutually exclusive; notes.json stays available (no planner /
id-seeded-flow regression), and a project with neither sees no change.

This is the minimum unification (issue #132 option C) plus the small role/redirect
needed to keep notes.json present; the fuller option A (read the tracker thread
from sources/ by role) remains future work.

Documented in pdca.toml.jinja and docs/03-plan.md. Tests in test_sources.py:
tracker-role github sources once and skips notes_cmd; tracker-role command
writes notes.json; a non-tracker source leaves notes_cmd running.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: eduralph

docs/03-plan.md

@@ -52,7 +52,10 @@ so the planner briefs from the **full** picture, not one scrape (issue #102). Bu
 types: `github` (`gh`), `gitlab` (`glab`), `csv`, `file` (a path/glob, `{id}`
 interpolated), and `command` (the escape hatch — exactly `notes_cmd`, run with
 `$PDCA_BUNDLE` / `$PDCA_SOURCES` set). Each is best-effort; the legacy `notes_cmd` still
-runs alongside them. For example, "the GitHub issue **and** its linked ADR":
+runs alongside them — **unless** a source sets `role = "tracker"`, which makes that source
+the tracker thread (it writes `notes.json` itself) and suppresses `notes_cmd` so the issue
+is sourced once, not fetched and stored twice (issue #132). `notes_cmd` and a tracker-role
+plan.source are mutually exclusive. For example, "the GitHub issue **and** its linked ADR":
 
 ```toml
 [[plan.source]]

template/pdca.toml.jinja

@@ -79,9 +79,14 @@ issue_trailer = "Fixes #{id}"
 # / file / failing command is non-fatal). Built-in types: github (gh), gitlab (glab), csv,
 # file (a path/glob, {id} interpolated), command (the escape hatch — a `.format(id=)` shell
 # command run with $PDCA_BUNDLE / $PDCA_SOURCES set; it writes its own output). The legacy
-# notes_cmd above still runs, so this is purely additive. Examples (uncomment to use):
+# notes_cmd above still runs alongside these, so they are purely additive — EXCEPT a source
+# that sets `role = "tracker"` (issue #132): it IS the tracker thread, writes the canonical
+# notes.json itself, and SUPPRESSES notes_cmd, so the issue is sourced once rather than
+# fetched/stored twice. `notes_cmd` and a tracker-role plan.source are mutually exclusive.
+# Examples (uncomment to use):
 # [[plan.source]]
 # type = "github"            # gh issue view {id} --json … → sources/github-<id>.json
+# # role = "tracker"         # make THIS the tracker fetch (→ notes.json) and drop notes_cmd
 # # repo = "owner/repo"      # optional; omit to use gh's default repo
 # [[plan.source]]
 # type = "file"              # a linked design doc / ADR / proposal / spec

template/src/pdca_harness/sources.py

@@ -18,8 +18,16 @@
 
 Every provider is **best-effort**: a missing tool, an absent file, or a failing command is
 non-fatal — that source is skipped with a note and Plan falls back to the others / the
-human. The legacy ``[tracker].notes_cmd`` still runs (back-compat), so a project that sets
-neither sees no change.
+human.
+
+**The tracker thread is sourced once (#132).** The legacy ``[tracker].notes_cmd`` still
+runs for back-compat — *unless* a ``[[plan.source]]`` declares itself the tracker thread
+with ``role = "tracker"``. A tracker-role ``github``/``gitlab``/``command`` source writes
+the canonical ``notes.json`` (at the bundle root, where the planner and the id-seeded
+batch flow read it) and ``seed()`` then **skips** ``notes_cmd``, so a GitHub-Issues
+project configures the tracker fetch once instead of fetching/storing the same issue
+twice. ``notes_cmd`` and a tracker-role plan.source are therefore mutually exclusive; a
+project that sets neither sees no change.
 """
 
 from __future__ import annotations
@@ -37,17 +45,26 @@ def seed(cfg: Config, d: Path) -> None:
     """Seed bundle ``d`` from every configured Plan source, plus the legacy notes_cmd.
 
     Idempotent-ish and best-effort: providers that fail are skipped. New providers write
-    into ``d/sources/``; the legacy ``notes_cmd`` still writes ``d/notes.json``. The
-    planner reads both.
+    into ``d/sources/``; the legacy ``notes_cmd`` writes ``d/notes.json``. The planner
+    reads both.
+
+    The tracker issue is sourced **once** (#132): if a plan.source declares ``role =
+    "tracker"`` it supplies the canonical ``notes.json`` itself, and the legacy
+    ``notes_cmd`` is skipped so the same issue isn't fetched and stored twice.
     """
     from . import leaves  # lazy: leaves imports sources via do_plan; avoid an import cycle
 
-    leaves.ensure_notes(cfg, d)  # legacy [tracker].notes_cmd → notes.json (#65), unchanged
-    if not cfg.plan_sources:
+    plan_sources = cfg.plan_sources or []
+    # Skip the legacy notes_cmd when a plan.source is the declared tracker thread —
+    # otherwise the issue is fetched twice (notes_cmd AND the provider) and both copies
+    # land in the bundle (#132). notes_cmd stays as back-compat for projects with none.
+    if not any(_is_tracker_source(s) for s in plan_sources):
+        leaves.ensure_notes(cfg, d)  # legacy [tracker].notes_cmd → notes.json (#65)
+    if not plan_sources:
         return
     sources_dir = d / "sources"
     issue_id = d.name.removeprefix("issue_")
-    for i, spec in enumerate(cfg.plan_sources):
+    for i, spec in enumerate(plan_sources):
         kind = (spec.get("type") or "").strip().lower()
         provider = _PROVIDERS.get(kind)
         if provider is None:
@@ -72,8 +89,26 @@ def _run_capture(cmd: list[str], cwd: Path) -> tuple[int, str]:
     return r.returncode, (r.stdout or "")
 
 
+def _is_tracker_source(spec: dict) -> bool:
+    """True iff this plan.source declares itself the tracker thread (``role =
+    "tracker"``) — a github/gitlab/command source that supplies the canonical
+    ``notes.json``, making the legacy ``notes_cmd`` redundant (#132)."""
+    return (spec.get("role") or "").strip().lower() == "tracker"
+
+
+def _tracker_dest(d: Path, sources_dir: Path, spec: dict, default_name: str) -> Path:
+    """Where a fetched issue is written: the canonical ``d/notes.json`` when this source
+    is the declared tracker thread (so the planner / id-seeded flow find it), else its
+    default file under ``sources/`` (supplementary context). #132."""
+    if _is_tracker_source(spec):
+        return d / "notes.json"
+    return sources_dir / (spec.get("out") or default_name)
+
+
 def _github(cfg: Config, d: Path, out: Path, issue_id: str, spec: dict, i: int) -> None:
-    """`gh issue view <id>` as JSON. A ``repo`` in the spec scopes it; absent ⇒ gh's default."""
+    """`gh issue view <id>` as JSON. A ``repo`` in the spec scopes it; absent ⇒ gh's
+    default. ``role = "tracker"`` writes the canonical ``notes.json`` (#132) instead of
+    ``sources/github-<id>.json`` so this provider can be the single tracker source."""
     fields = spec.get("fields", "title,body,comments,url,state,labels")
     cmd = ["gh", "issue", "view", issue_id, "--json", fields]
     if spec.get("repo"):
@@ -83,7 +118,7 @@ def _github(cfg: Config, d: Path, out: Path, issue_id: str, spec: dict, i: int)
         print(f"sources: {d.name} — `gh issue view {issue_id}` produced nothing (rc {rc}); "
               "skipping github source", file=sys.stderr)
         return
-    (out / f"github-{issue_id}.json").write_text(text, encoding="utf-8")
+    _tracker_dest(d, out, spec, f"github-{issue_id}.json").write_text(text, encoding="utf-8")
 
 
 def _gitlab(cfg: Config, d: Path, out: Path, issue_id: str, spec: dict, i: int) -> None:
@@ -95,7 +130,7 @@ def _gitlab(cfg: Config, d: Path, out: Path, issue_id: str, spec: dict, i: int)
         print(f"sources: {d.name} — `glab issue view {issue_id}` produced nothing (rc {rc}); "
               "skipping gitlab source", file=sys.stderr)
         return
-    (out / f"gitlab-{issue_id}.txt").write_text(text, encoding="utf-8")
+    _tracker_dest(d, out, spec, f"gitlab-{issue_id}.txt").write_text(text, encoding="utf-8")
 
 
 def _csv(cfg: Config, d: Path, out: Path, issue_id: str, spec: dict, i: int) -> None:
@@ -145,7 +180,9 @@ def _file(cfg: Config, d: Path, out: Path, issue_id: str, spec: dict, i: int) ->
 def _command(cfg: Config, d: Path, out: Path, issue_id: str, spec: dict, i: int) -> None:
     """The escape hatch — a ``.format(id=)`` shell command (exactly today's notes_cmd). It
     runs with ``$PDCA_BUNDLE`` (the bundle) and ``$PDCA_SOURCES`` (sources/) set and is
-    responsible for writing its own output there. Captured stdout, if any, is also saved."""
+    responsible for writing its own output there. Captured stdout, if any, is also saved —
+    to the canonical ``notes.json`` when ``role = "tracker"`` (#132, so a notes_cmd moved
+    into a tracker plan.source still seeds notes.json), else to ``sources/<out>``."""
     cmd = str(spec.get("cmd", "")).format(id=issue_id)
     if not cmd:
         return
@@ -156,7 +193,9 @@ def _command(cfg: Config, d: Path, out: Path, issue_id: str, spec: dict, i: int)
         print(f"sources: {d.name} — command source failed (rc {r.returncode}): "
               f"{(r.stderr or '').strip()}", file=sys.stderr)
         return
-    if spec.get("out") and (r.stdout or "").strip():
+    if _is_tracker_source(spec) and (r.stdout or "").strip():
+        (d / "notes.json").write_text(r.stdout, encoding="utf-8")
+    elif spec.get("out") and (r.stdout or "").strip():
         (out / str(spec["out"])).write_text(r.stdout, encoding="utf-8")
 
 

template/tests/test_sources.py

@@ -120,6 +120,44 @@ def test_legacy_notes_cmd_still_runs(self) -> None:
         sources.seed(cfg, d)
         self.assertTrue((d / "notes.json").exists())   # #65 back-compat preserved
 
+    def test_tracker_role_github_sources_once_and_skips_notes_cmd(self) -> None:
+        # #132: a github plan.source declared role="tracker" writes the canonical
+        # notes.json and the legacy notes_cmd is skipped — the issue is fetched once,
+        # not stored in both notes.json and sources/github-<id>.json.
+        cfg = _cfg(
+            self.tmp,
+            notes_cmd="printf NOTES_CMD_RAN > \"$PDCA_BUNDLE/notes.json\"",
+            plan_sources=[{"type": "github", "role": "tracker"}])
+        d = self._bundle(cfg)
+        fake = SimpleNamespace(returncode=0, stdout='{"title":"t"}', stderr="")
+        with mock.patch("pdca_harness.sources.subprocess.run", return_value=fake):
+            sources.seed(cfg, d)
+        self.assertEqual((d / "notes.json").read_text(encoding="utf-8"), '{"title":"t"}')
+        self.assertNotIn("NOTES_CMD_RAN", (d / "notes.json").read_text(encoding="utf-8"))
+        self.assertFalse((d / "sources" / "github-42.json").exists())  # not stored twice
+
+    def test_tracker_role_command_writes_notes_json_and_skips_notes_cmd(self) -> None:
+        # The `command` escape hatch as the tracker source: its stdout becomes notes.json
+        # and notes_cmd does not also run (moving a notes_cmd into a tracker plan.source
+        # must not run it twice).
+        cfg = _cfg(
+            self.tmp,
+            notes_cmd="printf NOTES_CMD_RAN > \"$PDCA_BUNDLE/notes.json\"",
+            plan_sources=[{"type": "command", "role": "tracker", "cmd": "echo thread"}])
+        d = self._bundle(cfg)
+        sources.seed(cfg, d)
+        self.assertEqual((d / "notes.json").read_text(encoding="utf-8"), "thread\n")
+
+    def test_non_tracker_source_leaves_notes_cmd_running(self) -> None:
+        # Back-compat: a plain (non-tracker) plan.source does NOT suppress notes_cmd.
+        cfg = _cfg(
+            self.tmp,
+            notes_cmd="printf thread > \"$PDCA_BUNDLE/notes.json\"",
+            plan_sources=[{"type": "file", "path": "missing-{id}.md"}])
+        d = self._bundle(cfg)
+        sources.seed(cfg, d)
+        self.assertEqual((d / "notes.json").read_text(encoding="utf-8"), "thread")
+
 
 if __name__ == "__main__":
     unittest.main()