docassert 0.14.1__tar.gz → 0.16.0__tar.gz

{docassert-0.14.1/docassert.egg-info → docassert-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.14.1
+Version: 0.16.0
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0

{docassert-0.14.1 → docassert-0.16.0}/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.14.1"
+__version__ = "0.16.0"

docassert-0.16.0/docassert/_data/criteria/operations.criteria.yaml

@@ -0,0 +1,40 @@
+# Audit criteria for the Operations kind (spec §13.21).
+kind: operations
+
+required_sections:
+  - Overview
+  - Services
+
+item_sections:
+  - section: Services
+    prefix: SVC
+
+checks:
+  - id: frontmatter-schema
+    type: structural
+    blocking: true
+    description: Frontmatter is valid against schema/operations.schema.json.
+  - id: frontmatter-complete
+    type: structural
+    blocking: once-proposed
+    description: Every schema-required frontmatter field is present (advisory while draft).
+  - id: required-sections
+    type: structural
+    blocking: once-proposed
+    description: Every required section is present and non-empty.
+  - id: items-well-formed
+    type: structural
+    blocking: true
+    description: Every SVC item follows the item grammar in its declared section.
+  - id: svc-items-complete
+    type: structural
+    blocking: once-proposed
+    description: Every SVC item states a Level (the commitment) and a Measure (how attainment is read).
+  - id: ops-review-fresh
+    type: structural
+    blocking: false
+    description: review_by is today or later; a past date is an amber input to derived status, never a merge blocker.
+  - id: unique-id
+    type: structural
+    blocking: true
+    description: The document id is unique across the repository.

{docassert-0.14.1 → docassert-0.16.0}/docassert/_data/criteria/risk-register.criteria.yaml

@@ -30,6 +30,11 @@ checks:
     type: structural
     blocking: once-proposed
     description: Every risk states a Probability, Impact, Owner, and Response.
+  - id: risk-disposition-valid
+    type: structural
+    blocking: true
+    description: Any Status field on a RISK item names a valid disposition (open/mitigated/accepted/closed).
+
   - id: unique-id
     type: structural
     blocking: true

docassert-0.16.0/docassert/_data/profiles/operations.yaml

@@ -0,0 +1,18 @@
+# Profile: operations
+#
+# For a repository (or project) whose work is a standing service catalog
+# rather than a delivery arc. The catalog itself is the one required kind;
+# the register and runbook are strongly recommended companions.
+name: operations
+description: >
+  A governed service catalog: the operations document is required, with the
+  risk register and runbook recommended alongside it.
+
+enforce_when: active
+
+expects:
+  required:
+    - operations
+  recommended:
+    - risk-register
+    - runbook

docassert-0.16.0/docassert/_data/schema/operations.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Operations frontmatter",
+  "type": "object",
+  "required": [
+    "kind",
+    "id",
+    "project",
+    "title",
+    "owner",
+    "status",
+    "review_by"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "kind": {
+      "const": "operations"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Z]{2,6}-[a-z0-9][a-z0-9-]*$",
+      "description": "Stable id, <CODE>-<slug>. Unique across documents/."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 3
+    },
+    "owner": {
+      "type": "string",
+      "minLength": 2
+    },
+    "status": {
+      "enum": [
+        "draft",
+        "proposed",
+        "approved",
+        "baselined"
+      ]
+    },
+    "project": {
+      "type": "string",
+      "pattern": "^PRJ-\\d{3,}-[A-Z]{2,6}$"
+    },
+    "review_by": {
+      "type": "string",
+      "format": "date",
+      "description": "The next operations review; a past date is an amber input to derived status."
+    }
+  }
+}

docassert-0.16.0/docassert/_data/templates/operations.template.md

@@ -0,0 +1,17 @@
+---
+kind: operations
+project: PRJ-000-XXX      # the owning project's id
+id: XXX-operations          # <CODE>-<slug>; the project code namespaces it
+title: My Operations
+owner: jane.doe
+status: draft
+review_by: 2026-12-31       # the next operations review; stale = amber
+---
+
+## Overview
+
+<!-- The operating period, the envelope, and what this catalog covers. -->
+
+## Services
+
+<!-- - **XXX-SVC-001**: What the service is. Level: the commitment, measurably stated. Measure: how attainment is read. -->

{docassert-0.14.1 → docassert-0.16.0}/docassert/status/derive.py

@@ -82,6 +82,9 @@ def _risks(graph, code=None):
         description = (item.text[:m.start()] if m else item.text).strip()
         rm = re.search(r"Response\s*:\s*(.+)$", item.text,
                        re.IGNORECASE | re.DOTALL)
+        raw = (_field_value(item.text, "status") or "open").lower()
+        disposition = raw if raw in {"open", "mitigated", "accepted",
+                                     "closed"} else "open"
         risks.append({
             "id": item.id,
             "description": description,
@@ -90,9 +93,12 @@ def _risks(graph, code=None):
             "impact": impact or "?",
             "owner": _field_value(item.text, "owner") or "?",
             "response": rm.group(1).strip() if rm else "",
+            "disposition": disposition,
             "score": _SEVERITY.get(prob, 0) * _SEVERITY.get(impact, 0),
         })
-    return sorted(risks, key=lambda r: -r["score"])
+    # open risks first, then by severity; dispositioned risks stay as record
+    return sorted(risks, key=lambda r: (r["disposition"] != "open",
+                                        -r["score"]))
 
 
 def _broken_references(graph, code=None):
@@ -107,6 +113,25 @@ def _broken_references(graph, code=None):
     return broken
 
 
+def _operations(docs):
+    """Operations documents with their review state."""
+    import datetime
+    out = []
+    for d in docs:
+        if d.kind != "operations":
+            continue
+        raw = d.frontmatter.get("review_by")
+        try:
+            due = (raw if isinstance(raw, datetime.date)
+                   else datetime.date.fromisoformat(str(raw)))
+            fresh = due >= datetime.date.today()
+            due_s = due.isoformat()
+        except (TypeError, ValueError):
+            fresh, due_s = False, str(raw)
+        out.append({"id": d.id, "review_by": due_s, "fresh": fresh})
+    return out
+
+
 def _latest_report(docs):
     reports = [d for d in docs if d.kind == "status-report"]
     if not reports:
@@ -173,6 +198,7 @@ def build_status(documents_dir=DOCUMENTS_DIR, project: str | None = None) -> dic
         },
         "coverage": _coverage(graph, cfg, code),
         "risks": _risks(graph, code),
+        "operations": _operations(docs),
         "broken_references": _broken_references(graph, code),
         "latest_report": _latest_report(docs),
         "completeness": completeness,
@@ -218,7 +244,7 @@ def build_index(documents_dir=DOCUMENTS_DIR) -> dict:
             "rag": m["rag"],
             "total": m["counts"]["total"],
             "failing": m["counts"]["failing"],
-            "risks": len(m["risks"]),
+            "risks": len([r for r in m["risks"] if r.get("disposition", "open") == "open"]),
             "coverage_gaps": sum(len(c["gaps"]) for c in m["coverage"]),
             "broken": len(m["broken_references"]),
             "completeness": m.get("completeness"),
@@ -238,7 +264,10 @@ def derive_rag(model) -> str:
     reported = (model["latest_report"] or {}).get("rag")
     completeness_gap = bool(comp and (comp["missing_required"] or comp["incomplete_required"]
                                       or comp["recommended_gaps"] or comp.get("unknown")))
-    if coverage_gap or model["risks"] or reported in {"amber", "red"} or completeness_gap:
+    open_risks = [r for r in model["risks"] if r.get("disposition", "open") == "open"]
+    stale_ops = [o for o in model.get("operations", []) if not o["fresh"]]
+    if (coverage_gap or open_risks or stale_ops
+            or reported in {"amber", "red"} or completeness_gap):
         return "amber"
     return "green"
 

{docassert-0.14.1 → docassert-0.16.0}/docassert/status/render.py

@@ -54,9 +54,17 @@ def render_markdown(model, summary: bool = False) -> str:
     if failing:
         out.append(f"- 🔴 **Documents failing audit**: {', '.join(failing)}")
 
+    for o in model.get("operations", []):
+        mark = "🟢" if o["fresh"] else "🟠"
+        verb = "next" if o["fresh"] else "OVERDUE since"
+        out.append(f"- {mark} **Operations review** (`{o['id']}`): {verb} {o['review_by']}")
     if model["risks"]:
-        out.append(f"- 🟠 **Open risks**: {len(model['risks'])}")
-        for r in model["risks"][:5]:
+        open_r = [r for r in model["risks"] if r.get("disposition", "open") == "open"]
+        rest = len(model["risks"]) - len(open_r)
+        mark = "🟠" if open_r else "🟢"
+        out.append(f"- {mark} **Open risks**: {len(open_r)}"
+                   + (f" ({rest} dispositioned)" if rest else ""))
+        for r in open_r[:5]:
             out.append(f"    - `{r['id']}` — {r['probability']}/{r['impact']} · owner: {r['owner']}")
 
     lr = model["latest_report"]
@@ -149,6 +157,12 @@ def render_html(model) -> str:
                      value, "var(--muted)")
         return f'<td style="color:{color};font-weight:600;">{esc(value)}</td>'
 
+    def disp(value):
+        color = {"open": "var(--amber)", "mitigated": "var(--ok)",
+                 "accepted": "var(--muted)", "closed": "var(--muted)"}.get(
+                     value, "var(--amber)")
+        return f'<td style="color:{color};font-weight:600;">{esc(value)}</td>'
+
     if model["risks"]:
         risk_rows = "".join(
             f'<tr><td><code>{esc(r["id"])}</code></td>'
@@ -156,15 +170,24 @@ def render_html(model) -> str:
             f'<td>{", ".join(f"<code>{esc(b)}</code>" for b in r["threatens"]) or "—"}</td>'
             + sev(r["probability"]) + sev(r["impact"])
             + f'<td>{esc(r["owner"])}</td>'
-            f'<td>{esc(r["response"]) or "—"}</td></tr>'
+            + disp(r.get("disposition", "open"))
+            + f'<td>{esc(r["response"]) or "—"}</td></tr>'
             for r in model["risks"])
         risks = ('<table><thead><tr><th>ID</th><th>Risk</th><th>Threatens</th>'
                  '<th>Probability</th><th>Impact</th><th>Owner</th>'
-                 '<th>Response</th></tr></thead>'
+                 '<th>Status</th><th>Response</th></tr></thead>'
                  f'<tbody>{risk_rows}</tbody></table>')
     else:
         risks = "<p>None open.</p>"
 
+    ops_html = "".join(
+        f'<div class="sig"><div class="sig-h"><span>Operations review · '
+        f'<code>{esc(o["id"])}</code></span><span style="color:'
+        + ("var(--ok)" if o["fresh"] else "var(--amber)") + ';font-weight:600;">'
+        + ("next " if o["fresh"] else "overdue since ") + f'{esc(o["review_by"])}'
+        '</span></div></div>'
+        for o in model.get("operations", []))
+
     problems = ""
     if model["broken_references"]:
         problems += ("<section><h2>Broken references</h2><ul>"
@@ -276,11 +299,11 @@ def render_html(model) -> str:
   </header>
   <p class="meta">Derived from {c['total']} documents · {c['kinds']} kinds ·
     {c['approved']} approved{scope} · generated {gen}. Do not edit — regenerated from the documents.</p>
-  <section><h2>Traceability coverage</h2>{coverage}</section>
+  <section><h2>Traceability coverage</h2>{coverage}{ops_html}</section>
   {document_set}
   {execution_html}
   {problems}
-  <section><h2>Open risks ({len(model['risks'])})</h2>{risks}</section>
+  <section><h2>Risks ({len([r for r in model['risks'] if r.get('disposition', 'open') == 'open'])} open of {len(model['risks'])})</h2>{risks}</section>
   <section><h2>Latest status report</h2><p>{report}</p></section>
   <section><h2>Documents ({c['total']})</h2>
     <table><thead><tr><th>Kind</th><th>ID</th><th>Status</th><th>Audit</th></tr></thead>

{docassert-0.14.1 → docassert-0.16.0}/docassert/structural.py

@@ -226,6 +226,7 @@ def check_project_id_format(doc: Document, ctx: dict) -> tuple[bool, str]:
 
 
 _RISK_FIELDS = ["Probability", "Impact", "Owner", "Response"]
+_DISPOSITIONS = {"open", "mitigated", "accepted", "closed"}
 _ADR_STATES = {"proposed", "accepted", "superseded", "deprecated", "rejected"}
 
 
@@ -255,6 +256,49 @@ def check_risk_items_complete(doc: Document, ctx: dict) -> tuple[bool, str]:
     return True, f"All {total} risk(s) state probability, impact, owner, and response."
 
 
+def check_risk_disposition_valid(doc: Document, ctx: dict) -> tuple[bool, str]:
+    """Where a RISK item yields Status, it names a valid disposition."""
+    bad, total = [], 0
+    for iid, text in _items_of_prefix(doc, ctx, "RISK"):
+        total += 1
+        value = _field_value(text, "Status")
+        if value is not None and value.lower() not in _DISPOSITIONS:
+            bad.append(f"{iid}: {value!r}")
+    if bad:
+        return False, ("invalid disposition (open|mitigated|accepted|closed): "
+                       + "; ".join(bad))
+    return True, f"All {total} risk disposition(s) valid (absent means open)."
+
+
+def check_svc_items_complete(doc: Document, ctx: dict) -> tuple[bool, str]:
+    """Every SVC item states a Level and a Measure."""
+    incomplete, total = [], 0
+    for iid, text in _items_of_prefix(doc, ctx, "SVC"):
+        total += 1
+        missing = [f for f in ("Level", "Measure") if _field_value(text, f) is None]
+        if missing:
+            incomplete.append(f'{iid} missing {", ".join(missing)}')
+    if incomplete:
+        return False, "; ".join(incomplete)
+    return True, f"All {total} service(s) state a level and a measure."
+
+
+def check_ops_review_fresh(doc: Document, ctx: dict) -> tuple[bool, str]:
+    """review_by is today or later (advisory; staleness ambers derived status)."""
+    import datetime
+    raw = doc.frontmatter.get("review_by")
+    if raw is None:
+        return False, "No review_by date."
+    try:
+        due = raw if isinstance(raw, datetime.date) else datetime.date.fromisoformat(str(raw))
+    except ValueError:
+        return False, f"review_by is not a date: {raw!r}"
+    today = datetime.date.today()
+    if due < today:
+        return False, f"operations review overdue since {due.isoformat()}"
+    return True, f"Next operations review {due.isoformat()}."
+
+
 def check_adr_items_have_status(doc: Document, ctx: dict) -> tuple[bool, str]:
     """Every ADR item declares a valid Status."""
     bad, total = [], 0
@@ -402,6 +446,9 @@ CHECKS: dict[str, Callable[[Document, dict], tuple[bool, str]]] = {
     "unique-id": check_unique_id,
     "items-well-formed": check_items_well_formed,
     "risk-items-complete": check_risk_items_complete,
+    "risk-disposition-valid": check_risk_disposition_valid,
+    "svc-items-complete": check_svc_items_complete,
+    "ops-review-fresh": check_ops_review_fresh,
     "adr-items-have-status": check_adr_items_have_status,
     "raci-one-accountable": check_raci_one_accountable,
     "story-format": check_story_format,

{docassert-0.14.1 → docassert-0.16.0/docassert.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.14.1
+Version: 0.16.0
 Summary: Unit testing for business documents — validate structured Markdown docs against a configurable audit standard.
 Author: C4G Enterprises Inc.
 License: Apache-2.0

{docassert-0.14.1 → docassert-0.16.0}/docassert.egg-info/SOURCES.txt

@@ -33,6 +33,7 @@ docassert/_data/criteria/charter.criteria.yaml
 docassert/_data/criteria/data-migration-plan.criteria.yaml
 docassert/_data/criteria/frnfr.criteria.yaml
 docassert/_data/criteria/hypercare-plan.criteria.yaml
+docassert/_data/criteria/operations.criteria.yaml
 docassert/_data/criteria/post-implementation-review.criteria.yaml
 docassert/_data/criteria/prd.criteria.yaml
 docassert/_data/criteria/project.criteria.yaml
@@ -47,6 +48,7 @@ docassert/_data/criteria/test-cases.criteria.yaml
 docassert/_data/criteria/user-story.criteria.yaml
 docassert/_data/profiles/agile-delivery.yaml
 docassert/_data/profiles/lean-startup.yaml
+docassert/_data/profiles/operations.yaml
 docassert/_data/profiles/regulated-industry.yaml
 docassert/_data/schema/adr.schema.json
 docassert/_data/schema/benefits-realization.schema.json
@@ -56,6 +58,7 @@ docassert/_data/schema/charter.schema.json
 docassert/_data/schema/data-migration-plan.schema.json
 docassert/_data/schema/frnfr.schema.json
 docassert/_data/schema/hypercare-plan.schema.json
+docassert/_data/schema/operations.schema.json
 docassert/_data/schema/post-implementation-review.schema.json
 docassert/_data/schema/prd.schema.json
 docassert/_data/schema/project.schema.json
@@ -77,6 +80,7 @@ docassert/_data/templates/charter.template.md
 docassert/_data/templates/data-migration-plan.template.md
 docassert/_data/templates/frnfr.template.md
 docassert/_data/templates/hypercare-plan.template.md
+docassert/_data/templates/operations.template.md
 docassert/_data/templates/post-implementation-review.template.md
 docassert/_data/templates/prd.template.md
 docassert/_data/templates/project.template.md

{docassert-0.14.1 → docassert-0.16.0}/tests/test_profiles.py

@@ -60,8 +60,9 @@ def test_load_profile_and_unknown():
     assert P.load_profile("does-not-exist", PROFILES) is None
 
 
-def test_available_lists_the_three_profiles():
-    assert set(P.available(PROFILES)) == {"regulated-industry", "lean-startup", "agile-delivery"}
+def test_available_lists_the_shipped_profiles():
+    assert set(P.available(PROFILES)) == {"regulated-industry", "lean-startup",
+                                          "agile-delivery", "operations"}
 
 
 # ── integration with the real repo ──────────────────────────────────────────

{docassert-0.14.1 → docassert-0.16.0}/tests/test_status.py

@@ -162,3 +162,114 @@ def test_render_html_risk_table():
     # severity cells are colored
     assert 'style="color:var(--bad);font-weight:600;">high</td>' in out \
         or 'style="color:var(--amber);font-weight:600;">medium</td>' in out
+
+
+# ── risk disposition (ENG-PR-002) ────────────────────────────────────────────
+def _risk_graph(*status_clauses):
+    from docassert.graph import Graph
+    from docassert.models import Item
+    g = Graph()
+    for i, clause in enumerate(status_clauses, 1):
+        text = (f"Risk {i} description. Probability: low. Impact: high. "
+                f"Owner: o.{i}.{clause} Response: watch.")
+        g.add(Item(f"XX-RISK-{i:03d}", "XX", "RISK", text, {}, "d.md",
+                   "risk-register", "approved", "S"))
+    return g
+
+
+def test_disposition_parsed_and_defaulted():
+    from docassert.status.derive import _risks
+    g = _risk_graph(" Status: Mitigated.", " Status: accepted.", "")
+    rs = _risks(g)
+    assert [r["disposition"] for r in rs] == ["open", "mitigated", "accepted"]
+    assert rs[0]["id"] == "XX-RISK-003"          # open risks sort first
+
+
+def test_rag_green_when_all_risks_dispositioned():
+    base = {"documents": [], "coverage": [], "broken_references": [],
+            "latest_report": None, "completeness": None}
+    open_r = dict(base, risks=[{"id": "R", "score": 2, "disposition": "open"}])
+    done_r = dict(base, risks=[{"id": "R", "score": 2, "disposition": "accepted"}])
+    assert S.derive_rag(open_r) == "amber"
+    assert S.derive_rag(done_r) == "green"
+
+
+def test_disposition_check_blocks_invalid(tmp_path):
+    from docassert.loader import load
+    from docassert.structural import check_risk_disposition_valid
+    p = tmp_path / "r.md"
+    p.write_text(
+        "---\nkind: risk-register\nid: XX-risk-register\n"
+        "project: PRJ-001-XX\ntitle: T\nowner: o\nstatus: approved\n---\n\n"
+        "## Overview\nx\n\n## Risks\n\n"
+        "- **XX-RISK-001**: Bad. Probability: low. Impact: low. Owner: o. "
+        "Status: wontfix. Response: r.\n", encoding="utf-8")
+    doc = load(p)
+    ok, detail = check_risk_disposition_valid(
+        doc, {"item_sections": [{"section": "Risks", "prefix": "RISK"}]})
+    assert not ok and "wontfix" in detail
+
+
+def test_render_html_shows_disposition_column():
+    _cd_root()
+    out = S.render_html(S.build_status(ROOT / "documents"))
+    assert "<th>Status</th>" in out and "open of" in out
+
+
+# ── operations kind (ENG-PR-003) ─────────────────────────────────────────────
+OPS_DOC = """---
+kind: operations
+id: XX-operations
+project: PRJ-001-XX
+title: Ops fixture
+owner: ops.owner
+status: approved
+review_by: {due}
+---
+
+## Overview
+x
+
+## Services
+
+- **XX-SVC-001**: Triage. Level: within 14 days. Measure: monthly report.
+"""
+
+
+def _ops_tree(tmp_path, due):
+    d = tmp_path / "documents" / "PRJ-001-XX"
+    d.mkdir(parents=True)
+    (d / "project.md").write_text(
+        "---\nkind: project\nid: PRJ-001-XX\ncode: XX\nname: Xy Ops\n"
+        "sponsor: sp.owner\nstatus: active\n---\n\n## Overview\nx\n\n## Scope\nx\n",
+        encoding="utf-8")
+    (d / "operations.md").write_text(OPS_DOC.format(due=due), encoding="utf-8")
+    return tmp_path / "documents"
+
+
+def test_stale_operations_review_ambers_status(tmp_path):
+    _cd_root()
+    m = S.build_status(_ops_tree(tmp_path, "2020-01-01"), project="PRJ-001-XX")
+    assert m["operations"][0]["fresh"] is False
+    assert m["rag"] == "amber"
+    assert "OVERDUE" in S.render_markdown(m)
+
+
+def test_fresh_operations_review_stays_green(tmp_path):
+    _cd_root()
+    m = S.build_status(_ops_tree(tmp_path, "2099-12-31"), project="PRJ-001-XX")
+    assert m["operations"][0]["fresh"] is True
+    assert m["rag"] == "green"
+    assert "Operations review" in S.render_html(m)
+
+
+def test_svc_and_freshness_checks(tmp_path):
+    from docassert.loader import load
+    from docassert.structural import check_ops_review_fresh, check_svc_items_complete
+    docs = _ops_tree(tmp_path, "2020-01-01")
+    doc = load(docs / "PRJ-001-XX" / "operations.md")
+    ctx = {"item_sections": [{"section": "Services", "prefix": "SVC"}]}
+    ok, _ = check_svc_items_complete(doc, ctx)
+    assert ok
+    fresh_ok, detail = check_ops_review_fresh(doc, ctx)
+    assert not fresh_ok and "overdue" in detail