docassert 0.7.1__tar.gz → 0.8.1__tar.gz

{docassert-0.7.1/docassert.egg-info → docassert-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.7.1
+Version: 0.8.1
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0
@@ -54,7 +54,7 @@ derived from the documents rather than self-reported.
 
 docassert is the reference implementation of **[PMO as Code](https://c4g-john.github.io/pmo-as-code/)** —
 a vendor-neutral standard for running a PMO from version-controlled, declarative
-files. It implements the [PMO as Code specification](https://github.com/c4g-john/pmo-as-code-spec) **v0.2**.
+files. It implements the [PMO as Code specification](https://github.com/c4g-john/pmo-as-code-spec) **v0.3** and passes its [conformance suite](https://github.com/c4g-john/pmo-as-code-spec/tree/main/conformance) in CI.
 
 ## Install
 
@@ -98,6 +98,7 @@ flagged as TODOs, never invented). The skill's source is
 | `docassert projects [--out] [--check]` | Generate / verify the project registry. |
 | `docassert new <kind> --project ID` | Scaffold a document from its template with identity filled in (`new project --code XYZ` auto-numbers the id); suggests the next free item ids. |
 | `docassert init [DIR]` | Scaffold the default config into a repo. |
+| `docassert bridge <action> --repo O/N` | Execution bridge: `scaffold` Features/Stories from approved user stories, `reconcile` (police the board against the docs), `status` (delivery figures). Needs the GitHub CLI. |
 | `docassert extract <file>` | Extract plain text from a source `.docx` / `.pdf` / `.md` / `.txt` (the first step of doc-to-pmo conversion). Needs the `convert` extra: `pip install "docassert[convert]"`. |
 
 Every document-reading command accepts `--documents-dir` (default `documents/`).

{docassert-0.7.1 → docassert-0.8.1}/README.md

@@ -14,7 +14,7 @@ derived from the documents rather than self-reported.
 
 docassert is the reference implementation of **[PMO as Code](https://c4g-john.github.io/pmo-as-code/)** —
 a vendor-neutral standard for running a PMO from version-controlled, declarative
-files. It implements the [PMO as Code specification](https://github.com/c4g-john/pmo-as-code-spec) **v0.2**.
+files. It implements the [PMO as Code specification](https://github.com/c4g-john/pmo-as-code-spec) **v0.3** and passes its [conformance suite](https://github.com/c4g-john/pmo-as-code-spec/tree/main/conformance) in CI.
 
 ## Install
 
@@ -58,6 +58,7 @@ flagged as TODOs, never invented). The skill's source is
 | `docassert projects [--out] [--check]` | Generate / verify the project registry. |
 | `docassert new <kind> --project ID` | Scaffold a document from its template with identity filled in (`new project --code XYZ` auto-numbers the id); suggests the next free item ids. |
 | `docassert init [DIR]` | Scaffold the default config into a repo. |
+| `docassert bridge <action> --repo O/N` | Execution bridge: `scaffold` Features/Stories from approved user stories, `reconcile` (police the board against the docs), `status` (delivery figures). Needs the GitHub CLI. |
 | `docassert extract <file>` | Extract plain text from a source `.docx` / `.pdf` / `.md` / `.txt` (the first step of doc-to-pmo conversion). Needs the `convert` extra: `pip install "docassert[convert]"`. |
 
 Every document-reading command accepts `--documents-dir` (default `documents/`).

{docassert-0.7.1 → docassert-0.8.1}/docassert/__init__.py

@@ -5,4 +5,4 @@ standard: deterministic structural checks that gate a merge, plus optional
 AI-graded semantic checks that advise.
 """
 
-__version__ = "0.7.1"
+__version__ = "0.8.1"

docassert-0.8.1/docassert/bridge/__init__.py

@@ -0,0 +1,9 @@
+"""The execution bridge: documents -> GitHub issues/boards -> dashboards.
+
+Scope authority is one-directional. The bridge scaffolds Features and Stories
+from approved user stories, polices the board against the documents, and reads
+delivery progress back for rendering. It never modifies documents.
+"""
+from .plan import BridgePlan, build_bridge_plan
+
+__all__ = ["BridgePlan", "build_bridge_plan"]

docassert-0.8.1/docassert/bridge/gh.py

@@ -0,0 +1,118 @@
+"""Thin wrapper around the GitHub CLI for the bridge (injectable for tests).
+
+All GitHub access goes through `gh` so token handling stays with gh/Actions
+and docassert gains no HTTP dependencies. Every mutation the bridge performs
+funnels through GhRunner, which dry-run mode replaces with a recorder.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+
+
+class GhError(RuntimeError):
+    pass
+
+
+class GhRunner:
+    """Executes gh commands. Tests substitute a fake with the same interface."""
+
+    def run(self, args: list[str], input_: str | None = None) -> str:
+        proc = subprocess.run(["gh", *args], capture_output=True, text=True,
+                              input=input_)
+        if proc.returncode != 0:
+            raise GhError(proc.stderr.strip() or f"gh {' '.join(args)} failed")
+        return proc.stdout
+
+    def api_json(self, path: str, *flags: str):
+        out = self.run(["api", path, *flags])
+        return json.loads(out) if out.strip() else None
+
+    def graphql(self, query: str, **variables) -> dict:
+        args = ["api", "graphql", "-f", f"query={query}"]
+        for k, v in variables.items():
+            args += (["-F", f"{k}={v}"] if isinstance(v, int)
+                     else ["-f", f"{k}={v}"])
+        data = json.loads(self.run(args))
+        if data.get("errors"):
+            raise GhError(json.dumps(data["errors"])[:400])
+        return data["data"]
+
+
+class DryRunner(GhRunner):
+    """Reads pass through; mutations are recorded, not executed."""
+
+    MUTATING = ("-X POST", "-X PATCH", "-X PUT", "-X DELETE", "mutation")
+
+    def __init__(self) -> None:
+        self.planned: list[str] = []
+
+    def run(self, args: list[str], input_: str | None = None) -> str:
+        joined = " ".join(args)
+        if any(m in joined for m in ("-X", "--method")) or "mutation" in joined:
+            self.planned.append(f"gh {joined}")
+            return "{}"
+        return super().run(args, input_)
+
+
+def list_issues(gh: GhRunner, repo: str, state: str = "all") -> list[dict]:
+    """Every issue (not PR) in the repo, paginated."""
+    raw = gh.run(["api", f"repos/{repo}/issues?state={state}&per_page=100",
+                  "--paginate"])
+    # --paginate concatenates JSON arrays
+    items: list[dict] = []
+    dec = json.JSONDecoder()
+    idx = 0
+    raw = raw.strip()
+    while idx < len(raw):
+        chunk, end = dec.raw_decode(raw, idx)
+        items.extend(chunk)
+        idx = end
+        while idx < len(raw) and raw[idx] in " \n\r\t":
+            idx += 1
+    return [i for i in items if "pull_request" not in i]
+
+
+def ensure_label(gh: GhRunner, repo: str, name: str, color: str, desc: str) -> None:
+    try:
+        gh.run(["api", f"repos/{repo}/labels", "-X", "POST",
+                "-f", f"name={name}", "-f", f"color={color}",
+                "-f", f"description={desc}"])
+    except GhError as exc:
+        if "already_exists" not in str(exc) and "422" not in str(exc):
+            raise
+
+
+def create_issue(gh: GhRunner, repo: str, title: str, body: str,
+                 labels: list[str]) -> dict:
+    args = ["api", f"repos/{repo}/issues", "-X", "POST",
+            "-f", f"title={title}", "-f", f"body={body}"]
+    for lb in labels:
+        args += ["-f", f"labels[]={lb}"]
+    return json.loads(gh.run(args) or "{}")
+
+
+def update_issue(gh: GhRunner, repo: str, number: int, **fields) -> None:
+    args = ["api", f"repos/{repo}/issues/{number}", "-X", "PATCH"]
+    for k, v in fields.items():
+        args += ["-f", f"{k}={v}"]
+    gh.run(args)
+
+
+def comment(gh: GhRunner, repo: str, number: int, body: str) -> None:
+    gh.run(["api", f"repos/{repo}/issues/{number}/comments", "-X", "POST",
+            "-f", f"body={body}"])
+
+
+def add_sub_issue(gh: GhRunner, parent_node: str, child_node: str) -> None:
+    q = ("mutation($p: ID!, $c: ID!) { addSubIssue(input: {issueId: $p, "
+         "subIssueId: $c}) { issue { id } } }")
+    try:
+        gh.graphql(q, p=parent_node, c=child_node)
+    except GhError as exc:
+        # An existing identical link is success, not failure. GitHub words it
+        # several ways ("duplicate sub-issues", "may only have one parent").
+        msg = str(exc).lower()
+        if not any(s in msg for s in ("already", "duplicate sub-issue",
+                                      "only have one parent")):
+            raise

docassert-0.8.1/docassert/bridge/ops.py

@@ -0,0 +1,179 @@
+"""Bridge operations: scaffold, reconcile, status.
+
+scaffold  documents -> issues/board (idempotent; never deletes)
+reconcile board -> alerts (labels + one pinned scope report; never deletes)
+status    board -> read-only delivery figures
+
+The bridge never writes to documents/ — scope changes go through document PRs.
+"""
+from __future__ import annotations
+
+import json
+import re
+
+from . import gh as G
+from .plan import (
+    MARKER,
+    BridgePlan,
+    feature_body,
+    feature_title,
+    story_body,
+    story_title,
+)
+
+MARKER_RE = re.compile(r"<!-- docassert-bridge: ([A-Za-z0-9-]+) -->")
+SCOPE_REPORT_KEY = "scope-report"
+LABELS = {
+    "bridge:feature": ("1d76db", "Feature scaffolded from a product requirement"),
+    "bridge:story": ("0e8a16", "Story scaffolded from an approved user story"),
+    "scope:unverified": ("d93f0b", "No matching item in the governing documents"),
+    "scope:orphaned": ("b60205", "Its document item was removed or demoted"),
+}
+
+
+def _marker_of(issue: dict) -> str | None:
+    m = MARKER_RE.search(issue.get("body") or "")
+    return m.group(1) if m else None
+
+
+def _index(issues: list[dict]) -> dict[str, dict]:
+    out: dict[str, dict] = {}
+    for i in issues:
+        key = _marker_of(i)
+        if key and key not in out:          # first (oldest) wins
+            out[key] = i
+    return out
+
+
+def scaffold(plan: BridgePlan, gh: G.GhRunner, repo: str,
+             docs_url: str | None = None) -> list[str]:
+    """Make the repo's issues match the plan. Returns human-readable actions."""
+    actions: list[str] = []
+    for name, (color, desc) in LABELS.items():
+        G.ensure_label(gh, repo, name, color, desc)
+
+    issues = G.list_issues(gh, repo)
+    by_key = _index(issues)
+
+    def ensure(key: str, title: str, body: str, label: str) -> dict:
+        existing = by_key.get(key)
+        if existing is None:
+            created = G.create_issue(gh, repo, title, body, [label])
+            created["body"] = body
+            by_key[key] = created
+            actions.append(f"created #{created.get('number', '?')} {title}")
+            return created
+        if existing.get("title") != title or (existing.get("body") or "").strip() != body.strip():
+            G.update_issue(gh, repo, existing["number"], title=title, body=body)
+            actions.append(f"updated #{existing['number']} {title}")
+        if existing.get("state") == "closed" and key in plan.managed_ids:
+            pass  # closed means delivered; scaffold never reopens
+        return existing
+
+    for f in plan.features:
+        feat_issue = ensure(f.id, feature_title(f), feature_body(f, docs_url),
+                            "bridge:feature")
+        for s in f.stories:
+            story_issue = ensure(s.id, story_title(s), story_body(s, docs_url),
+                                 "bridge:story")
+            pnode, cnode = feat_issue.get("node_id"), story_issue.get("node_id")
+            if pnode and cnode:
+                G.add_sub_issue(gh, pnode, cnode)
+
+    for sk in plan.skipped:
+        actions.append(f"skipped {sk['id']}: {sk['reason']}")
+    return actions
+
+
+def reconcile(plan: BridgePlan, gh: G.GhRunner, repo: str) -> tuple[list[str], int]:
+    """Police the board against the documents. Returns (report lines, exit code)."""
+    for name, (color, desc) in LABELS.items():
+        G.ensure_label(gh, repo, name, color, desc)
+
+    managed = plan.managed_ids
+    issues = G.list_issues(gh, repo, state="open")
+    unverified, orphaned = [], []
+
+    for issue in issues:
+        key = _marker_of(issue)
+        if key == SCOPE_REPORT_KEY:
+            continue
+        labels = {lb["name"] for lb in issue.get("labels", [])}
+        number = issue["number"]
+
+        if key is None:
+            unverified.append(issue)
+            if "scope:unverified" not in labels:
+                gh.run(["api", f"repos/{repo}/issues/{number}/labels", "-X", "POST",
+                        "-f", "labels[]=scope:unverified"])
+                G.comment(gh, repo, number,
+                          "**Scope check:** this issue has no matching item in the "
+                          "governing documents. Scope is defined in the PMO repo; "
+                          "either link it to an approved item or move the scope "
+                          "change through a documents PR.")
+        elif key not in managed:
+            orphaned.append(issue)
+            if "scope:orphaned" not in labels:
+                gh.run(["api", f"repos/{repo}/issues/{number}/labels", "-X", "POST",
+                        "-f", "labels[]=scope:orphaned"])
+                G.comment(gh, repo, number,
+                          f"**Scope check:** `{key}` no longer resolves to an "
+                          "approved item in the documents (removed, renamed, or "
+                          "demoted). A human should decide whether to close this "
+                          "issue or restore the item.")
+
+    lines = [f"managed items: {len(managed)}",
+             f"open issues checked: {len(issues)}",
+             f"unverified: {len(unverified)}", f"orphaned: {len(orphaned)}"]
+    for i in unverified:
+        lines.append(f"  unverified: #{i['number']} {i['title']}")
+    for i in orphaned:
+        lines.append(f"  orphaned: #{i['number']} {i['title']} [{_marker_of(i)}]")
+
+    body = (MARKER.format(SCOPE_REPORT_KEY)
+            + "\n_Maintained by `docassert bridge reconcile`. The documents are "
+              "the authoritative scope source._\n\n```\n" + "\n".join(lines) + "\n```\n")
+    report = _index(G.list_issues(gh, repo)).get(SCOPE_REPORT_KEY)
+    if report is None:
+        G.create_issue(gh, repo, "Scope report — docassert bridge", body, [])
+    else:
+        G.update_issue(gh, repo, report["number"], body=body)
+
+    return lines, (1 if (unverified or orphaned) else 0)
+
+
+def status(plan: BridgePlan, gh: G.GhRunner, repo: str) -> dict:
+    """Read-only: delivery progress per feature from issue states."""
+    by_key = _index(G.list_issues(gh, repo))
+    out: dict = {"projects": []}
+    for p in plan.projects:
+        feats = []
+        for f in p["features"]:
+            states = [(by_key.get(s.id) or {}).get("state") for s in f.stories]
+            feats.append({
+                "id": f.id,
+                "issue": (by_key.get(f.id) or {}).get("number"),
+                "stories_total": len(f.stories),
+                "stories_closed": sum(1 for s in states if s == "closed"),
+                "closed": (by_key.get(f.id) or {}).get("state") == "closed",
+            })
+        done = sum(x["stories_closed"] for x in feats)
+        total = sum(x["stories_total"] for x in feats)
+        out["projects"].append({"id": p["id"], "features": feats,
+                                "stories_closed": done, "stories_total": total})
+    return out
+
+
+def render_status(data: dict) -> str:
+    lines = []
+    for p in data["projects"]:
+        lines.append(f"{p['id']}: {p['stories_closed']}/{p['stories_total']} stories closed")
+        for f in p["features"]:
+            mark = "✓" if f["closed"] else " "
+            lines.append(f"  [{mark}] {f['id']}: {f['stories_closed']}/{f['stories_total']}"
+                         + (f" (#{f['issue']})" if f["issue"] else " (no issue)"))
+    return "\n".join(lines) or "no qualifying projects"
+
+
+def to_json(data: dict) -> str:
+    return json.dumps(data, indent=2) + "\n"

docassert-0.8.1/docassert/bridge/plan.py

@@ -0,0 +1,178 @@
+"""Build the execution-bridge plan from the document graph (pure, no I/O).
+
+Scope authority flows one way: documents -> GitHub. This module decides WHAT
+should exist on the board (Features from product requirements, Stories from
+approved user stories); the executor makes GitHub match it. Nothing here, or
+anywhere in the bridge, writes to documents/.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ..graph import build_graph
+from ..loader import load
+
+APPROVED = {"approved", "baselined"}
+MARKER = "<!-- docassert-bridge: {} -->"
+
+
+@dataclass
+class Story:
+    id: str
+    text: str
+    feature_id: str
+    doc_path: str
+
+
+@dataclass
+class Feature:
+    id: str
+    text: str
+    doc_path: str
+    project: str
+    stories: list[Story] = field(default_factory=list)
+    acceptance: list[tuple[str, str]] = field(default_factory=list)  # (id, text)
+    tests: list[str] = field(default_factory=list)                   # tc ids
+
+
+@dataclass
+class BridgePlan:
+    projects: list[dict] = field(default_factory=list)   # {id, code, features}
+    skipped: list[dict] = field(default_factory=list)    # {id, reason}
+
+    @property
+    def features(self) -> list[Feature]:
+        return [f for p in self.projects for f in p["features"]]
+
+    @property
+    def stories(self) -> list[Story]:
+        return [s for f in self.features for s in f.stories]
+
+    @property
+    def managed_ids(self) -> set[str]:
+        return {f.id for f in self.features} | {s.id for s in self.stories}
+
+
+def _title(item_text: str, limit: int = 64) -> str:
+    """First sentence of the item text, trimmed for an issue title."""
+    first = item_text.split(". ")[0].rstrip(".")
+    return first if len(first) <= limit else first[: limit - 1].rstrip() + "…"
+
+
+def _anchors(documents_dir: Path) -> dict[str, dict]:
+    """project id -> {code, name} for every project anchor."""
+    out: dict[str, dict] = {}
+    for path in sorted(documents_dir.rglob("project.md")):
+        try:
+            doc = load(path)
+        except ValueError:
+            continue
+        if doc.kind == "project" and doc.id:
+            out[doc.id] = {"code": str(doc.frontmatter.get("code", "")),
+                           "name": str(doc.frontmatter.get("name", ""))}
+    return out
+
+
+def _story_docs(documents_dir: Path) -> dict[str, list]:
+    """project id -> its user-story documents."""
+    out: dict[str, list] = {}
+    for path in sorted(documents_dir.rglob("*.md")):
+        try:
+            doc = load(path)
+        except ValueError:
+            continue
+        if doc.kind == "user-story":
+            proj = str(doc.frontmatter.get("project", ""))
+            out.setdefault(proj, []).append(doc)
+    return out
+
+
+def build_bridge_plan(documents_dir: str | Path = "documents") -> BridgePlan:
+    """The gate (Decision D): a project qualifies when it has a user-story
+    document with approved status, and every approved story traces to an
+    existing product requirement. Draft/proposed stories never reach the board.
+    """
+    documents_dir = Path(documents_dir)
+    graph = build_graph(documents_dir)
+    plan = BridgePlan()
+
+    for proj_id, meta in _anchors(documents_dir).items():
+        docs = _story_docs(documents_dir).get(proj_id, [])
+        if not docs:
+            plan.skipped.append({"id": proj_id, "reason": "no user-story document"})
+            continue
+        approved_docs = [d for d in docs
+                         if str(d.frontmatter.get("status", "")).lower() in APPROVED]
+        if not approved_docs:
+            plan.skipped.append({"id": proj_id, "reason": "user stories not approved"})
+            continue
+
+        code = meta["code"]
+        stories = [i for i in graph.by_type.get("US", [])
+                   if i.project == code and i.doc_status.lower() in APPROVED]
+        features: dict[str, Feature] = {}
+        problems: list[str] = []
+        for s in stories:
+            targets = s.targets("traces")
+            parents = [t for t in targets if graph.canonical(t) is not None]
+            if not parents:
+                problems.append(f"{s.id} has no resolvable traces link")
+                continue
+            for pid in parents:
+                parent = graph.canonical(pid)
+                if parent is None:      # filtered above; narrows the type
+                    continue
+                feat = features.get(parent.id)
+                if feat is None:
+                    feat = Feature(id=parent.id, text=parent.text,
+                                   doc_path=parent.doc_path, project=proj_id)
+                    feat.acceptance = [(a.id, a.text) for a in
+                                       graph.children(parent.id, "verifies", "AC")]
+                    for aid, _ in feat.acceptance:
+                        feat.tests += [t.id for t in graph.children(aid, "tests", "TC")]
+                    features[parent.id] = feat
+                feat.stories.append(Story(id=s.id, text=s.text,
+                                          feature_id=parent.id, doc_path=s.doc_path))
+        if problems:
+            plan.skipped.append({"id": proj_id,
+                                 "reason": "; ".join(problems)})
+            continue
+        plan.projects.append({"id": proj_id, "code": code, "name": meta["name"],
+                              "features": list(features.values())})
+    return plan
+
+
+def feature_title(f: Feature) -> str:
+    return f"[{f.id}] {_title(f.text)}"
+
+
+def story_title(s: Story) -> str:
+    return f"[{s.id}] {_title(s.text)}"
+
+
+def feature_body(f: Feature, docs_url: str | None) -> str:
+    lines = [MARKER.format(f.id),
+             "_Managed by the docassert bridge. Scope lives in the documents;"
+             " edits here are overwritten._", "",
+             f.text, "", f"**Project:** {f.project}"]
+    if docs_url:
+        lines.append(f"**Source:** {docs_url}/{f.doc_path}")
+    if f.stories:
+        lines += ["", "**Stories:**"] + [f"- {s.id}" for s in f.stories]
+    if f.acceptance:
+        lines += ["", "**Acceptance criteria:**"] + \
+                 [f"- [ ] {aid}: {text}" for aid, text in f.acceptance]
+    if f.tests:
+        lines += ["", "**Verified by:** " + ", ".join(sorted(set(f.tests)))]
+    return "\n".join(lines) + "\n"
+
+
+def story_body(s: Story, docs_url: str | None) -> str:
+    lines = [MARKER.format(s.id),
+             "_Managed by the docassert bridge. Scope lives in the documents;"
+             " edits here are overwritten._", "",
+             s.text, "", f"**Feature:** {s.feature_id}"]
+    if docs_url:
+        lines.append(f"**Source:** {docs_url}/{s.doc_path}")
+    return "\n".join(lines) + "\n"

{docassert-0.7.1 → docassert-0.8.1}/docassert/cli.py

@@ -289,6 +289,42 @@ def cmd_new(args: argparse.Namespace) -> int:
     return 0
 
 
+
+
+def cmd_bridge(args: argparse.Namespace) -> int:
+    """Execution bridge: scaffold/police/read the GitHub board from the docs.
+    Scope flows documents -> GitHub only; the bridge never edits documents."""
+    from .bridge import build_bridge_plan, ops
+    from .bridge import gh as ghmod
+
+    plan = build_bridge_plan(args.documents_dir)
+    gh = ghmod.DryRunner() if getattr(args, "dry_run", False) else ghmod.GhRunner()
+
+    if args.action == "scaffold":
+        actions = ops.scaffold(plan, gh, args.repo, docs_url=args.docs_url)
+        for a in actions:
+            print(f"docassert bridge: {a}")
+        if isinstance(gh, ghmod.DryRunner):
+            print(f"docassert bridge: dry run — {len(gh.planned)} mutation(s) planned")
+            for m in gh.planned:
+                print(f"  {m}")
+        return 0
+    if args.action == "reconcile":
+        lines, code = ops.reconcile(plan, gh, args.repo)
+        for line in lines:
+            print(f"docassert bridge: {line}")
+        return code
+    if args.action == "status":
+        data = ops.status(plan, gh, args.repo)
+        sys.stdout.write(ops.to_json(data) if args.json else
+                         ops.render_status(data) + "\n")
+        if args.json and args.out:
+            Path(args.out).write_text(ops.to_json(data))
+        return 0
+    print(f"docassert bridge: unknown action {args.action!r}", file=sys.stderr)
+    return 2
+
+
 def main(argv: list[str] | None = None) -> int:
     from . import __version__
     parser = argparse.ArgumentParser(prog="docassert",
@@ -367,6 +403,18 @@ def main(argv: list[str] | None = None) -> int:
     docs_dir_opt(n)
     n.set_defaults(func=cmd_new)
 
+
+    b = sub.add_parser("bridge", help="Execution bridge: scaffold and police the GitHub board from approved stories.")
+    b.add_argument("action", choices=["scaffold", "reconcile", "status"],
+                   help="scaffold: docs -> issues/board · reconcile: police the board · status: delivery figures.")
+    b.add_argument("--repo", required=True, help="Target GitHub repo (OWNER/NAME) holding the issues.")
+    b.add_argument("--docs-url", help="Base URL of the documents repo, for source links in issue bodies.")
+    b.add_argument("--dry-run", action="store_true", help="Print planned mutations without executing them.")
+    b.add_argument("--json", action="store_true", help="status: emit JSON.")
+    b.add_argument("--out", help="status --json: also write to this path.")
+    docs_dir_opt(b)
+    b.set_defaults(func=cmd_bridge)
+
     args = parser.parse_args(argv)
     return args.func(args)
 

{docassert-0.7.1 → docassert-0.8.1/docassert.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.7.1
+Version: 0.8.1
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0
@@ -54,7 +54,7 @@ derived from the documents rather than self-reported.
 
 docassert is the reference implementation of **[PMO as Code](https://c4g-john.github.io/pmo-as-code/)** —
 a vendor-neutral standard for running a PMO from version-controlled, declarative
-files. It implements the [PMO as Code specification](https://github.com/c4g-john/pmo-as-code-spec) **v0.2**.
+files. It implements the [PMO as Code specification](https://github.com/c4g-john/pmo-as-code-spec) **v0.3** and passes its [conformance suite](https://github.com/c4g-john/pmo-as-code-spec/tree/main/conformance) in CI.
 
 ## Install
 
@@ -98,6 +98,7 @@ flagged as TODOs, never invented). The skill's source is
 | `docassert projects [--out] [--check]` | Generate / verify the project registry. |
 | `docassert new <kind> --project ID` | Scaffold a document from its template with identity filled in (`new project --code XYZ` auto-numbers the id); suggests the next free item ids. |
 | `docassert init [DIR]` | Scaffold the default config into a repo. |
+| `docassert bridge <action> --repo O/N` | Execution bridge: `scaffold` Features/Stories from approved user stories, `reconcile` (police the board against the docs), `status` (delivery figures). Needs the GitHub CLI. |
 | `docassert extract <file>` | Extract plain text from a source `.docx` / `.pdf` / `.md` / `.txt` (the first step of doc-to-pmo conversion). Needs the `convert` extra: `pip install "docassert[convert]"`. |
 
 Every document-reading command accepts `--documents-dir` (default `documents/`).

{docassert-0.7.1 → docassert-0.8.1}/docassert.egg-info/SOURCES.txt

@@ -89,10 +89,15 @@ docassert/_data/templates/runbook.template.md
 docassert/_data/templates/status-report.template.md
 docassert/_data/templates/test-cases.template.md
 docassert/_data/templates/user-story.template.md
+docassert/bridge/__init__.py
+docassert/bridge/gh.py
+docassert/bridge/ops.py
+docassert/bridge/plan.py
 docassert/status/__init__.py
 docassert/status/derive.py
 docassert/status/render.py
 tests/test_badge.py
+tests/test_bridge.py
 tests/test_config.py
 tests/test_consistency.py
 tests/test_defects.py