plan: a missing section named like a contracts file gives no hint

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 48
+- `plan` with a section that is not found: the table-of-contents hint keeps `--contracts`, and a section named like a file next to the plan points to it (`plan <dir>/<name>.md`). Cards named another module's contracts file as a section of this one, and agents got "section not found" with no way forward (9 reports).
+
 ## 47
 - `bash_guard` lets `cat > file <<` create a new file: Write costs the same there, so blocking only cost agents a retry (15 reports after the previous fix). Rewriting or appending to an existing project file is still refused.
 

lib/dpcli/__init__.py

@@ -6,4 +6,4 @@
 else in the current copy. Exit codes: 0 ok, 1 error/check failed, 2 arguments.
 """
 
-VERSION = 47# bump on every change: older copies re-exec from the main copy (reexec.maybe_reexec)
+VERSION = 48  # bump on every change: older copies re-exec from the main copy (reexec.maybe_reexec)

lib/dpcli/commands/plan.py

@@ -45,7 +45,10 @@ def cmd_plan(a):
         return
     sel = find_section(heads, a.section)
     if sel is None:
-        raise DpError(f"section \"{a.section.strip()}\" not found; table of contents: {CLI} plan {a.target}")
+        other = path.parent / f"{a.section.strip()}.md"  # cards name another contracts file as if it were a section
+        raise DpError(f"section \"{a.section.strip()}\" not found; table of contents: {CLI} plan {a.target}"
+                      + (" --contracts" if a.contracts else "")
+                      + (f"; it is a file: {CLI} plan {rel(other)}" if other.is_file() and other != path else ""))
     print("\n".join(section_body(lines, heads, sel, a.max)))
 
 

tests/test_plan_report.py

@@ -51,6 +51,16 @@ def test_decide_plan_near_miss_still_appends(self):
         self.assertIn("added", self.p.ok("decide", "pf", "Use B", "--by", "user", "--plan", "1. Goal"))
         self.assertIn("- **Use B** (", self.p.ok("plan", "pf", "1"))
 
+    def test_missing_section_named_like_a_contracts_file_points_to_it(self):
+        d = self.p.root / "docs" / "contracts"
+        d.mkdir(parents=True, exist_ok=True)
+        (d / "pf.md").write_text("# C\n## 1. API\n", encoding="utf-8")
+        (d / "cli.md").write_text("# CLI\n## 1. Commands\n", encoding="utf-8")
+        code, _, err = self.p.run("plan", "pf", "cli", "--contracts")  # flag last: Python 3.10 argparse
+        self.assertEqual(code, 1)
+        self.assertIn("plan pf --contracts", err)  # the table of contents of the same file
+        self.assertIn("docs/contracts/cli.md", err)
+
     def test_plan_ref_checked_at_task_new(self):
         args = ["task", "new", "pf", "--type", "dp-engineer", "--title", "t", "--goal", "g", "--scope", "src", "--no-copy"]
         for bad in ("7. Nowhere", "7. Nowhere (x)", "Goal (1)"):