beacon-framework 1.2.2__tar.gz → 1.3.1__tar.gz

{beacon_framework-1.2.2 → beacon_framework-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beacon-framework
-Version: 1.2.2
+Version: 1.3.1
 Summary: Light-touch, pragmatic, artifact-driven framework for AI-assisted software delivery
 Project-URL: Repository, https://github.com/darth-veitcher/beacon
 Author: darth-veitcher

{beacon_framework-1.2.2 → beacon_framework-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "beacon-framework"
-version = "1.2.2"
+version = "1.3.1"
 description = "Light-touch, pragmatic, artifact-driven framework for AI-assisted software delivery"
 readme = "README.md"
 license = "MIT"
@@ -76,6 +76,8 @@ Repository = "https://github.com/darth-veitcher/beacon"
 
 
 
+
+
 
 
 
@@ -185,6 +187,8 @@ exclude_commit_patterns = ["^chore\\(release\\):"]
 
 
 
+
+
 
 
 

{beacon_framework-1.2.2 → beacon_framework-1.3.1}/src/beacon/__init__.py

@@ -1,3 +1,3 @@
 """BEACON Framework: lifecycle and discipline for artifact-driven AI-assisted delivery."""
 
-__version__ = "1.2.2"
+__version__ = "1.3.1"

{beacon_framework-1.2.2 → beacon_framework-1.3.1}/src/beacon/cli.py

@@ -1271,8 +1271,8 @@ def roadmap_export(
     stdout: bool = typer.Option(
         False, "--stdout", help="Print to stdout instead of writing a file."
     ),
-    include_done: bool = typer.Option(
-        False, "--include-done", help="Include Done epics in the Gantt chart."
+    exclude_done: bool = typer.Option(
+        False, "--exclude-done", help="Exclude Done/archived epics from the roadmap."
     ),
 ) -> None:
     """Generate ROADMAP.md — version-controlled Markdown + Mermaid source of truth.
@@ -1280,10 +1280,14 @@ def roadmap_export(
     Renders epics, spec progress, ADRs, and active bullets into a Mermaid-enhanced
     Markdown document. Safe to commit alongside beacon.md; regenerate on demand or
     wire into CI with ``beacon roadmap export``.
+
+    Done/archived epics are included by default (up to ``roadmap_done_limit`` in
+    your manifest, defaulting to 3). Pass ``--exclude-done`` to suppress them.
     """
     from datetime import date
 
     from beacon import roadmap as _roadmap
+    from beacon.manifest import Manifest
 
     root = _resolve_root(here, path)
     if not (root / "project-management").is_dir():
@@ -1293,9 +1297,11 @@ def roadmap_export(
             "[dim]beacon roadmap export /path/to/project[/dim]"
         )
         raise typer.Exit(1)
+    _m = Manifest.load(root)
+    done_limit = 0 if exclude_done else (_m.roadmap_done_limit if _m else 3)
     today = date.today().isoformat()
     data = _roadmap.collect(root)
-    content = _roadmap.render_markdown(data, today, include_done=include_done)
+    content = _roadmap.render_markdown(data, today, done_limit=done_limit)
     if stdout:
         console.print(content)
         return
@@ -1303,13 +1309,13 @@ def roadmap_export(
     dest.write_text(content, encoding="utf-8")
     console.print(f"[green]✓[/green] Roadmap exported → [cyan]{dest.relative_to(root)}[/cyan]")
     if not data.epics:
-        if data.archived_epics and not include_done:
+        if data.archived_epics and exclude_done:
             n = len(data.archived_epics)
             plural = "s" if n > 1 else ""
             console.print(
                 f"[dim]  ({n} archived epic{plural}"
-                " — run [/dim][dim cyan]beacon roadmap export --include-done"
-                "[/dim cyan][dim] to include completed work)[/dim]"
+                " — remove [/dim][dim cyan]--exclude-done"
+                "[/dim cyan][dim] to include recent completed work)[/dim]"
             )
         elif not data.archived_epics:
             console.print(
@@ -1325,6 +1331,9 @@ def roadmap_render(
     output: Path | None = typer.Option(
         None, "--output", "-o", help="Output path (default: ROADMAP.html in project root)."
     ),
+    exclude_done: bool = typer.Option(
+        False, "--exclude-done", help="Exclude Done/archived epics from the visualization."
+    ),
 ) -> None:
     """Generate ROADMAP.html — Structural Breath interactive visualization (gitignored).
 
@@ -1332,10 +1341,14 @@ def roadmap_render(
     cards, active-bullet feed, and ADR index — all styled with the Structural Breath
     design system (dark, blueprint-grid, engineering-whitepaper aesthetic). Open
     directly in a browser, screenshot into a slide deck, or host as a static page.
+
+    Done/archived epics are included by default (up to ``roadmap_done_limit`` in
+    your manifest, defaulting to 3). Pass ``--exclude-done`` to suppress them.
     """
     from datetime import date
 
     from beacon import roadmap as _roadmap
+    from beacon.manifest import Manifest
 
     root = _resolve_root(here, path)
     if not (root / "project-management").is_dir():
@@ -1345,9 +1358,11 @@ def roadmap_render(
             "[dim]beacon roadmap render /path/to/project[/dim]"
         )
         raise typer.Exit(1)
+    _m = Manifest.load(root)
+    done_limit = 0 if exclude_done else (_m.roadmap_done_limit if _m else 3)
     today = date.today().isoformat()
     data = _roadmap.collect(root)
-    content = _roadmap.render_html(data, today)
+    content = _roadmap.render_html(data, today, done_limit=done_limit)
     dest = output or (root / "ROADMAP.html")
     dest.write_text(content, encoding="utf-8")
     console.print(f"[green]✓[/green] Roadmap rendered → [cyan]{dest.relative_to(root)}[/cyan]")

{beacon_framework-1.2.2 → beacon_framework-1.3.1}/src/beacon/doctor.py

@@ -901,6 +901,39 @@ def _check_epic_adr_coverage(root: Path, config: Config = DEFAULT_CONFIG) -> Che
     )
 
 
+def _check_epic_adr_broken_paths(root: Path) -> Check:
+    """Every ADR entry in every epic's ## ADRs section must resolve to a real file.
+
+    Silently broken paths (typos, wrong relative paths, unrecognised markdown
+    link syntax) render as ``(file missing)`` in the DECISIONS tab without any
+    warning. This check surfaces them before a render is needed.
+    """
+    from beacon.roadmap import _parse_adr  # local import to avoid circular
+
+    all_epics = _epic.list_active(root) + _epic.list_archived(root)
+    broken: list[str] = []
+    for e in all_epics:
+        epic_dir = e.path.parent if e.path else None
+        for adr_path in e.adrs:
+            summary = _parse_adr(root, adr_path, epic_dir)
+            if summary.title == "(file missing)":
+                broken.append(f"{e.slug}: {adr_path!r}")
+    if broken:
+        head = "; ".join(broken[:3]) + ("…" if len(broken) > 3 else "")
+        return Check(
+            "epic-adr-broken-paths",
+            Status.WARN,
+            f"{len(broken)} ADR entry/entries resolve to missing file(s): {head}. "
+            "Use bare paths (e.g. `project-management/ADRs/ADR-001-foo.md`) or "
+            "markdown links with a correct relative href.",
+        )
+    return Check(
+        "epic-adr-broken-paths",
+        Status.OK,
+        "All ADR entries in epics resolve to existing files.",
+    )
+
+
 ROADMAP_REVIEW_AGE = timedelta(days=90)
 """Roadmap is stale if `Last reviewed:` is older than this."""
 
@@ -1917,6 +1950,7 @@ CHECKS: tuple[tuple[str, object, bool], ...] = (
     ("epic-spec-lifecycle", _check_epic_spec_lifecycle, False),
     ("epic-rollup", _check_epic_rollup, False),
     ("epic-adr-coverage", _check_epic_adr_coverage, True),
+    ("epic-adr-broken-paths", _check_epic_adr_broken_paths, False),
     ("roadmap-staleness", _check_roadmap_staleness, True),
     ("publishing-mode", _check_publishing_mode, False),
     ("release-config-alignment", _check_release_config_alignment, False),
@@ -2074,6 +2108,13 @@ CHECK_DESCRIPTIONS: dict[str, str] = {
         "probably went unrecorded — creating/editing an epic is a BEACON "
         "DESIGN-phase activity that should produce ADRs."
     ),
+    "epic-adr-broken-paths": (
+        "Every ADR entry in every epic's `## ADRs` section must resolve to a "
+        "file that exists on disk. WARN means one or more entries are broken — "
+        "typo, wrong relative path, or unsupported markdown link syntax. "
+        "Broken entries render silently as `(file missing)` in `beacon roadmap "
+        "render` without this check."
+    ),
     "roadmap-staleness": (
         "`Roadmap/README.md` should carry a `Last reviewed: YYYY-MM-DD` "
         "header newer than `roadmap_review_age_days` (default 90). WARN means "

{beacon_framework-1.2.2 → beacon_framework-1.3.1}/src/beacon/manifest.py

@@ -50,6 +50,11 @@ class Manifest:
     # `--no-speckit` / declining the offer sets this False; pre-PR installs
     # without the field default False (no nag for users who never opted in).
     speckit_requested: bool = False
+    # How many of the most-recently-completed (archived) epics to include in
+    # roadmap output by default.  0 = exclude Done epics entirely; any positive
+    # integer caps the count.  Use ``--exclude-done`` on the CLI to override to
+    # 0 for a single run without touching this value.
+    roadmap_done_limit: int = 3
 
     @classmethod
     def fresh(cls) -> Manifest:
@@ -71,6 +76,7 @@ class Manifest:
             hooks_enabled=bool(data.get("hooks_enabled", True)),
             git_flow=str(data.get("git_flow", "trunk")),
             speckit_requested=bool(data.get("speckit_requested", False)),
+            roadmap_done_limit=int(data.get("roadmap_done_limit", 3)),
         )
 
     def save(self, project_root: Path) -> Path:

{beacon_framework-1.2.2 → beacon_framework-1.3.1}/src/beacon/resources/integrations/claude_code/commands/beacon/roadmap.md

@@ -17,6 +17,8 @@ Run:
 beacon roadmap export
 ```
 
+This includes the most-recently-completed epics by default (controlled by `roadmap_done_limit` in the manifest, defaulting to 3). Pass `--exclude-done` to suppress Done/archived epics.
+
 If the user passed `render` as an argument (i.e. `$ARGUMENTS` contains the word `render`), also run:
 ```bash
 beacon roadmap render
@@ -26,7 +28,7 @@ beacon roadmap render
 
 Read the just-written `ROADMAP.md` and report concisely:
 
-- **Epic counts** by status: Active / Planning / Paused / Done
+- **Epic counts** by status: Active / Planning / Paused / Done (including any archived epics shown)
 - **Fidelity** for each epic — show the badge (`S+/S?  A+/A?  T:N%`) and flag any that are `S?` (no specs) or `A?` (no ADRs)
 - **In-flight bullets** — how many worktrees have active bullets and which epics they're attached to
 - **Roadmap coverage** — fraction of Active epics that have both specs and ADRs filled in

{beacon_framework-1.2.2 → beacon_framework-1.3.1}/src/beacon/roadmap.py

@@ -33,6 +33,9 @@ _ADR_TITLE_RE = re.compile(r"^#\s*ADR-\d+[:\s]+(.+?)\s*$", re.MULTILINE)
 # Valid ADR statuses
 _ADR_STATUSES = {"Proposed", "Accepted", "Deprecated", "Superseded"}
 
+# Markdown link href extractor: [text](href)
+_MD_LINK_RE = re.compile(r"\[.*?\]\(([^)]+)\)")
+
 
 # ---------------------------------------------------------------------------
 # Dataclasses
@@ -176,15 +179,23 @@ def _fidelity_badge(f: EpicFidelity) -> str:
     return f"{spec} {adr} {task}"
 
 
-def _parse_adr(root: Path, adr_path: str) -> AdrSummary:
+def _parse_adr(root: Path, adr_path: str, epic_dir: Path | None = None) -> AdrSummary:
     """Extract token, title, and status from an ADR file. Never returns None."""
-    # Normalise: drop leading "./" and trailing "/"
-    clean = adr_path.strip().lstrip("./").rstrip("/")
-    full = root / clean
+    # Extract href from markdown link syntax [text](href) if present
+    md_m = _MD_LINK_RE.search(adr_path)
+    raw = md_m.group(1) if md_m else adr_path
 
     token_m = _ADR_TOKEN_RE.search(adr_path)
     token = token_m.group(1).upper() if token_m else "ADR-???"
 
+    raw = raw.strip().rstrip("/")
+    if raw.startswith(("../", "./")):
+        # Relative path — resolve against the epic file's directory
+        base = epic_dir or (root / "project-management/Roadmap/epics")
+        full = (base / raw).resolve()
+    else:
+        full = root / raw.lstrip("./")
+
     if not full.exists():
         return AdrSummary(path=adr_path, token=token, title="(file missing)", status="Unknown")
 
@@ -208,6 +219,15 @@ def _parse_adr(root: Path, adr_path: str) -> AdrSummary:
     return AdrSummary(path=adr_path, token=token, title=title, status=status)
 
 
+def _select_done_epics(archived: list[Epic], done_limit: int) -> list[Epic]:
+    """Return the N most-recently-started archived epics, sorted chronologically."""
+    if done_limit <= 0:
+        return []
+    by_recency = sorted(archived, key=lambda e: e.started or "0000-00-00", reverse=True)
+    selected = by_recency[:done_limit]
+    return sorted(selected, key=lambda e: e.started or "9999-99-99")
+
+
 def _mermaid_gantt_src(
     epics: list[Epic],
     rollups: dict[str, Rollup],
@@ -290,12 +310,13 @@ def _markdown_status_table(
     return "\n".join(rows)
 
 
-def _to_json_data(data: RoadmapData, generated_at: str, *, include_done: bool = False) -> dict:
+def _to_json_data(data: RoadmapData, generated_at: str, *, done_limit: int = 3) -> dict:
     """Serialise RoadmapData to the shape embedded in ROADMAP.html."""
-    all_epics = data.epics + (data.archived_epics if include_done else [])
+    done_epics = _select_done_epics(data.archived_epics, done_limit)
+    all_epics = data.epics + done_epics
     epics_list = []
     for e in all_epics:
-        if not include_done and e.status == "Done":
+        if done_limit == 0 and e.status == "Done":
             continue
         roll = data.rollups.get(e.slug)
         f = data.fidelity.get(e.slug)
@@ -354,7 +375,7 @@ def _to_json_data(data: RoadmapData, generated_at: str, *, include_done: bool =
     # Build gantt_bars for D3
     gantt_bars = []
     for e in all_epics:
-        if not include_done and e.status == "Done":
+        if done_limit == 0 and e.status == "Done":
             continue
         if not e.started:
             continue
@@ -422,12 +443,13 @@ def collect(root: Path) -> RoadmapData:
             adr_count=len(e.adrs),
         )
 
+        epic_dir = e.path.parent if e.path else None
         for adr_path in e.adrs:
             m = _ADR_TOKEN_RE.search(adr_path)
             if m:
                 tok = m.group(1).upper()
                 if tok not in seen_adrs:
-                    seen_adrs[tok] = _parse_adr(root, adr_path)
+                    seen_adrs[tok] = _parse_adr(root, adr_path, epic_dir)
 
     adrs = sorted(seen_adrs.values(), key=lambda a: a.token)
 
@@ -452,7 +474,7 @@ def render_markdown(
     data: RoadmapData,
     generated_at: str,
     *,
-    include_done: bool = False,
+    done_limit: int = 3,
 ) -> str:
     """Render ROADMAP.md content from collected data."""
     lines: list[str] = []
@@ -465,7 +487,8 @@ def render_markdown(
         lines.append(f"> {data.vision_excerpt}")
         lines.append("")
 
-    visible_epics = data.epics + (data.archived_epics if include_done else [])
+    done_epics = _select_done_epics(data.archived_epics, done_limit)
+    visible_epics = data.epics + done_epics
 
     if not visible_epics:
         if data.archived_epics:
@@ -473,7 +496,8 @@ def render_markdown(
             plural = "s" if n > 1 else ""
             lines.append(
                 f"_No active epics — {n} epic{plural} archived. "
-                f"Run `beacon roadmap export --include-done` to include completed work._"
+                "Remove `--exclude-done` or raise `roadmap_done_limit` in your manifest"
+                " to include completed work._"
             )
         else:
             lines.append(
@@ -497,7 +521,7 @@ def render_markdown(
     lines.append("")
     lines.append("```mermaid")
     lines.append(
-        _mermaid_gantt_src(visible_epics, data.rollups, generated_at, include_done=include_done)
+        _mermaid_gantt_src(visible_epics, data.rollups, generated_at, include_done=(done_limit > 0))
     )
     lines.append("```")
     lines.append("")
@@ -545,7 +569,7 @@ def render_markdown(
     return "\n".join(lines)
 
 
-def render_html(data: RoadmapData, generated_at: str) -> str:
+def render_html(data: RoadmapData, generated_at: str, *, done_limit: int = 3) -> str:
     """Render ROADMAP.html by injecting JSON into the Structural Breath template."""
     from importlib import resources as _res
 
@@ -554,7 +578,7 @@ def render_html(data: RoadmapData, generated_at: str) -> str:
     )
     template = template_bytes.decode("utf-8")
 
-    json_data = _to_json_data(data, generated_at)
+    json_data = _to_json_data(data, generated_at, done_limit=done_limit)
     # Use json.dumps with separators for compact embedding; escape </script> sequences
     json_str = json.dumps(json_data, ensure_ascii=False).replace("</script>", "<\\/script>")
 
@@ -568,26 +592,36 @@ def generate_markdown(
     root: Path,
     output: Path | None = None,
     *,
-    include_done: bool = False,
+    done_limit: int | None = None,
 ) -> Path:
     """Collect data, render, and write ROADMAP.md. Returns the written path."""
     from datetime import date
 
+    from beacon.manifest import Manifest
+
+    if done_limit is None:
+        m = Manifest.load(root)
+        done_limit = m.roadmap_done_limit if m else 3
     today = date.today().isoformat()
     data = collect(root)
-    content = render_markdown(data, today, include_done=include_done)
+    content = render_markdown(data, today, done_limit=done_limit)
     dest = output or (root / "ROADMAP.md")
     dest.write_text(content, encoding="utf-8")
     return dest
 
 
-def generate_html(root: Path, output: Path | None = None) -> Path:
+def generate_html(root: Path, output: Path | None = None, *, done_limit: int | None = None) -> Path:
     """Collect data, render, and write ROADMAP.html. Returns the written path."""
     from datetime import date
 
+    from beacon.manifest import Manifest
+
+    if done_limit is None:
+        m = Manifest.load(root)
+        done_limit = m.roadmap_done_limit if m else 3
     today = date.today().isoformat()
     data = collect(root)
-    content = render_html(data, today)
+    content = render_html(data, today, done_limit=done_limit)
     dest = output or (root / "ROADMAP.html")
     dest.write_text(content, encoding="utf-8")
     return dest