docassert 0.15.0__tar.gz → 0.16.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.15.0
+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.15.0 → 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.15.0"
+__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.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.15.0 → docassert-0.16.0}/docassert/status/derive.py

@@ -113,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:
@@ -179,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,
@@ -245,7 +265,9 @@ def derive_rag(model) -> str:
     completeness_gap = bool(comp and (comp["missing_required"] or comp["incomplete_required"]
                                       or comp["recommended_gaps"] or comp.get("unknown")))
     open_risks = [r for r in model["risks"] if r.get("disposition", "open") == "open"]
-    if coverage_gap or open_risks or reported in {"amber", "red"} or completeness_gap:
+    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.15.0 → docassert-0.16.0}/docassert/status/render.py

@@ -54,6 +54,10 @@ 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"]:
         open_r = [r for r in model["risks"] if r.get("disposition", "open") == "open"]
         rest = len(model["risks"]) - len(open_r)
@@ -176,6 +180,14 @@ def render_html(model) -> str:
     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>"
@@ -287,7 +299,7 @@ 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}

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

@@ -270,6 +270,35 @@ def check_risk_disposition_valid(doc: Document, ctx: dict) -> tuple[bool, str]:
     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
@@ -418,6 +447,8 @@ CHECKS: dict[str, Callable[[Document, dict], tuple[bool, str]]] = {
     "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.15.0 → docassert-0.16.0/docassert.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docassert
-Version: 0.15.0
+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.15.0 → 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.15.0 → 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.15.0 → docassert-0.16.0}/tests/test_status.py

@@ -214,3 +214,62 @@ 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