Merge pull request #71 from eduralph/feat/67-plan-pointer

feat(plan): Plan-as-pointer brief variant for host planning artifacts

Author: eduralph

docs/03-plan.md

@@ -100,6 +100,17 @@ INTEGRATION §2", "addon convention per INTEGRATION §3". That's the payoff of
 ("which branch? where does the test go?") against your repo's concretizations
 instead of guessing.
 
+### The Plan can be a pointer
+
+If your project already plans through its own artifacts — an ADR, an enhancement
+proposal, a normative spec under change control — you don't restate that here. Use
+`templates/plan-pointer.md.tpl`: a thin brief that **references** the host document
+(`- **Planning artifact:** docs/adr/0042-thing.md`) and carries only the few fields the
+driver parses (slug, success criterion, branch target, test file). Do reads the
+referenced artifact as the authoritative plan and cites it; the rest of the cycle is
+unchanged. This lets PDCA wrap a host's existing planning process instead of imposing
+its own document shape.
+
 ## STOP discipline
 
 Every brief carries the rule that the cycle never ships before sign-off:

template/src/pdca_harness/brief.py

@@ -49,6 +49,16 @@ def disposition_hint(brief_path: Path) -> str:
     return field(brief_path, "disposition hint", "disposition")
 
 
+def planning_artifact(brief_path: Path) -> str:
+    """The host planning artifact this brief points at, or "" if it's a self-contained brief.
+
+    The optional ``- **Planning artifact:** <path|url>`` field (issue #67, ``plan-pointer``
+    template): a reference to the host's OWN plan (an ADR / proposal / spec) that Do treats
+    as authoritative. Absent ⇒ an ordinary brief that carries its own spec.
+    """
+    return field(brief_path, "planning artifact", "plan artifact", "plan source")
+
+
 def test_files(brief_path: Path) -> list[Path]:
     """Paths named by the brief's test-requirement field, relative to the bundle.
 

template/src/pdca_harness/leaves.py

@@ -146,6 +146,7 @@ def do_plan(d: Path, cfg: Config, csv: str | None = None) -> None:
 def _plan_prompt(cfg: Config, csv: str | None, d: Path) -> str:
     fix_tpl = cfg.templates_dir / "brief.md.tpl"
     geps_tpl = cfg.templates_dir / "design-proposal.md.tpl"
+    pointer_tpl = cfg.templates_dir / "plan-pointer.md.tpl"
     issue_id = d.name.removeprefix("issue_")
     tracker_csv = csv or cfg.tracker_export_csv
     notes = d / "notes.json"
@@ -178,9 +179,11 @@ def _plan_prompt(cfg: Config, csv: str | None, d: Path) -> str:
         f"to {fix_tpl} — it fits bug fixes AND ordinary new functionality. Use {geps_tpl} "
         "(a design proposal) ONLY for the exception: a change significant enough to "
         "warrant a proposal (major architecture / API / UX). Not every feature is a "
-        "design proposal — when in doubt use the normal brief. Keep the parsed "
-        "`- **Label:** value` field shape; resolve the repo + branch target per "
-        "INTEGRATION §2. One bundle = one brief.md. Plan only."
+        f"design proposal — when in doubt use the normal brief. Use {pointer_tpl} when the "
+        "plan ALREADY lives in a host artifact (an ADR / proposal / normative spec): the "
+        "brief then POINTS at that document (a `Planning artifact:` reference) instead of "
+        "restating it. Keep the parsed `- **Label:** value` field shape; resolve the repo + "
+        "branch target per INTEGRATION §2. One bundle = one brief.md. Plan only."
     )
 
 
@@ -286,7 +289,9 @@ def _build_prompt(d: Path) -> str:
         f"You are the Do builder. Read {d}/brief.md. Build to satisfy its **Success "
         "criterion** (the real end result), not a narrower proxy — an item is done only "
         "when that end result holds, proven red→green; a green mechanical check on "
-        "something adjacent is not done. If brief.md carries an '## Iteration N — "
+        "something adjacent is not done. If brief.md names a **Planning artifact** (an "
+        "ADR / proposal / spec), READ that document — it is the authoritative plan and the "
+        "brief only points at it; build to it and cite it. If brief.md carries an '## Iteration N — "
         "carry-forward' block, address it (the previous attempt's rationale + failing "
         "gate) and do NOT repeat the rejected approach. Produce, in the bundle directory "
         f"{d}: (1) patch.diff — a unified diff against the brief's target branch; "

template/templates/plan-pointer.md.tpl

@@ -0,0 +1,31 @@
+# Brief (pointer) — issue <id> / <slug>
+
+> A Plan artifact that is a **pointer**, for hosts that plan through their OWN
+> artifacts (an ADR, an enhancement proposal, a normative spec) rather than a brief
+> authored here (docs 03). The host's document IS the plan; this file just references
+> it and carries the few fields the driver parses. Use this instead of `brief.md.tpl`
+> when the planning decision already lives — and is reviewed/governed — elsewhere.
+>
+> Keep the `- **Label:** value` lines: Do reads the spec fields from them, and the
+> driver/SUMMARY read slug / success criterion / branch. Do reads the **Planning
+> artifact** as the authoritative plan; this brief does not restate it.
+
+- **Slug:** <short-kebab-slug>
+- **Planning artifact:** <path or URL to the host's ADR / proposal / spec that IS the
+  plan — e.g. `docs/adr/0042-thing.md`, or a permalinked spec section. Do treats this
+  as authoritative; cite it.>
+- **Defect / goal:** <one line: what this realizes — the observable problem or capability>
+- **Success criterion:** <the observable condition that means it works — what the shipped test asserts>
+- **Repo + branch target:** <owner/repo> @ <branch>   (resolve here at Plan — do not leave to Do)
+- **Onto branch:** <remote>/<existing-pr-branch>   (optional — stack onto an open PR's branch; docs 03)
+- **Depends on:** <id>[, <id>…]   (optional — scheduling waits until these are COMPLETE; docs 09)
+- **Conflicts with:** <id>[, <id>…]   (optional — never co-schedule in one wave; docs 09)
+- **Scope:** <the one logical change this realizes> / out of scope: <what is excluded>
+- **Test file:** <path where the regression test ships — must fail pre-change, pass post-change>
+- **Citations expected:** Do must cite path:line on the target branch AND the Planning artifact for every change.
+- **Disposition hint:** <likely-fix | likely-close | … see brief.md.tpl for the full set>
+
+## STOP discipline
+
+Draft only until Check sign-off. A draft PR MAY be opened for CI; the PR MUST NOT be
+marked ready before sign-off accepts.

template/tests/test_flow_slice.py

@@ -19,6 +19,7 @@
 from pdca_harness.config import Config, LeafConfig
 
 DESIGN_TPL = Path(__file__).resolve().parents[1] / "templates" / "design-proposal.md.tpl"
+POINTER_TPL = Path(__file__).resolve().parents[1] / "templates" / "plan-pointer.md.tpl"
 
 
 def _stub_config(root: Path) -> Config:
@@ -528,6 +529,42 @@ def test_feature_brief_flows_and_renders_goal(self) -> None:
         self.assertIn("the capability this adds", summary)     # the Goal value, not blank
 
 
+class PlanPointerBrief(unittest.TestCase):
+    """A pointer-brief (issue #67): the Plan is a reference to the host's own planning
+    artifact (ADR / proposal / spec), not a brief authored here. It carries the same
+    parsed-field contract, so the driver treats it as a normal PLANNED brief."""
+
+    def setUp(self) -> None:
+        self.tmp = Path(tempfile.mkdtemp())
+        self.cfg = _stub_config(self.tmp)
+        self.d = self.cfg.bundle("ADR")
+        self.d.mkdir(parents=True)
+        shutil.copyfile(POINTER_TPL, self.d / "brief.md")  # the plan-pointer template
+
+    def tearDown(self) -> None:
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_template_keeps_driver_parsed_fields(self) -> None:
+        fields = brief.parse_fields(self.d / "brief.md")
+        for label in ("slug", "success criterion", "repo + branch target", "test file",
+                      "planning artifact"):
+            self.assertIn(label, fields, f"plan-pointer template lost parsed field: {label}")
+
+    def test_planning_artifact_reader(self) -> None:
+        # brief.planning_artifact reads the pointer; a self-contained brief returns "".
+        self.assertTrue(brief.planning_artifact(self.d / "brief.md"))
+        plain = self.cfg.bundle("PLAIN")
+        plain.mkdir(parents=True)
+        (plain / "brief.md").write_text("- **Slug:** x\n", encoding="utf-8")
+        self.assertEqual(brief.planning_artifact(plain / "brief.md"), "")
+
+    def test_pointer_brief_flows_to_signoff(self) -> None:
+        # A pointer-brief is PLANNED and drives Do→Check→sign-off offline like any brief.
+        self.assertEqual(state.state(self.d), state.PLANNED)
+        self.assertEqual(driver.run_issue(self.d, self.cfg), state.AWAITING_SIGNOFF)
+        self.assertTrue((self.d / "SUMMARY.md").exists())
+
+
 _TOY_BRIEF = (
     "- **Slug:** {slug}\n"
     "- **Defect:** the count is off by one.\n"