Wiki:Packs/Transformation Program Office/Modules

From WFM Labs

Modules for the Transformation Program Office pack (CP-OPS-015). Save the block under the filename in its heading and upload it as project knowledge with the rest of the pack. It needs only the Python standard library.

Read Wiki:Packs/Transformation Program Office first.

Block 8: program_view.py

"""program_view.py: Transformation Program Office, snapshot tools.

The program lead's working register is pushed one way to the program manager as a snapshot:
one JSON file plus a self-contained HTML view of it. This script writes, checks, compares and
renders snapshots. Standard library only.

Usage:
    python program_view.py demo OUTDIR               # illustrative v01 and v02 pushes
    python program_view.py validate FILE.json        # schema, codes, parent links, changes block
    python program_view.py diff OLD.json NEW.json [--write]   # changes block for NEW (--write stores it)
    python program_view.py render FILE.json OUT.html # self-contained HTML view
    python program_view.py feedback FILE.json LINES.txt   # check returned "ID CODE" lines

The snapshot schema is in 07-register-and-hand-off.md; TOP_KEYS, PROJECT_KEYS and ITEM_KEYS
below are the same lists. "review" is optional on projects and items.
A project or item is mapped if it has a code, or if its parent project has one.
"""
from __future__ import annotations

import argparse
import datetime as dt
import html
import json
import re
import sys
from pathlib import Path

CODE_RE = re.compile(r"^P(10|[0-9])(\.S\d{2}(\.X\d{2})?)?$")
VERSION_RE = re.compile(r"^v\d{2}$")
STATUSES = ["Planned", "Active", "At risk", "Blocked", "Done"]
TOP_KEYS = ["meta", "areas", "workstreams", "substreams", "bodies", "projects", "items", "changes"]
PROJECT_KEYS = ["id", "title", "code", "owner", "status", "due"]
ITEM_KEYS = ["id", "title", "code", "parent", "owner", "status", "due"]
OPTIONAL_KEYS = {"review"}
CHANGE_KEYS = ["added", "closed", "recoded", "renamed"]


# --- codes

def level(code: str) -> int:
    """1 = workstream (P2), 2 = sub-stream (P2.S03), 3 = body of work (P2.S03.X01)."""
    return code.count(".") + 1


def workstream_of(code: str) -> str:
    return code.split(".")[0] if code else ""


def parent_code(code: str) -> str:
    return code.rsplit(".", 1)[0] if "." in code else ""


def code_name(snap: dict, code: str) -> str:
    for k in ("workstreams", "substreams", "bodies"):
        if code in snap.get(k, {}):
            return snap[k][code]
    return ""


def effective_code(snap: dict, rec: dict) -> str:
    """A record's own code, else its parent project's code, else empty (unmapped)."""
    if rec.get("code"):
        return rec["code"]
    parent = rec.get("parent")
    if parent:
        for p in snap.get("projects", []):
            if p["id"] == parent:
                return p.get("code") or ""
    return ""


def unmapped(snap: dict) -> list[dict]:
    out = []
    for kind, recs in (("project", snap.get("projects", [])), ("item", snap.get("items", []))):
        for r in recs:
            if not effective_code(snap, r) and r.get("status") != "Done":
                out.append({**r, "kind": kind})
    return out


def _date_ok(s) -> bool:
    if s in ("", None):
        return True
    try:
        dt.date.fromisoformat(s)
        return True
    except (TypeError, ValueError):
        return False


# --- validate

def validate(snap: dict) -> tuple[list[str], list[str]]:
    """Return (errors, warnings). An empty error list means the snapshot can be pushed."""
    err, warn = [], []
    if not isinstance(snap, dict):
        return ["snapshot is not a JSON object"], []
    for k in TOP_KEYS:
        if k not in snap:
            err.append(f"missing top-level key: {k}")
    if err:
        return err, warn

    m = snap["meta"]
    for k in ("version", "date", "source"):
        if not m.get(k):
            err.append(f"meta.{k} is missing")
    if m.get("version") and not VERSION_RE.match(m["version"]):
        err.append(f"meta.version {m['version']!r} should look like v01, v02, ...")
    if m.get("date") and not _date_ok(m["date"]):
        err.append(f"meta.date {m['date']!r} is not YYYY-MM-DD")

    registry = {}
    for key, lvl in (("workstreams", 1), ("substreams", 2), ("bodies", 3)):
        for code, name in snap[key].items():
            if not CODE_RE.match(code):
                err.append(f"{key}: bad code {code!r}")
                continue
            if level(code) != lvl:
                err.append(f"{key}: {code} is a level-{level(code)} code, expected level {lvl}")
            if not name:
                err.append(f"{key}: {code} has no name")
            registry[code] = lvl
    for code, lvl in registry.items():
        if lvl > 1 and parent_code(code) not in registry:
            err.append(f"{code} has no parent {parent_code(code)} in the code list")

    seen_ws = {}
    area_codes = set()
    for a in snap["areas"]:
        if not a.get("code") or not a.get("name"):
            err.append(f"area without code or name: {a}")
        if a.get("code") in area_codes:
            err.append(f"duplicate area code {a.get('code')}")
        area_codes.add(a.get("code"))
        for w in a.get("workstreams", []):
            if w not in snap["workstreams"]:
                err.append(f"area {a.get('code')} lists unknown workstream {w}")
            if w in seen_ws:
                err.append(f"workstream {w} is in two areas ({seen_ws[w]}, {a.get('code')})")
            seen_ws[w] = a.get("code")
    for w in snap["workstreams"]:
        if w not in seen_ws:
            err.append(f"workstream {w} is in no area")

    ids = {}
    project_ids = set()
    for kind, recs, keys in (("project", snap["projects"], PROJECT_KEYS), ("item", snap["items"], ITEM_KEYS)):
        for r in recs:
            rid = r.get("id", "?")
            for k in keys:
                if k not in r:
                    err.append(f"{kind} {rid}: missing field {k}")
            extra = set(r) - set(keys) - OPTIONAL_KEYS
            if extra:
                warn.append(f"{kind} {rid}: unexpected fields {sorted(extra)}")
            if rid in ids:
                err.append(f"duplicate id {rid}")
            ids[rid] = kind
            if kind == "project":
                project_ids.add(rid)
            code = r.get("code") or ""
            if code and not CODE_RE.match(code):
                err.append(f"{kind} {rid}: bad code {code!r}")
            elif code and code not in registry:
                err.append(f"{kind} {rid}: code {code} is not in the code list")
            if r.get("status") not in STATUSES:
                err.append(f"{kind} {rid}: status {r.get('status')!r} not in {STATUSES}")
            for f in ("due", "review"):
                if not _date_ok(r.get(f)):
                    err.append(f"{kind} {rid}: {f} {r.get(f)!r} is not YYYY-MM-DD")
            if not r.get("title"):
                err.append(f"{kind} {rid}: no title")
            if not r.get("owner"):
                warn.append(f"{kind} {rid}: no owner")
    for it in snap["items"]:
        p = it.get("parent")
        if p and p not in project_ids:
            err.append(f"item {it.get('id')}: parent {p} is not a project in this snapshot")
        if it.get("code") and p:
            pc = next((x.get("code") for x in snap["projects"] if x["id"] == p), "")
            if pc and workstream_of(pc) != workstream_of(it["code"]):
                warn.append(f"item {it['id']}: code {it['code']} is in a different workstream from parent {p} ({pc})")
    for r in unmapped(snap):
        if not r.get("review"):
            err.append(f"{r['kind']} {r['id']}: unmapped and has no review date")

    ch = snap["changes"]
    for k in CHANGE_KEYS:
        if not isinstance(ch.get(k), list):
            err.append(f"changes.{k} must be a list")
    if not err:
        for rid in ch["added"]:
            if rid not in ids:
                err.append(f"changes.added: {rid} is not in this snapshot")
        for k in ("recoded", "renamed"):
            for c in ch[k]:
                if not {"id", "from", "to"} <= set(c):
                    err.append(f"changes.{k}: entry needs id, from and to: {c}")
                elif c["id"] not in ids:
                    err.append(f"changes.{k}: {c['id']} is not in this snapshot")
        for c in ch["recoded"]:
            rec = next((r for r in snap["projects"] + snap["items"] if r["id"] == c.get("id")), None)
            if rec is not None and (rec.get("code") or "") != (c.get("to") or ""):
                err.append(f"changes.recoded: {c['id']} says to={c.get('to')!r} but its code is {rec.get('code')!r}")
    return err, warn


# --- diff

def diff(old: dict, new: dict) -> dict:
    """Changes block for NEW: added; closed (moved to Done, or gone); recoded (own code, "" =
    unmapped); renamed (title)."""
    def recs(s):
        return {r["id"]: r for r in s.get("projects", []) + s.get("items", [])}
    o, n = recs(old), recs(new)
    added = [i for i in n if i not in o]
    closed = [i for i in o if i not in n]
    closed += [i for i in n if i in o and n[i].get("status") == "Done" and o[i].get("status") != "Done"]
    recoded = [{"id": i, "from": o[i].get("code") or "", "to": n[i].get("code") or ""}
               for i in n if i in o and (o[i].get("code") or "") != (n[i].get("code") or "")]
    renamed = [{"id": i, "from": o[i]["title"], "to": n[i]["title"]}
               for i in n if i in o and o[i].get("title") != n[i].get("title")]
    return {"added": sorted(added), "closed": sorted(closed),
            "recoded": sorted(recoded, key=lambda c: c["id"]), "renamed": sorted(renamed, key=lambda c: c["id"])}


# --- summary

def counts(snap: dict) -> dict:
    """Per-workstream counts of projects and items, plus the unmapped total."""
    out = {w: {"projects": 0, "items": 0, "open": 0, "at_risk": 0, "done": 0} for w in snap["workstreams"]}
    for r in snap["projects"] + snap["items"]:
        w = workstream_of(effective_code(snap, r))
        if not w or w not in out:
            continue
        c = out[w]
        c["projects" if r in snap["projects"] else "items"] += 1
        if r["status"] == "Done":
            c["done"] += 1
        else:
            c["open"] += 1
        if r["status"] in ("At risk", "Blocked"):
            c["at_risk"] += 1
    return {"workstreams": out, "unmapped": len(unmapped(snap)),
            "projects": len(snap["projects"]), "items": len(snap["items"])}


def feedback(snap: dict, lines: list[str]) -> list[tuple[str, str, str]]:
    """(id, code, verdict) per returned 'ID CODE' line. Never edits the snapshot: accepted lines
    go into the working register and show in the next push as recoded."""
    known = {r["id"] for r in snap["projects"] + snap["items"]}
    registry = set(snap["workstreams"]) | set(snap["substreams"]) | set(snap["bodies"])
    out = []
    for raw in lines:
        s = raw.split("#", 1)[0].strip()
        if not s:
            continue
        parts = re.split(r"\s*(?:->|=>|,|\t|\s)\s*", s, maxsplit=1)
        if len(parts) != 2:
            out.append((s, "", "unreadable: expected 'ID CODE'"))
            continue
        rid, code = parts[0], parts[1].strip()
        if rid not in known:
            verdict = "unknown id"
        elif not CODE_RE.match(code):
            verdict = "bad code format"
        elif code not in registry:
            verdict = "code not in the code list"
        else:
            verdict = "ok"
        out.append((rid, code, verdict))
    return out


# --- render

PAGE = """<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>__TITLE__</title>
<style>
:root{--ink:#1d2430;--muted:#5b6575;--line:#d9dee6;--bg:#f6f7f9;--card:#fff;--accent:#2f5d8a;--risk:#a33a2a;--done:#2f7a4a}
*{box-sizing:border-box}
body{margin:0;font:14px/1.45 system-ui,-apple-system,Segoe UI,Roboto,sans-serif;color:var(--ink);background:var(--bg)}
header{padding:20px 28px;background:var(--card);border-bottom:1px solid var(--line)}
h1{font-size:20px;margin:0 0 4px}h2{font-size:16px;margin:28px 0 10px}h3{font-size:14px;margin:0 0 6px}
.meta{color:var(--muted)}
main{padding:0 28px 40px;max-width:1200px}
.panel{background:var(--card);border:1px solid var(--line);border-radius:6px;padding:14px 16px;margin-top:16px}
.grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(200px,1fr));gap:10px}
.tile,.tile b{display:block;font-size:13px}
.tile .n{font-size:22px;font-weight:600}
.tile .s{color:var(--muted);font-size:12px}
.cards{display:grid;grid-template-columns:repeat(auto-fill,minmax(340px,1fr));gap:10px}
.card ul{margin:6px 0 0;padding-left:0;list-style:none}
.card li{padding:3px 0;border-top:1px solid var(--bg);font-size:13px}
code{font:12px ui-monospace,Menlo,Consolas,monospace;background:var(--bg);padding:1px 4px;border-radius:3px}
.st{font-size:11px;padding:1px 6px;border-radius:9px;border:1px solid var(--line);white-space:nowrap}
.st-At-risk,.st-Blocked{color:var(--risk);border-color:var(--risk)}
.st-Done{color:var(--done);border-color:var(--done)}
.area{color:var(--muted);font-size:12px;text-transform:uppercase;letter-spacing:.04em;margin-top:30px}
table{border-collapse:collapse;width:100%}td,th{text-align:left;padding:4px 8px;border-top:1px solid var(--line);font-size:13px;vertical-align:top}
.empty{color:var(--muted)}
</style>
</head>
<body>
<header><h1 id="title"></h1><div class="meta" id="meta"></div></header>
<main>
<section class="panel" id="changes"></section>
<h2>At a glance</h2>
<div class="grid" id="glance"></div>
<div id="streams"></div>
<h2 id="unmapped-h">Unmapped</h2>
<section class="panel" id="unmapped"></section>
</main>
<script type="application/json" id="snapshot">__DATA__</script>
<script>
(function(){
var S=JSON.parse(document.getElementById('snapshot').textContent);
function el(t,c,x){var e=document.createElement(t);if(c)e.className=c;if(x!=null)e.textContent=x;return e;}
function add(p){for(var i=1;i<arguments.length;i++){var a=arguments[i];if(a!=null)p.appendChild(typeof a==='string'?document.createTextNode(a):a);}return p;}
function code(c){return el('code',null,c||'unmapped');}
function st(s){return el('span','st st-'+String(s).replace(/ /g,'-'),s);}
var names={};['workstreams','substreams','bodies'].forEach(function(k){for(var c in S[k])names[c]=S[k][c];});
var proj={};S.projects.forEach(function(p){proj[p.id]=p;});
function eff(r){if(r.code)return r.code;if(r.parent&&proj[r.parent])return proj[r.parent].code||'';return '';}
function pl(n,w){return n+' '+w+(n===1?'':'s');}
function ws(c){return c?c.split('.')[0]:'';}
function line(r){var li=el('li');add(li,code(r.id),' ',r.title,' ',(r.code&&r.code!==eff(proj[r.parent]||{}))?code(r.code):null,' ',st(r.status),' ',el('span','meta',(r.owner||'no owner')+(r.due?' · due '+r.due:'')));return li;}

document.title=S.meta.source+' '+S.meta.version;
document.getElementById('title').textContent='Program snapshot '+S.meta.version;
document.getElementById('meta').textContent=S.meta.date+' · from '+S.meta.source+' · '+S.projects.length+' projects, '+S.items.length+' items · read-only: send feedback as ID-to-code lines';

var ch=S.changes,cp=document.getElementById('changes');
add(cp,el('h3',null,'What changed since the last push'));
var tb=el('table');
function row(label,list,fmt){var tr=el('tr');add(tr,el('th',null,label+' ('+list.length+')'));var td=el('td');if(!list.length)add(td,el('span','empty','none'));list.forEach(function(x,i){if(i)add(td,', ');add(td,fmt(x));});add(tr,td);add(tb,tr);}
function byId(id){var r=S.projects.concat(S.items).filter(function(x){return x.id===id;})[0];var s=el('span');add(s,code(id),r?' '+r.title:'');return s;}
row('Added',ch.added,byId);
row('Closed',ch.closed,byId);
row('Re-coded',ch.recoded,function(c){var s=el('span');add(s,code(c.id),' ',code(c.from),' to ',code(c.to));return s;});
row('Renamed',ch.renamed,function(c){var s=el('span');add(s,code(c.id),' "'+c.from+'" to "'+c.to+'"');return s;});
add(cp,tb);

var cnt={};for(var w in S.workstreams)cnt[w]={p:0,i:0,open:0,risk:0,done:0};
var all=S.projects.concat(S.items),un=[];
all.forEach(function(r){var w=ws(eff(r));if(!w||!cnt[w]){if(r.status!=='Done')un.push(r);return;}var c=cnt[w];if(proj[r.id]===r)c.p++;else c.i++;if(r.status==='Done')c.done++;else c.open++;if(r.status==='At risk'||r.status==='Blocked')c.risk++;});
var g=document.getElementById('glance');
for(var w2 in S.workstreams){var c=cnt[w2],t=el('div','tile');add(t,el('b',null,w2+' '+S.workstreams[w2]),el('div','n',String(c.open)),el('div','s',pl(c.p,'project')+', '+pl(c.i,'item')+' · '+c.risk+' at risk or blocked · '+c.done+' done'));add(g,t);}
var tu=el('div','tile');add(tu,el('b',null,'Unmapped'),el('div','n',String(un.length)),el('div','s','held with a review date'));add(g,tu);

var host=document.getElementById('streams');
S.areas.forEach(function(a){
  add(host,el('div','area',a.code+' · '+a.name));
  a.workstreams.forEach(function(w){
    add(host,el('h2',null,w+' '+S.workstreams[w]));
    var cards=el('div','cards'),n=0;
    S.projects.filter(function(p){return ws(p.code)===w;}).forEach(function(p){
      n++;var cd=el('div','card');add(cd,add(el('h3'),code(p.id),' ',p.title));
      add(cd,add(el('div','meta'),code(p.code),' '+(names[p.code]||'')+' · ',st(p.status),' · '+p.owner+(p.due?' · due '+p.due:'')));
      var ul=el('ul');S.items.filter(function(i){return i.parent===p.id;}).forEach(function(i){add(ul,line(i));});
      if(ul.childNodes.length)add(cd,ul);add(cards,cd);});
    var loose=S.items.filter(function(i){return ws(i.code)===w&&!(i.parent&&proj[i.parent]&&ws(proj[i.parent].code)===w);});
    if(loose.length){n++;var cd2=el('div','card');add(cd2,el('h3',null,'Items coded here without a project here'));var ul2=el('ul');loose.forEach(function(i){add(ul2,line(i));});add(cd2,ul2);add(cards,cd2);}
    if(!n)add(cards,el('div','empty','No projects yet.'));
    add(host,cards);});});

var up=document.getElementById('unmapped');
if(!un.length)add(up,el('span','empty','Everything open is mapped to a code.'));
else{var t2=el('table');add(t2,add(el('tr'),el('th',null,'ID'),el('th',null,'Title'),el('th',null,'Owner'),el('th',null,'Status'),el('th',null,'Review by')));
un.forEach(function(r){add(t2,add(el('tr'),add(el('td'),code(r.id)),el('td',null,r.title),el('td',null,r.owner||''),add(el('td'),st(r.status)),el('td',null,r.review||'none set')));});add(up,t2);}
})();
</script>
</body>
</html>
"""


def render(snap: dict) -> str:
    data = json.dumps(snap, indent=1, ensure_ascii=False)
    # Keep the embedded JSON from closing its own script element.
    data = data.replace("</", "<\\/").replace("<!--", "<\\!--")
    title = html.escape(f"{snap['meta'].get('source', 'Program')} {snap['meta'].get('version', '')}")
    return PAGE.replace("__TITLE__", title).replace("__DATA__", data)


def extract(html_text: str) -> dict:
    """Read the snapshot back out of a rendered view (used by the tests and for audits)."""
    m = re.search(r'<script type="application/json" id="snapshot">(.*?)</script>', html_text, re.S)
    if not m:
        raise ValueError("no embedded snapshot")
    return json.loads(m.group(1).replace("<\\/", "</").replace("<\\!--", "<!--"))


# --- demo

AREAS = [
    ("A1", "Program office", ["P0"]),
    ("A2", "Data and standards", ["P1", "P2"]),
    ("A3", "Planning", ["P3", "P4", "P5"]),
    ("A4", "Agentic and automation", ["P6", "P7", "P8"]),
    ("A5", "Capability layer", ["P9", "P10"]),
]
WORKSTREAMS = {
    "P0": "Program office",
    "P1": "Data layer",
    "P2": "Process standards",
    "P3": "Planning platform, next phase",
    "P4": "One workforce-platform instance",
    "P5": "One method, one calendar",
    "P6": "Build environment",
    "P7": "Agentic forecasting",
    "P8": "Intraday automation",
    "P9": "Capability record and placement model",
    "P10": "Placement engine",
}
SUBSTREAMS = {
    "P0.S01": "Working register and hand-off",
    "P0.S02": "Benefits tracking",
    "P1.S01": "Definitions register",
    "P1.S02": "Single data model",
    "P1.S03": "Semantic layer",
    "P2.S01": "Standards stack",
    "P2.S02": "Writing function",
    "P2.S03": "Risk Desk",
    "P2.S04": "Schedule change requests",
    "P2.S05": "Partner capacity requests",
    "P3.S01": "Evergreen plan",
    "P3.S02": "Assumption register and variance",
    "P4.S01": "Instance consolidation",
    "P5.S01": "Method standard",
    "P5.S02": "Planning calendar",
    "P6.S01": "Environment and guardrails",
    "P7.S01": "Forecasting agent pilot",
    "P8.S01": "Live view",
    "P8.S02": "Fifteen-minute actions",
    "P9.S01": "Capability record",
    "P9.S02": "Supply elasticity",
    "P10.S01": "Engine design",
}
BODIES = {
    "P1.S01.X01": "Core metric definitions, first twelve",
    "P2.S01.X01": "Standards stack, first edition",
    "P2.S03.X01": "Risk Desk manual phase with the partner",
    "P2.S03.X02": "Risk Desk internal build",
    "P3.S01.X01": "First evergreen quarter",
    "P7.S01.X01": "Forecasting agent on one queue family",
    "P8.S02.X01": "Off-queue time release pilot",
    "P9.S02.X01": "Partner surge rate card",
}

# id, title, code, owner, status, due
PROJECTS_V01 = [
    ("PRJ-01", "Stand up the working register and weekly push", "P0.S01", "Program lead", "Active", "2026-11-30"),
    ("PRJ-02", "Benefits baseline", "P0.S02", "Finance partner", "Planned", "2027-01-15"),
    ("PRJ-03", "Definitions register, first twelve metrics", "P1.S01.X01", "Data lead", "Active", "2026-12-11"),
    ("PRJ-04", "Single data model: interval and schedule tables", "P1.S02", "Data lead", "Active", "2027-01-29"),
    ("PRJ-05", "Semantic layer prototype", "P1.S03", "Data engineer", "Planned", "2027-02-26"),
    ("PRJ-06", "Standards stack, first edition", "P2.S01.X01", "Standards lead", "Active", "2026-12-04"),
    ("PRJ-07", "Writing function with the outsourcing partner", "P2.S02", "Standards lead", "Planned", "2027-01-08"),
    ("PRJ-08", "Risk Desk manual phase", "P2.S03.X01", "Risk desk lead", "Active", "2027-01-22"),
    ("PRJ-09", "Schedule change request standard", "P2.S04", "Standards lead", "Planned", "2027-02-05"),
    ("PRJ-10", "Evergreen plan, first quarter", "P3.S01.X01", "Planning lead", "Active", "2027-03-31"),
    ("PRJ-11", "Assumption register", "P3.S02", "Planning lead", "At risk", "2026-12-18"),
    ("PRJ-12", "Consolidate to one platform instance", "P4.S01", "Platform owner", "Planned", "2027-04-30"),
    ("PRJ-13", "One forecasting and capacity method", "P5.S01", "Methods lead", "Active", "2027-01-15"),
    ("PRJ-14", "One planning calendar", "P5.S02", "Methods lead", "Active", "2026-12-11"),
    ("PRJ-15", "Build environment and guardrails", "P6.S01", "Build lead", "Active", "2026-12-18"),
    ("PRJ-16", "Forecasting agent pilot", "P7.S01.X01", "Forecasting lead", "Planned", "2027-03-12"),
    ("PRJ-17", "Live intraday view", "P8.S01", "Real-time lead", "Active", "2027-02-12"),
    ("PRJ-18", "Off-queue time release pilot", "P8.S02.X01", "Real-time lead", "Planned", "2027-03-26"),
    ("PRJ-19", "Capability record, data design", "P9.S01", "Capability lead", "Planned", "2027-05-28"),
    ("PRJ-20", "Partner surge rate card", "P9.S02.X01", "Partner manager", "At risk", "2027-01-29"),
    ("PRJ-21", "Placement engine, options paper", "P10.S01", "Capability lead", "Planned", "2027-06-30"),
    ("PRJ-22", "Program charter and decision log", "P0", "Program lead", "Done", "2026-10-30"),
    ("PRJ-23", "Site staffing review requested by an operations director", "", "Program lead", "Planned", ""),
    ("PRJ-24", "Supply tuning: weekly partner volume call", "P9.S02", "Partner manager", "Active", "2026-12-18"),
]
REVIEW = {"PRJ-23": "2026-11-20"}

# id, title, code, parent, owner, status, due
ITEMS_V01 = [
    ("T-001", "Agree register fields and code list", "", "PRJ-01", "Program lead", "Done", "2026-10-30"),
    ("T-002", "First JSON and HTML push", "", "PRJ-01", "Program lead", "Done", "2026-11-02"),
    ("T-003", "Agree push day with the program manager", "", "PRJ-01", "Program lead", "Active", "2026-11-13"),
    ("T-004", "Choose four benefit measures", "", "PRJ-02", "Finance partner", "Planned", "2026-12-11"),
    ("T-005", "Draft definitions: handled, offered, abandoned", "", "PRJ-03", "Data lead", "Active", "2026-11-20"),
    ("T-006", "Draft definitions: paid, productive, shrinkage", "", "PRJ-03", "Data lead", "Active", "2026-11-27"),
    ("T-007", "Sign-off route for definitions", "", "PRJ-03", "Data lead", "Planned", "2026-12-04"),
    ("T-008", "Interval table design", "", "PRJ-04", "Data engineer", "Active", "2026-12-04"),
    ("T-009", "Schedule table design", "", "PRJ-04", "Data engineer", "Planned", "2026-12-18"),
    ("T-010", "Source system inventory", "", "PRJ-04", "Data engineer", "Done", "2026-10-30"),
    ("T-011", "Pick three measures to serve first", "", "PRJ-05", "Data engineer", "Planned", "2027-01-15"),
    ("T-012", "Standards stack outline", "", "PRJ-06", "Standards lead", "Done", "2026-10-30"),
    ("T-013", "Process card template", "", "PRJ-06", "Standards lead", "Active", "2026-11-20"),
    ("T-014", "Review roles and approval rule", "", "PRJ-06", "Standards lead", "Active", "2026-11-27"),
    ("T-015", "Partner writing brief", "", "PRJ-07", "Standards lead", "Planned", "2026-12-11"),
    ("T-016", "Style and review checklist for partner writers", "", "PRJ-07", "Standards lead", "Planned", "2026-12-18"),
    ("T-017", "Daily signal list template", "", "PRJ-08", "Risk desk lead", "Active", "2026-11-13"),
    ("T-018", "Weekly review agenda with the partner", "", "PRJ-08", "Risk desk lead", "Active", "2026-11-20"),
    ("T-019", "Severity rule: reach by duration", "", "PRJ-08", "Risk desk lead", "Done", "2026-11-02"),
    ("T-020", "Executive alert one-screen template", "", "PRJ-08", "Risk desk lead", "Active", "2026-11-20"),
    ("T-021", "Expense band agreed with finance", "", "PRJ-08", "Finance partner", "Blocked", "2026-11-27"),
    ("T-022", "Change request intake form", "", "PRJ-09", "Standards lead", "Planned", "2027-01-15"),
    ("T-023", "Quarter-one assumptions list", "", "PRJ-10", "Planning lead", "Active", "2026-12-04"),
    ("T-024", "Monthly re-plan cadence", "", "PRJ-10", "Planning lead", "Planned", "2027-01-08"),
    ("T-025", "Variance read in both directions", "", "PRJ-11", "Planning lead", "At risk", "2026-12-11"),
    ("T-026", "Owner for each assumption", "", "PRJ-11", "Planning lead", "Active", "2026-11-27"),
    ("T-027", "Instance inventory", "", "PRJ-12", "Platform owner", "Planned", "2026-12-18"),
    ("T-028", "Method gap list across teams", "", "PRJ-13", "Methods lead", "Active", "2026-11-27"),
    ("T-029", "Shrinkage method standard", "", "PRJ-13", "Methods lead", "Planned", "2026-12-18"),
    ("T-030", "Calendar draft", "", "PRJ-14", "Methods lead", "Active", "2026-11-20"),
    ("T-031", "Calendar sign-off", "", "PRJ-14", "Methods lead", "Planned", "2026-12-11"),
    ("T-032", "Repository and review rules", "", "PRJ-15", "Build lead", "Active", "2026-11-27"),
    ("T-033", "Data access for builders", "", "PRJ-15", "Build lead", "Blocked", "2026-12-04"),
    ("T-034", "Back-test plan", "", "PRJ-16", "Forecasting lead", "Planned", "2027-01-22"),
    ("T-035", "Forward-test plan", "", "PRJ-16", "Forecasting lead", "Planned", "2027-02-12"),
    ("T-036", "Live view wireframe", "", "PRJ-17", "Real-time lead", "Active", "2026-11-27"),
    ("T-037", "Interval feed latency check", "", "PRJ-17", "Data engineer", "Active", "2026-12-04"),
    ("T-038", "Release rules for off-queue time", "", "PRJ-18", "Real-time lead", "Planned", "2027-01-29"),
    ("T-039", "Capability fields first draft", "", "PRJ-19", "Capability lead", "Planned", "2027-02-26"),
    ("T-040", "Surge rate options with the partner", "", "PRJ-20", "Partner manager", "At risk", "2026-12-11"),
    ("T-041", "Contract clause review", "", "PRJ-20", "Partner manager", "Blocked", "2026-12-18"),
    ("T-042", "Options paper outline", "", "PRJ-21", "Capability lead", "Planned", "2027-03-31"),
    ("T-043", "Charter signed", "", "PRJ-22", "Program lead", "Done", "2026-10-23"),
    ("T-044", "Gather site staffing questions", "", "PRJ-23", "Program lead", "Planned", ""),
    ("T-045", "Weekly partner volume call agenda", "", "PRJ-24", "Partner manager", "Active", "2026-11-20"),
    ("T-046", "Partner flex range per week", "", "PRJ-24", "Partner manager", "Active", "2026-12-04"),
    ("T-047", "Risk Desk feed from the live view", "P2.S03.X02", "PRJ-17", "Real-time lead", "Planned", "2027-02-26"),
    ("T-048", "Map each process to an owner", "P2.S01", None, "Standards lead", "Active", "2026-11-27"),
    ("T-049", "Definitions glossary on the intranet", "P1.S01", None, "Data lead", "Planned", "2026-12-18"),
    ("T-050", "Benefit tracking template", "P0.S02", None, "Finance partner", "Planned", "2026-12-18"),
    ("T-051", "Planner training on the evergreen plan", "P3.S01", None, "Planning lead", "Planned", "2027-02-05"),
    ("T-052", "Agent review rubric", "P6.S01", None, "Build lead", "Planned", "2026-12-18"),
    ("T-053", "Partner capacity request standard", "P2.S05", None, "Standards lead", "Planned", "2027-02-26"),
    ("T-054", "Holiday-week staffing model for next month", "", None, "Planning lead", "Planned", ""),
    ("T-055", "Dashboard colour change request", "", None, "Data lead", "Planned", ""),
    ("T-056", "Move of one queue family to the second site", "", None, "Program lead", "Planned", ""),
    ("T-057", "Survey tool for frontline feedback", "", None, "Program lead", "Planned", ""),
    ("T-058", "Partner invoice query, October", "", None, "Finance partner", "Active", ""),
]
REVIEW.update({"T-044": "2026-11-20", "T-054": "2026-11-13", "T-055": "2026-11-27",
               "T-056": "2026-11-13", "T-057": "2026-12-04", "T-058": "2026-11-13"})


def _snapshot(version, date, projects, items, review):
    def rec(keys, r):
        d = dict(zip(keys, r))
        if r[0] in review:
            d["review"] = review[r[0]]
        return d
    return {"meta": {"version": version, "date": date, "source": "Transformation working register"},
            "areas": [{"code": c, "name": n, "workstreams": w} for c, n, w in AREAS],
            "workstreams": dict(WORKSTREAMS), "substreams": dict(SUBSTREAMS), "bodies": dict(BODIES),
            "projects": [rec(PROJECT_KEYS, r) for r in projects], "items": [rec(ITEM_KEYS, r) for r in items],
            "changes": {k: [] for k in CHANGE_KEYS}}


def demo_snapshots() -> tuple[dict, dict]:
    """The illustrative v01 and v02 pushes. v02 carries a computed changes block."""
    v01 = _snapshot("v01", "2026-11-02", PROJECTS_V01, ITEMS_V01, REVIEW)

    projects = [list(r) for r in PROJECTS_V01]
    items = [list(r) for r in ITEMS_V01]
    review = dict(REVIEW)

    def setp(pid, idx, val):
        next(r for r in projects if r[0] == pid)[idx] = val

    def seti(iid, idx, val):
        next(r for r in items if r[0] == iid)[idx] = val

    # A week in the working register: three closed, one redirected out, two re-coded, two renamed.
    for t in ("T-003", "T-013", "T-017"):
        seti(t, 5, "Done")
    seti("T-055", 2, "P1.S03")
    seti("T-055", 1, "Dashboard colour standard for the semantic layer")
    review.pop("T-055")
    items = [r for r in items if r[0] != "T-057"]
    setp("PRJ-11", 1, "Assumption register and variance read")
    seti("T-047", 2, "P8.S01")
    projects.append(["PRJ-25", "Risk Desk internal build", "P2.S03.X02", "Build lead", "Planned", "2027-04-30"])
    items += [
        ["T-059", "Watch-list review rule", "", "PRJ-08", "Risk desk lead", "Active", "2026-11-27"],
        ["T-060", "Incident record fields", "", "PRJ-08", "Risk desk lead", "Active", "2026-11-20"],
        ["T-061", "Data needs from the data layer", "", "PRJ-25", "Build lead", "Planned", "2027-01-15"],
        ["T-062", "Overtime spike in one queue family", "", None, "Real-time lead", "Planned", ""],
        ["T-063", "Peak-season hiring plan, next year", "", None, "Planning lead", "Planned", ""],
        ["T-064", "Partner reports to use the agreed definitions", "", None, "Partner manager", "Planned", ""],
    ]
    review.update({"T-062": "2026-11-16", "T-063": "2026-11-20", "T-064": "2026-11-23"})
    v02 = _snapshot("v02", "2026-11-09", projects, items, review)
    v02["changes"] = diff(v01, v02)
    return v01, v02


def demo(outdir: str) -> str:
    out = Path(outdir)
    out.mkdir(parents=True, exist_ok=True)
    v01, v02 = demo_snapshots()
    for s in (v01, v02):
        (out / f"snapshot-{s['meta']['version']}.json").write_text(json.dumps(s, indent=2, ensure_ascii=False))
        (out / f"program-view-{s['meta']['version']}.html").write_text(render(s))
    (out / "feedback-example.txt").write_text(
        "# Returned by the program manager: one 'ID CODE' line per suggested mapping\n"
        "T-064 P1.S01\nT-063 P3.S01\nT-054 P5.S02\nT-999 P2.S03\n")
    c = counts(v02)
    ch = v02["changes"]
    return (f"wrote {out}/snapshot-v01.json, snapshot-v02.json, program-view-v01.html, program-view-v02.html, "
            f"feedback-example.txt\n"
            f"v02: {len(v02['workstreams'])} workstreams, {c['projects']} projects, {c['items']} items, "
            f"{c['unmapped']} unmapped; changes: {len(ch['added'])} added, {len(ch['closed'])} closed, "
            f"{len(ch['recoded'])} re-coded, {len(ch['renamed'])} renamed")


# --- cli

def _load(path):
    return json.loads(Path(path).read_text())


def main(argv=None) -> int:
    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
    sub = ap.add_subparsers(dest="cmd", required=True)
    s = sub.add_parser("demo"); s.add_argument("outdir")
    s = sub.add_parser("validate"); s.add_argument("file")
    s = sub.add_parser("diff"); s.add_argument("old"); s.add_argument("new")
    s.add_argument("--write", action="store_true", help="store the changes block in NEW")
    s = sub.add_parser("render"); s.add_argument("file"); s.add_argument("out")
    s = sub.add_parser("feedback"); s.add_argument("file"); s.add_argument("lines")
    a = ap.parse_args(argv)
    if a.cmd == "demo":
        print(demo(a.outdir))
        return 0
    if a.cmd == "validate":
        err, warn = validate(_load(a.file))
        for w in warn:
            print(f"warn  {w}")
        for e in err:
            print(f"ERROR {e}")
        print("valid" if not err else f"{len(err)} error(s)")
        return 1 if err else 0
    if a.cmd == "diff":
        new = _load(a.new)
        ch = diff(_load(a.old), new)
        print(json.dumps(ch, indent=2, ensure_ascii=False))
        if a.write:
            new["changes"] = ch
            Path(a.new).write_text(json.dumps(new, indent=2, ensure_ascii=False))
        return 0
    if a.cmd == "render":
        snap = _load(a.file)
        err, _ = validate(snap)
        if err:
            print("refusing to render an invalid snapshot:\n  " + "\n  ".join(err), file=sys.stderr)
            return 1
        Path(a.out).write_text(render(snap))
        print(f"wrote {a.out}")
        return 0
    if a.cmd == "feedback":
        res = feedback(_load(a.file), Path(a.lines).read_text().splitlines())
        for rid, code, verdict in res:
            print(f"{rid:8} {code:12} {verdict}")
        return 0 if all(v == "ok" for _, _, v in res) else 1
    return 2


if __name__ == "__main__":
    sys.exit(main())

See also