@collective-intelligence/backlog 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. package/README.md +67 -34
  2. package/package.json +2 -2
  3. package/skills/generate-human-backlog-skills/SKILL.md +117 -0
  4. package/skills/generate-human-backlog-skills/references/client-profile.md +51 -0
  5. package/skills/generate-human-backlog-skills/references/eject.md +31 -0
  6. package/skills/{setup-human-backlog → generate-human-backlog-skills}/references/process.md +7 -5
  7. package/skills/{analyze-business-request/SKILL.md → generate-human-backlog-skills/references/templates/analyze-business-request/SKILL.md.tmpl} +14 -8
  8. package/skills/{analyze-business-request → generate-human-backlog-skills/references/templates/analyze-business-request}/references/plan-format.md +3 -3
  9. package/skills/{create-bug/SKILL.md → generate-human-backlog-skills/references/templates/create-bug/SKILL.md.tmpl} +7 -5
  10. package/skills/{create-bug → generate-human-backlog-skills/references/templates/create-bug}/references/azure-operations.md +1 -1
  11. package/skills/{create-business-request/SKILL.md → generate-human-backlog-skills/references/templates/create-business-request/SKILL.md.tmpl} +24 -18
  12. package/skills/{create-business-request → generate-human-backlog-skills/references/templates/create-business-request}/references/example.md +1 -1
  13. package/skills/{create-business-request → generate-human-backlog-skills/references/templates/create-business-request}/references/intake-guide.md +2 -2
  14. package/skills/{human-backlog-ado/SKILL.md → generate-human-backlog-skills/references/templates/human-backlog-ado/SKILL.md.tmpl} +32 -37
  15. package/skills/{plan-sprint/SKILL.md → generate-human-backlog-skills/references/templates/plan-sprint/SKILL.md.tmpl} +6 -4
  16. package/skills/{plan-sprint → generate-human-backlog-skills/references/templates/plan-sprint}/references/assessment-guide.md +1 -1
  17. package/skills/{plan-sprint → generate-human-backlog-skills/references/templates/plan-sprint}/references/operations.md +1 -1
  18. package/skills/{update-business-request/SKILL.md → generate-human-backlog-skills/references/templates/update-business-request/SKILL.md.tmpl} +4 -2
  19. package/skills/{human-backlog-ado → generate-human-backlog-skills}/scripts/ado.py +408 -106
  20. package/skills/generate-human-backlog-skills/scripts/render.py +361 -0
  21. package/skills/setup-human-backlog/SKILL.md +0 -83
  22. package/skills/setup-human-backlog/references/eject.md +0 -26
  23. /package/skills/{create-bug → generate-human-backlog-skills/references/templates/create-bug}/references/examples.md +0 -0
  24. /package/skills/{update-business-request → generate-human-backlog-skills/references/templates/update-business-request}/references/examples.md +0 -0
  25. /package/skills/{update-business-request → generate-human-backlog-skills/references/templates/update-business-request}/references/operations.md +0 -0
@@ -13,6 +13,15 @@ Human Backlog Config, resolved per key; the first source with a value wins
13
13
  Keys: provider ("azure-devops"), projectUrl (https://dev.azure.com/{org}/{project}),
14
14
  tenant, and optional ratingsPipelineUrl.
15
15
 
16
+ Client mappings, resolved per section; the first source with the section wins
17
+ 1. "humanBacklog.profile" in the nearest .devpunks/settings.json: types, fields, ratings, sprint
18
+ 2. config.json beside this script: mappings.types, mappings.fields, ratings, sprint
19
+ types maps businessRequest, epic, feature, productBacklogItem and bug to the client's work item
20
+ type names; fields maps friendly names (see FIELDS) to the client's reference names; ratings
21
+ sets the score scale (default min 1, max 5); sprint.lengthDays sets the sprint length in days,
22
+ in complete weeks (default 14). Commands keep the canonical names; the helper translates them
23
+ where it talks to Azure DevOps. Human States are never mapped.
24
+
16
25
  Commands
17
26
  whoami who the token belongs to
18
27
  get ID [ID ...] [--relations] read work items (HTML fields as plain text)
@@ -33,8 +42,9 @@ Commands
33
42
  attach ID --file FILE --receipt JSON [--comment TEXT] [--dry-run]
34
43
  sync-ratings [FEATURE_ID ... | --all] [--dry-run] recompute ratings from linked BRs
35
44
  apply PLAN.json [--dry-run] create a whole backlog plan (see analyze-business-request)
45
+ scan read-only JSON of the project's types, fields, states and iterations
36
46
  doctor read-only check of the config and the process: ready or blocked
37
- eject --out PATH zip the Human Backlog skills with config.json and MANIFEST.json
47
+ eject --from DIR --out PATH zip a checked Client Skill Set with MANIFEST.json (generator only)
38
48
 
39
49
  Field JSON uses friendly names (see FIELDS) or raw reference names. Values of
40
50
  rich-text fields may be written in a small Markdown subset (headings, bullet
@@ -45,6 +55,7 @@ import contextlib
45
55
  from datetime import date, timedelta
46
56
  import hashlib
47
57
  import html
58
+ import importlib.util
48
59
  import io
49
60
  import json
50
61
  import math
@@ -53,6 +64,7 @@ import re
53
64
  import subprocess
54
65
  import sys
55
66
  import tempfile
67
+ from types import SimpleNamespace
56
68
  import urllib.error
57
69
  import urllib.parse
58
70
  import urllib.request
@@ -65,7 +77,8 @@ CONFIG_ENV = {
65
77
  "ratingsPipelineUrl": "ADO_RATINGS_PIPELINE_URL",
66
78
  }
67
79
  REQUIRED_CONFIG = ("provider", "projectUrl", "tenant")
68
- CONFIG_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "config.json")
80
+ SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
81
+ CONFIG_FILE = os.path.join(SCRIPT_DIR, "config.json")
69
82
  PROJECT_URL = re.compile(r"^https://dev\.azure\.com/([^/]+)/([^/]+)/?$")
70
83
  ADO_RESOURCE = "499b84ac-1321-427f-aa17-267ca6975798"
71
84
 
@@ -116,6 +129,17 @@ TYPES = {
116
129
  "product backlog item": "Product Backlog Item",
117
130
  "bug": "Bug",
118
131
  }
132
+ # Canonical work item type names under their Client Profile keys; a profile maps them to the client's names.
133
+ TYPE_NAMES = {
134
+ "businessRequest": "Business Request",
135
+ "epic": "Epic",
136
+ "feature": "Feature",
137
+ "productBacklogItem": "Product Backlog Item",
138
+ "bug": "Bug",
139
+ }
140
+ RATINGS = {"min": 1, "max": 5}
141
+ SPRINT = {"lengthDays": 14}
142
+ WEEK_WORDS = {1: "one", 2: "two", 3: "three", 4: "four"}
119
143
 
120
144
  # Allowed parent type for each child type: the backlog hierarchy of the process.
121
145
  # Business Request sits at Feature level but never has a parent or children.
@@ -128,7 +152,7 @@ ALLOWED_PARENT = {
128
152
  }
129
153
 
130
154
  # Process fields the skills read or write on each work-item type, beside the System fields every
131
- # type has. `doctor` checks them; setup-human-backlog/references/process.md lists them for the team.
155
+ # type has. `doctor` checks them; generate-human-backlog-skills/references/process.md lists them for the team.
132
156
  PROCESS_FIELDS = {
133
157
  "Epic": (),
134
158
  "Feature": ("Microsoft.VSTS.Common.AcceptanceCriteria", "Custom.BusinessValueScore", "Custom.Urgency"),
@@ -194,6 +218,9 @@ Human States: Received, In analysis, Planned, In progress, On staging, Live, Rej
194
218
  A stale --expected-rev is refused before any write. --dry-run reports the decision and writes nothing."""
195
219
 
196
220
  _token = None
221
+ _tables = None
222
+ # Eject proves a Client Skill Set with its own config.json only; see pin_config().
223
+ _pinned = None
197
224
 
198
225
 
199
226
  def die(msg):
@@ -229,8 +256,11 @@ def nearest_settings():
229
256
 
230
257
  def load_config():
231
258
  """Resolve the Human Backlog Config (see the module help); stop on a missing or invalid key."""
232
- env = {key: os.environ[name] for key, name in CONFIG_ENV.items() if os.environ.get(name)}
233
- sources = (env, nearest_settings(), json_object(CONFIG_FILE))
259
+ if _pinned is not None:
260
+ sources = (json_object(_pinned),)
261
+ else:
262
+ env = {key: os.environ[name] for key, name in CONFIG_ENV.items() if os.environ.get(name)}
263
+ sources = (env, nearest_settings(), json_object(CONFIG_FILE))
234
264
  config = {}
235
265
  for key in CONFIG_ENV:
236
266
  value = next((source[key] for source in sources if source.get(key)), None)
@@ -238,6 +268,8 @@ def load_config():
238
268
  config[key] = value
239
269
  for key in REQUIRED_CONFIG:
240
270
  if key not in config:
271
+ if _pinned is not None:
272
+ die(f"The Human Backlog Config has no {key}. Set {key} in {_pinned}.")
241
273
  die(f"The Human Backlog Config has no {key}. Set {CONFIG_ENV[key]}, humanBacklog.{key} "
242
274
  f"in .devpunks/settings.json, or {key} in {CONFIG_FILE}.")
243
275
  if config["provider"] != "azure-devops":
@@ -250,6 +282,144 @@ def load_config():
250
282
  return config
251
283
 
252
284
 
285
+ def pin_config(path):
286
+ """Make `path` the only source of the Config and the mappings, as in a Client Skill Set without settings."""
287
+ global _pinned, _tables, _token
288
+ _pinned, _tables, _token = path, None, None
289
+
290
+
291
+ # ---------- client mappings ----------
292
+
293
+ MAPPING_SECTIONS = ("types", "fields", "ratings", "sprint")
294
+ REFERENCE_NAME = re.compile(r"^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)+$")
295
+
296
+
297
+ def mapping_problems(sections, paths):
298
+ """Problems of the mapping sections (types, fields, ratings, sprint); `paths` names each section in messages."""
299
+ found = []
300
+
301
+ def section(key, allowed):
302
+ value = sections.get(key, {})
303
+ if not isinstance(value, dict):
304
+ found.append(f"{paths[key]} must be a JSON object.")
305
+ return {}
306
+ found.extend(f"Unknown key {paths[key]}.{name}." for name in value if name not in allowed)
307
+ return {name: v for name, v in value.items() if name in allowed}
308
+
309
+ types = section("types", TYPE_NAMES)
310
+ for key, name in types.items():
311
+ if not isinstance(name, str) or not name.strip() or name != name.strip():
312
+ found.append(f"{paths['types']}.{key} must be a work item type name without outer spaces.")
313
+ names = [str(types.get(key, default)).casefold() for key, default in TYPE_NAMES.items()]
314
+ if len(set(names)) != len(names):
315
+ found.append(f"{paths['types']} gives two types the same name.")
316
+ fields = section("fields", FIELDS)
317
+ for key, ref in fields.items():
318
+ if FIELDS[key].startswith("System."):
319
+ found.append(f"{paths['fields']}.{key} is the System field {FIELDS[key]}; every process has it, so it is not mapped.")
320
+ elif not isinstance(ref, str) or not REFERENCE_NAME.match(ref):
321
+ found.append(f"{paths['fields']}.{key} must be a reference name such as Custom.{key}.")
322
+ # Friendly names that share a reference name (SuccessCriteria, AcceptanceCriteria) map together.
323
+ first = {}
324
+ for key, ref in fields.items():
325
+ other = first.setdefault(FIELDS[key], (key, ref))
326
+ if other[1] != ref:
327
+ found.append(f"{paths['fields']}.{other[0]} and {key} share {FIELDS[key]}; map them to the same field.")
328
+ # Reads translate the client's reference names back, so two fields never share one.
329
+ effective = {ref: ref for ref in FIELDS.values()}
330
+ effective.update({FIELDS[key]: ref for key, ref in fields.items() if isinstance(ref, str)})
331
+ owners = {}
332
+ for ref, client in effective.items():
333
+ if owners.setdefault(client, ref) != ref:
334
+ found.append(f"{paths['fields']} maps {owners[client]} and {ref} to the same field {client}.")
335
+ ratings = {**RATINGS, **section("ratings", RATINGS)}
336
+ if any(type(v) is not int for v in ratings.values()):
337
+ found.append(f"{paths['ratings']}.min and max must be integers.")
338
+ elif ratings["min"] >= ratings["max"]:
339
+ found.append(f"{paths['ratings']}.min must be lower than max.")
340
+ days = {**SPRINT, **section("sprint", SPRINT)}["lengthDays"]
341
+ if type(days) is not int or days % 7 or not 7 <= days <= 28:
342
+ found.append(f"{paths['sprint']}.lengthDays must be 7, 14, 21 or 28: complete working weeks.")
343
+ return found
344
+
345
+
346
+ def mapping_sections():
347
+ """The mapping sections in force, each from its first source, and the paths that name them."""
348
+ if _pinned is not None:
349
+ settings = {}
350
+ config_file = _pinned
351
+ else:
352
+ settings = nearest_settings().get("profile", {})
353
+ config_file = CONFIG_FILE
354
+ if not isinstance(settings, dict):
355
+ die("humanBacklog.profile in .devpunks/settings.json must be a JSON object.")
356
+ stored = json_object(config_file)
357
+ mappings = stored.get("mappings", {})
358
+ if not isinstance(mappings, dict):
359
+ die(f"{config_file}: mappings must be a JSON object.")
360
+ sections, paths = {}, {}
361
+ for key in MAPPING_SECTIONS:
362
+ if key in settings:
363
+ sections[key], paths[key] = settings[key], f"humanBacklog.profile.{key}"
364
+ else:
365
+ source = mappings if key in ("types", "fields") else stored
366
+ paths[key] = f"{config_file}: {'mappings.' if source is mappings else ''}{key}"
367
+ if key in source:
368
+ sections[key] = source[key]
369
+ return sections, paths
370
+
371
+
372
+ def build_tables(sections):
373
+ """The translation tables between canonical names and the client's names (identity without mappings)."""
374
+ types = {name: sections.get("types", {}).get(key, name) for key, name in TYPE_NAMES.items()}
375
+ fields = {FIELDS[key]: ref for key, ref in sections.get("fields", {}).items()}
376
+ ratings = {**RATINGS, **sections.get("ratings", {})}
377
+ return SimpleNamespace(
378
+ types=types, types_in={client: name for name, client in types.items()},
379
+ fields=fields, fields_in={client: ref for ref, client in fields.items()},
380
+ ratings=(ratings["min"], ratings["max"]),
381
+ sprint_days={**SPRINT, **sections.get("sprint", {})}["lengthDays"])
382
+
383
+
384
+ def tables():
385
+ """The client mappings in force, read and checked once."""
386
+ global _tables
387
+ if _tables is None:
388
+ sections, paths = mapping_sections()
389
+ problems = mapping_problems(sections, paths)
390
+ if problems:
391
+ die("The Human Backlog mappings are not valid:\n- " + "\n- ".join(problems))
392
+ _tables = build_tables(sections)
393
+ return _tables
394
+
395
+
396
+ def client_type(name):
397
+ return tables().types.get(name, name)
398
+
399
+
400
+ def canonical_type(name):
401
+ return tables().types_in.get(name, name)
402
+
403
+
404
+ def client_ref(ref):
405
+ return tables().fields.get(ref, ref)
406
+
407
+
408
+ def canonical_ref(ref):
409
+ return tables().fields_in.get(ref, ref)
410
+
411
+
412
+ def from_client(item):
413
+ """Canonical type and reference names in a work item read from Azure DevOps."""
414
+ fields = item.get("fields")
415
+ if isinstance(fields, dict):
416
+ fields = {canonical_ref(ref): value for ref, value in fields.items()}
417
+ if "System.WorkItemType" in fields:
418
+ fields["System.WorkItemType"] = canonical_type(fields["System.WorkItemType"])
419
+ item["fields"] = fields
420
+ return item
421
+
422
+
253
423
  def base():
254
424
  return f"https://dev.azure.com/{load_config()['org']}"
255
425
 
@@ -306,7 +476,9 @@ def api_url(wid):
306
476
 
307
477
 
308
478
  def norm_type(t):
309
- v = TYPES.get(str(t).strip().lower())
479
+ """The canonical type name of an alias, a canonical name or the client's type name."""
480
+ key = str(t).strip().lower()
481
+ v = TYPES.get(key) or next((name for name, client in tables().types.items() if client.lower() == key), None)
310
482
  if not v:
311
483
  die(f"Unknown work item type '{t}'. Use one of: br, epic, feature, pbi, bug.")
312
484
  return v
@@ -317,7 +489,8 @@ def article(word):
317
489
 
318
490
 
319
491
  def ref_of(name):
320
- return FIELDS.get(name, name)
492
+ """The canonical reference name of a friendly name, a canonical reference name or the client's one."""
493
+ return FIELDS.get(name) or canonical_ref(name)
321
494
 
322
495
 
323
496
  # ---------- text conversion ----------
@@ -423,7 +596,7 @@ def compact(item, relations=False, chars=None):
423
596
  res = {
424
597
  "id": item["id"],
425
598
  "rev": item.get("rev"),
426
- "type": f.get("System.WorkItemType"),
599
+ "type": client_type(f.get("System.WorkItemType")),
427
600
  "title": f.get("System.Title"),
428
601
  "state": f.get("System.State"),
429
602
  "url": wi_url(item["id"]),
@@ -474,9 +647,9 @@ def fetch(ids, fields=None, relations=False):
474
647
  if relations:
475
648
  url = f"{base()}/_apis/wit/workitems?ids={chunk}&$expand=relations&errorPolicy=omit&api-version=7.1"
476
649
  else:
477
- fl = ",".join(fields or READ_FIELDS)
650
+ fl = ",".join(client_ref(ref) for ref in fields or READ_FIELDS)
478
651
  url = f"{base()}/_apis/wit/workitems?ids={chunk}&fields={fl}&errorPolicy=omit&api-version=7.1"
479
- items += [x for x in call("GET", url).get("value", []) if x]
652
+ items += [from_client(x) for x in call("GET", url).get("value", []) if x]
480
653
  return items
481
654
 
482
655
 
@@ -488,8 +661,12 @@ def wiql(query):
488
661
 
489
662
 
490
663
  def type_clause(types):
491
- names = [norm_type(t) for t in types]
492
- return "[System.WorkItemType] IN (" + ", ".join(f"'{n}'" for n in names) + ")"
664
+ return "[System.WorkItemType] IN (" + ", ".join(wiql_type(norm_type(t)) for t in types) + ")"
665
+
666
+
667
+ def wiql_type(name):
668
+ """The client's name of a canonical type as a WIQL string literal."""
669
+ return "'" + client_type(name).replace("'", "''") + "'"
493
670
 
494
671
 
495
672
  def cmd_whoami(a):
@@ -552,7 +729,7 @@ def field_ops(fields, op="add"):
552
729
  ref = ref_of(name)
553
730
  if ref in HTML_FIELDS:
554
731
  value = md_to_html(value)
555
- ops.append({"op": op, "path": f"/fields/{ref}", "value": value})
732
+ ops.append({"op": op, "path": f"/fields/{client_ref(ref)}", "value": value})
556
733
  return ops
557
734
 
558
735
 
@@ -561,9 +738,10 @@ def check_parent(child_type, parent_id):
561
738
  if not parent:
562
739
  die(f"Parent #{parent_id} not found.")
563
740
  ptype = parent[0]["fields"]["System.WorkItemType"]
564
- if ptype not in ALLOWED_PARENT.get(child_type, set()):
565
- die(f"A {child_type} cannot be a child of {ptype} #{parent_id}. "
566
- f"Allowed parents: {sorted(ALLOWED_PARENT.get(child_type, set())) or 'none'}.")
741
+ allowed = ALLOWED_PARENT.get(child_type, set())
742
+ if ptype not in allowed:
743
+ die(f"A {client_type(child_type)} cannot be a child of {client_type(ptype)} #{parent_id}. "
744
+ f"Allowed parents: {sorted(client_type(t) for t in allowed) or 'none'}.")
567
745
 
568
746
 
569
747
  # ---------- business ratings ----------
@@ -572,13 +750,19 @@ def validate_scores(fields, required=False):
572
750
  values = {ref_of(k): v for k, v in fields.items()}
573
751
  if "Microsoft.VSTS.Common.BusinessValue" in values:
574
752
  die("Use BusinessValue (Custom.BusinessValueScore), not the legacy Business Value field.")
753
+ low, high = tables().ratings
575
754
  for ref in SCORE_FIELDS:
576
755
  if ref not in values:
577
756
  if required:
578
- die(f"{FRIENDLY[ref]} is required; ask the business for an integer from 1 to 5.")
757
+ die(f"{FRIENDLY[ref]} is required; ask the business for an integer from {low} to {high}.")
579
758
  continue
580
- if type(values[ref]) is not int or not 1 <= values[ref] <= 5:
581
- die(f"{FRIENDLY[ref]} must be an integer from 1 to 5; do not infer a score.")
759
+ if not is_rating(values[ref]):
760
+ die(f"{FRIENDLY[ref]} must be an integer from {low} to {high}; do not infer a score.")
761
+
762
+
763
+ def is_rating(value):
764
+ low, high = tables().ratings
765
+ return type(value) is int and low <= value <= high
582
766
 
583
767
 
584
768
  def related_ids(item):
@@ -737,7 +921,7 @@ def planning_context(team=None, iteration=None):
737
921
  path = selected_iteration["path"].replace("'", "''")
738
922
  ids = wiql("SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project "
739
923
  f"AND [System.IterationPath] = '{path}' "
740
- "AND [System.WorkItemType] IN ('Feature', 'Bug') ORDER BY [System.Id]")
924
+ f"AND [System.WorkItemType] IN ({wiql_type('Feature')}, {wiql_type('Bug')}) ORDER BY [System.Id]")
741
925
  workload = fetch(ids)
742
926
  if set(ids) != {i["id"] for i in workload}:
743
927
  die("Some iteration work items are inaccessible; do not plan from an incomplete workload.")
@@ -761,12 +945,15 @@ def inspect_sprint_plan(plan, context, today=None):
761
945
  if not working or not working <= set(weekdays):
762
946
  die("Team working days are missing or invalid; clarify the calendar before planning.")
763
947
  span = (finish - start).days + 1
764
- if not 7 < span <= 14:
765
- die("The selected iteration does not cover a two-week sprint.")
948
+ length = tables().sprint_days
949
+ weeks = length // 7
950
+ if not length - 7 < span <= length:
951
+ die(f"The selected iteration does not cover a {WEEK_WORDS[weeks]}-week sprint.")
766
952
  dates = [start + timedelta(days=i) for i in range(span)
767
953
  if weekdays[(start + timedelta(days=i)).weekday()] in working]
768
- if len(dates) != 2 * len(working):
769
- die("The selected iteration does not contain two complete configured working weeks.")
954
+ if len(dates) != weeks * len(working):
955
+ die(f"The selected iteration does not contain {WEEK_WORDS[weeks]} complete configured working "
956
+ f"week{'s' if weeks > 1 else ''}.")
770
957
  remaining = [day for day in dates if day >= today]
771
958
  if not remaining:
772
959
  die("Past iterations cannot be used for normal sprint planning.")
@@ -914,7 +1101,7 @@ def rating_result(feature, brs):
914
1101
  for br in brs:
915
1102
  for ref in SCORE_FIELDS:
916
1103
  value = br["fields"].get(ref)
917
- if type(value) is not int or not 1 <= value <= 5:
1104
+ if not is_rating(value):
918
1105
  missing.append({"br": br["id"], "field": FRIENDLY[ref], "value": value})
919
1106
  if missing:
920
1107
  return {**result, "status": "needs_input", "missing": missing}
@@ -989,7 +1176,7 @@ def cmd_sync_ratings(a):
989
1176
  ids = a.ids
990
1177
  if all_features:
991
1178
  ids = wiql("SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project "
992
- "AND [System.WorkItemType] = 'Feature' AND [System.State] IN ('New', 'Planned') "
1179
+ f"AND [System.WorkItemType] = {wiql_type('Feature')} AND [System.State] IN ('New', 'Planned') "
993
1180
  "ORDER BY [System.Id]")
994
1181
  report = []
995
1182
  failed = False
@@ -1015,11 +1202,11 @@ def create_item(wtype, fields, parent=None, dry_run=False):
1015
1202
  ops.append({"op": "add", "path": "/relations/-",
1016
1203
  "value": {"rel": LINK_TYPES["parent"], "url": api_url(parent)}})
1017
1204
  qs = "validateOnly=true&" if dry_run else ""
1018
- res = call("POST", f"{pbase()}/_apis/wit/workitems/${urllib.parse.quote(wtype)}?{qs}api-version=7.1",
1205
+ res = call("POST", f"{pbase()}/_apis/wit/workitems/${urllib.parse.quote(client_type(wtype))}?{qs}api-version=7.1",
1019
1206
  ops, content_type="application/json-patch+json")
1020
1207
  if dry_run:
1021
- return {"validated": True, "type": wtype, "title": fields.get("Title")}
1022
- return {"id": res["id"], "type": wtype, "title": res["fields"].get("System.Title"), "url": wi_url(res["id"])}
1208
+ return {"validated": True, "type": client_type(wtype), "title": fields.get("Title")}
1209
+ return {"id": res["id"], "type": client_type(wtype), "title": res["fields"].get("System.Title"), "url": wi_url(res["id"])}
1023
1210
 
1024
1211
 
1025
1212
  def cmd_create(a):
@@ -1462,35 +1649,44 @@ def cmd_apply(a):
1462
1649
  out(report)
1463
1650
 
1464
1651
 
1465
- # ---------- setup: doctor and eject ----------
1652
+ # ---------- setup: scan, doctor and eject ----------
1466
1653
 
1467
1654
  DOCTOR_CHECKS = ("config", "az", "project", "types", "fields", "states", "iterations", "create")
1468
1655
  DOCTOR_HELP = """\
1469
1656
  Read-only check of the Human Backlog Config and the Azure DevOps process. Writes nothing.
1470
1657
 
1471
- Checks, in order: config, az (signed in for the tenant), project (reachable), types (the five
1472
- work-item types), fields (every process field the skills use), states (exactly the eight Human
1473
- States on Business Request), iterations (the default team has iterations), create (Azure DevOps
1474
- validates, without saving, one create per type with only the fields the skills always set, so a
1475
- required field that intake may leave empty is a mismatch). A failing config,
1476
- az or project check skips the checks after it. JSON status is "ready" when every check passes (exit 0);
1477
- otherwise "blocked" with every mismatch (exit 1)."""
1658
+ Checks, in order: config (the Config and the mappings), az (signed in for the tenant), project
1659
+ (reachable), types (the five work-item types), fields (every process field the skills use), states
1660
+ (exactly the eight Human States on Business Request), iterations (the default team has iterations,
1661
+ and each current or future one lasts sprint.lengthDays), create (Azure DevOps validates, without
1662
+ saving, one create per type with only the fields the skills always set, so a required field that
1663
+ intake may leave empty is a mismatch). Types and fields carry the client's names from the mappings;
1664
+ doctor reads what `scan` reads. A failing config, az or project check skips the checks after it.
1665
+ JSON status is "ready" when every check passes (exit 0); otherwise "blocked" with every mismatch,
1666
+ each naming what the team must add or run (exit 1)."""
1667
+ SCAN_HELP = """\
1668
+ Read-only scan of the configured Azure DevOps project. Writes nothing. Prints, in the client's names,
1669
+ {"project": {"name", "id"}, "types": [{"name", "fields": [{"referenceName", "name", "type"}],
1670
+ "states": [{"name", "category"}]}], "iterations": [{"name", "path", "startDate", "finishDate"}]};
1671
+ the iterations are the default team's."""
1478
1672
 
1479
1673
  PACKAGE = "@collective-intelligence/backlog"
1480
- # The Human Backlog skills an Eject carries; in an HI repo other skills sit beside them.
1481
- SKILL_NAMES = ("analyze-business-request", "create-bug", "create-business-request", "human-backlog-ado",
1482
- "plan-sprint", "setup-human-backlog", "update-business-request")
1483
- SKILLS_DIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
1674
+ GENERATOR = "generate-human-backlog-skills"
1675
+ TEMPLATES_DIR = os.path.join(os.path.dirname(SCRIPT_DIR), "references", "templates")
1484
1676
  EJECT_NAME = "human-backlog-skills.zip"
1485
- # Where an ejected ado.py finds its config: CONFIG_FILE, beside the script.
1677
+ # Where the ado.py of a Client Skill Set finds its config: CONFIG_FILE, beside the script.
1486
1678
  CONFIG_ENTRY = "human-backlog-ado/scripts/config.json"
1487
- EJECT_SKIP_NAMES = {"tests", "__pycache__", ".DS_Store"}
1488
- # The team keeps the process reference (Q33); an earlier Eject's config is replaced by CONFIG_ENTRY.
1489
- EJECT_SKIP_FILES = {"setup-human-backlog/references/process.md", CONFIG_ENTRY}
1679
+ EJECT_SKIP_NAMES = {"__pycache__", ".DS_Store"}
1490
1680
  EJECT_HELP = """\
1491
- Write one zip of the installed Human Backlog skills, without tests, plus
1492
- human-backlog-ado/scripts/config.json (the resolved Human Backlog Config, where an ejected ado.py reads it)
1493
- and MANIFEST.json (package, skillTreeSha256, configSha256, date). Makes no network call; run doctor first."""
1681
+ Zip one Client Skill Set that `render.py render` wrote to DIR. Only the generator's copy of ado.py
1682
+ (generate-human-backlog-skills/scripts/ado.py) ejects; the copy in a Client Skill Set refuses.
1683
+
1684
+ Refuses, and writes no zip, unless DIR passes every `render.py check` rule, DIR was rendered from
1685
+ humanBacklog.profile in the nearest .devpunks/settings.json, and `doctor` is ready with DIR's
1686
+ human-backlog-ado/scripts/config.json as its only config. The zip holds every file of DIR and
1687
+ MANIFEST.json: package, templateTreeSha256 (the generator's references/templates/ tree),
1688
+ skillTreeSha256 (DIR without config.json), configSha256, profileSha256 and date. The same inputs
1689
+ on the same day give the same zip bytes."""
1494
1690
 
1495
1691
 
1496
1692
  def attempt(fn, *args):
@@ -1503,18 +1699,75 @@ def attempt(fn, *args):
1503
1699
  return None, json.loads(stderr.getvalue())["error"]
1504
1700
 
1505
1701
 
1702
+ def read_project():
1703
+ project = urllib.parse.quote(load_config()["project"], safe="")
1704
+ return call("GET", f"{base()}/_apis/projects/{project}?api-version=7.1")
1705
+
1706
+
1707
+ def read_types():
1708
+ """The project's work item types with their fields and states, in the client's names."""
1709
+ types = call("GET", f"{pbase()}/_apis/wit/workitemtypes?api-version=7.1").get("value", [])
1710
+ kinds = {f["referenceName"]: f.get("type")
1711
+ for f in call("GET", f"{pbase()}/_apis/wit/fields?api-version=7.1").get("value", [])}
1712
+ return [{"name": t["name"],
1713
+ "fields": [{"referenceName": f["referenceName"], "name": f.get("name"), "type": kinds.get(f["referenceName"])}
1714
+ for f in t.get("fields", [])],
1715
+ "states": [{"name": s["name"], "category": s.get("category")} for s in t.get("states", [])]}
1716
+ for t in types]
1717
+
1718
+
1719
+ def read_iterations():
1720
+ """The default team's iterations."""
1721
+ rows = call("GET", f"{pbase()}/_apis/work/teamsettings/iterations?api-version=7.1").get("value", [])
1722
+ return [{"name": row.get("name"), "path": row.get("path"),
1723
+ "startDate": (row.get("attributes") or {}).get("startDate"),
1724
+ "finishDate": (row.get("attributes") or {}).get("finishDate")} for row in rows]
1725
+
1726
+
1727
+ def cmd_scan(a):
1728
+ project = read_project()
1729
+ out({"project": {"name": project.get("name"), "id": project.get("id")},
1730
+ "types": read_types(), "iterations": read_iterations()})
1731
+
1732
+
1506
1733
  def process_mismatches(work_item_types):
1507
- """Compare the project's work-item types with PROCESS_FIELDS and the Human States."""
1734
+ """Compare the scanned types with PROCESS_FIELDS and the Human States, in the client's names."""
1508
1735
  types = {t["name"]: t for t in work_item_types}
1509
- found = {
1510
- "types": [f"Work item type {name} is missing." for name in PROCESS_FIELDS if name not in types],
1511
- "fields": [f"{name} has no field {ref}." for name, refs in PROCESS_FIELDS.items() if name in types
1512
- for ref in refs if ref not in {f["referenceName"] for f in types[name].get("fields", [])}],
1513
- }
1514
- if "Business Request" in types:
1515
- states = [s["name"] for s in types["Business Request"].get("states", [])]
1516
- found["states"] = ([f"Business Request has no Human State {s!r}." for s in BR_STATES if s not in states]
1517
- + [f"Business Request state {s!r} is not a Human State." for s in states if s not in BR_STATES])
1736
+ found = {"types": [], "fields": []}
1737
+ for name, refs in PROCESS_FIELDS.items():
1738
+ client = client_type(name)
1739
+ if client not in types:
1740
+ children = sorted(client_type(child) for child, parents in ALLOWED_PARENT.items() if name in parents)
1741
+ parent = f", the parent of {' and '.join(children)}" if children else ""
1742
+ found["types"].append(f"Work item type {client} is missing: add the work item type {client}{parent}.")
1743
+ continue
1744
+ known = {f["referenceName"] for f in types[client]["fields"]}
1745
+ found["fields"] += [f"{client} has no field {client_ref(ref)}: add the field {client_ref(ref)} to {client}."
1746
+ for ref in refs if client_ref(ref) not in known]
1747
+ br = client_type("Business Request")
1748
+ if br in types:
1749
+ states = [s["name"] for s in types[br]["states"]]
1750
+ found["states"] = ([f"{br} has no Human State {s!r}: add the state {s!r} to {br}." for s in BR_STATES if s not in states]
1751
+ + [f"{br} state {s!r} is not a Human State: remove it from {br}." for s in states if s not in BR_STATES])
1752
+ return found
1753
+
1754
+
1755
+ def iteration_mismatches(iterations, today=None):
1756
+ """The default team needs iterations, and each current or future one lasts sprint.lengthDays."""
1757
+ if not iterations:
1758
+ return ["The default team has no iterations: add its sprint iterations; plan-sprint needs them."]
1759
+ today = today or date.today()
1760
+ length = tables().sprint_days
1761
+ found = []
1762
+ for row in iterations:
1763
+ try:
1764
+ start, finish = (date.fromisoformat(row[k][:10]) for k in ("startDate", "finishDate"))
1765
+ except (KeyError, TypeError, ValueError):
1766
+ continue
1767
+ span = (finish - start).days + 1
1768
+ if finish >= today and not length - 7 < span <= length:
1769
+ found.append(f"Iteration {row['path']} spans {span} days ({start} to {finish}); sprints last "
1770
+ f"{length} days (sprint.lengthDays): change its dates, or the sprint length in the Client Profile.")
1518
1771
  return found
1519
1772
 
1520
1773
 
@@ -1533,75 +1786,84 @@ DOCTOR_CREATE = {
1533
1786
 
1534
1787
  def create_mismatches(work_item_types):
1535
1788
  """Validate one create per process type the project has; the types and fields checks report the rest."""
1789
+ low, high = tables().ratings
1790
+ rating = (low + high) // 2
1536
1791
  sample = {"Title": "Human Backlog doctor check", "Description": "Validated by ado.py doctor; not saved.",
1537
1792
  "AcceptanceCriteria": "- Validated", "Context": "doctor check",
1538
- "TargetDate": (date.today() + timedelta(days=30)).isoformat(), "BusinessValue": 3, "Urgency": 3,
1793
+ "TargetDate": (date.today() + timedelta(days=30)).isoformat(), "BusinessValue": rating, "Urgency": rating,
1539
1794
  "ReproSteps": "1. Validated by ado.py doctor"}
1540
1795
  types = {t["name"]: t for t in work_item_types}
1541
1796
  found = []
1542
1797
  for name, names in DOCTOR_CREATE.items():
1543
- if name not in types:
1798
+ client = client_type(name)
1799
+ if client not in types:
1544
1800
  continue
1545
- known = {f["referenceName"] for f in types[name].get("fields", [])}
1546
- ops = field_ops({k: sample[k] for k in names if ref_of(k) in known})
1547
- url = f"{pbase()}/_apis/wit/workitems/${urllib.parse.quote(name)}?validateOnly=true&api-version=7.1"
1801
+ known = {f["referenceName"] for f in types[client]["fields"]}
1802
+ ops = field_ops({k: sample[k] for k in names if client_ref(ref_of(k)) in known})
1803
+ url = f"{pbase()}/_apis/wit/workitems/${urllib.parse.quote(client)}?validateOnly=true&api-version=7.1"
1548
1804
  _, error = attempt(call, "POST", url, ops, "application/json-patch+json")
1549
1805
  if error:
1550
- found.append(f"Azure DevOps refuses to create {article(name)} {name}: {error}")
1806
+ found.append(f"Azure DevOps refuses to create {article(client)} {client}: {error}")
1551
1807
  return found
1552
1808
 
1553
1809
 
1554
- def read_project():
1555
- project = urllib.parse.quote(load_config()["project"], safe="")
1556
- return call("GET", f"{base()}/_apis/projects/{project}?api-version=7.1")
1557
-
1558
-
1559
1810
  def doctor_findings():
1560
- """Mismatches per doctor check; a check that could not run is absent."""
1811
+ """Mismatches per doctor check, from the reads of `scan`; a check that could not run is absent."""
1561
1812
  found = {}
1562
- for check, read in (("config", load_config), ("az", token), ("project", read_project)):
1813
+ for check, read in (("config", lambda: (load_config(), tables())), ("az", token), ("project", read_project)):
1563
1814
  _, error = attempt(read)
1564
1815
  found[check] = [error] if error else []
1565
1816
  if error:
1566
1817
  return found
1567
- types, error = attempt(call, "GET", f"{pbase()}/_apis/wit/workitemtypes?api-version=7.1")
1568
- found.update({"types": [error]} if error else process_mismatches(types.get("value", [])))
1569
- iterations, error = attempt(call, "GET", f"{pbase()}/_apis/work/teamsettings/iterations?api-version=7.1")
1570
- if error:
1571
- found["iterations"] = [error]
1572
- else:
1573
- found["iterations"] = [] if iterations.get("value") else ["The default team has no iterations; plan-sprint needs them."]
1574
- if types and "value" in types:
1575
- found["create"] = create_mismatches(types["value"])
1818
+ types, error = attempt(read_types)
1819
+ found.update({"types": [error]} if error else process_mismatches(types))
1820
+ iterations, error = attempt(read_iterations)
1821
+ found["iterations"] = [error] if error else iteration_mismatches(iterations)
1822
+ if types is not None:
1823
+ found["create"] = create_mismatches(types)
1576
1824
  return found
1577
1825
 
1578
1826
 
1579
- def cmd_doctor(a):
1827
+ def doctor_report():
1580
1828
  found = doctor_findings()
1581
1829
  checks = [{"check": c, "status": "skipped" if c not in found else "fail" if found[c] else "pass"}
1582
1830
  for c in DOCTOR_CHECKS]
1583
1831
  ready = all(check["status"] == "pass" for check in checks)
1584
- out({"status": "ready" if ready else "blocked", "checks": checks,
1585
- "mismatches": [f"{c}: {m}" for c in DOCTOR_CHECKS for m in found.get(c, [])]})
1586
- if not ready:
1832
+ return {"status": "ready" if ready else "blocked", "checks": checks,
1833
+ "mismatches": [f"{c}: {m}" for c in DOCTOR_CHECKS for m in found.get(c, [])]}
1834
+
1835
+
1836
+ def cmd_doctor(a):
1837
+ report = doctor_report()
1838
+ out(report)
1839
+ if report["status"] != "ready":
1587
1840
  raise SystemExit(1)
1588
1841
 
1589
1842
 
1590
- def skill_files():
1591
- """Sorted (zip path, bytes) of every file of the installed Human Backlog skills that an Eject carries."""
1843
+ def is_generator():
1844
+ """True for the generator's copy of this script; the copy in a Client Skill Set sits in human-backlog-ado."""
1845
+ return os.path.basename(SCRIPT_DIR) == "scripts" and os.path.basename(os.path.dirname(SCRIPT_DIR)) == GENERATOR
1846
+
1847
+
1848
+ def load_render():
1849
+ """render.py from beside this script, without bytecode: a __pycache__ under skills/ would ship."""
1850
+ sys.dont_write_bytecode = True
1851
+ spec = importlib.util.spec_from_file_location("human_backlog_render", os.path.join(SCRIPT_DIR, "render.py"))
1852
+ module = importlib.util.module_from_spec(spec)
1853
+ spec.loader.exec_module(module)
1854
+ return module
1855
+
1856
+
1857
+ def tree_files(root):
1858
+ """Sorted (path relative to root, bytes) of every file below root, without OS or Python leftovers."""
1592
1859
  files = []
1593
- for name in SKILL_NAMES:
1594
- folder = os.path.join(SKILLS_DIR, name)
1595
- if not os.path.isdir(folder):
1596
- die(f"The Human Backlog skill {name} is not installed in {SKILLS_DIR}. Reinstall the skills, then eject.")
1597
- for directory, dirs, names in os.walk(folder):
1598
- dirs[:] = [d for d in dirs if d not in EJECT_SKIP_NAMES]
1599
- for file_name in names:
1860
+ for directory, dirs, names in os.walk(root):
1861
+ dirs[:] = [d for d in dirs if d not in EJECT_SKIP_NAMES]
1862
+ for file_name in names:
1863
+ if file_name not in EJECT_SKIP_NAMES:
1600
1864
  path = os.path.join(directory, file_name)
1601
- rel = os.path.relpath(path, SKILLS_DIR).replace(os.sep, "/")
1602
- if file_name not in EJECT_SKIP_NAMES and rel not in EJECT_SKIP_FILES:
1603
- with open(path, "rb") as fh:
1604
- files.append((rel, fh.read()))
1865
+ with open(path, "rb") as fh:
1866
+ files.append((os.path.relpath(path, root).replace(os.sep, "/"), fh.read()))
1605
1867
  return sorted(files)
1606
1868
 
1607
1869
 
@@ -1614,14 +1876,49 @@ def tree_sha256(files):
1614
1876
 
1615
1877
 
1616
1878
  def cmd_eject(a):
1617
- config = load_config()
1618
- config_bytes = (json.dumps({k: config[k] for k in CONFIG_ENV if k in config}, indent=2) + "\n").encode()
1619
- files = skill_files()
1620
- manifest = {"package": PACKAGE, "skillTreeSha256": tree_sha256(files),
1621
- "configSha256": hashlib.sha256(config_bytes).hexdigest(), "date": date.today().isoformat()}
1622
- entries = sorted([*files, (CONFIG_ENTRY, config_bytes),
1623
- ("MANIFEST.json", (json.dumps(manifest, indent=2) + "\n").encode())])
1624
- path = os.path.join(a.out, EJECT_NAME) if os.path.isdir(a.out) else a.out
1879
+ if not is_generator():
1880
+ die("This ado.py belongs to a Client Skill Set and does not eject. Regenerate the Client Skill Set "
1881
+ f"with the {GENERATOR} skill, then eject it there.")
1882
+ source = os.path.abspath(a.source)
1883
+ path = os.path.abspath(os.path.join(a.out, EJECT_NAME) if os.path.isdir(a.out) else a.out)
1884
+ if os.path.commonpath([path, source]) == source:
1885
+ die(f"Write the Eject zip outside {source}.")
1886
+ render = load_render()
1887
+ problems = render.check_problems(source)
1888
+ if problems:
1889
+ die(f"Eject refused: {source} fails the render.py check:\n- " + "\n- ".join(problems))
1890
+ profile = nearest_settings().get("profile")
1891
+ if not isinstance(profile, dict):
1892
+ die("Eject refused: save the Client Profile as humanBacklog.profile in the nearest .devpunks/settings.json, "
1893
+ "render it, then eject.")
1894
+ problems = render.profile_problems(profile)
1895
+ if problems:
1896
+ die("Eject refused: the Client Profile is not valid:\n- " + "\n- ".join(problems))
1897
+ with open(os.path.join(source, render.RENDER_ENTRY), "rb") as fh:
1898
+ rendered = json.loads(fh.read())
1899
+ if rendered.get("profileSha256") != render.profile_sha256(profile):
1900
+ die(f"Eject refused: {source} was rendered from another Client Profile than humanBacklog.profile in "
1901
+ ".devpunks/settings.json. Render it again, then eject.")
1902
+ config_path = os.path.join(source, *CONFIG_ENTRY.split("/"))
1903
+ with open(config_path, "rb") as fh:
1904
+ config_bytes = fh.read()
1905
+ skills = sorted(d for d in os.listdir(source) if os.path.isdir(os.path.join(source, d)))
1906
+ if (skills != render.rendered_skills(profile["skills"])
1907
+ or config_bytes != render.config_bytes(json_object(config_path), profile)):
1908
+ die(f"Eject refused: {source} was not rendered from humanBacklog.profile in .devpunks/settings.json. "
1909
+ "Render it again, then eject.")
1910
+ pin_config(config_path)
1911
+ report = doctor_report()
1912
+ if report["status"] != "ready":
1913
+ die(f"Eject refused: doctor is blocked with {config_path}:\n- " + "\n- ".join(report["mismatches"]))
1914
+ files = [f for f in tree_files(source) if f[0] != render.RENDER_ENTRY]
1915
+ manifest = {"package": PACKAGE,
1916
+ "templateTreeSha256": rendered["templateTreeSha256"],
1917
+ "skillTreeSha256": tree_sha256([f for f in files if f[0] != CONFIG_ENTRY]),
1918
+ "configSha256": hashlib.sha256(config_bytes).hexdigest(),
1919
+ "profileSha256": rendered["profileSha256"],
1920
+ "date": date.today().isoformat()}
1921
+ entries = sorted([*files, ("MANIFEST.json", (json.dumps(manifest, indent=2) + "\n").encode())])
1625
1922
  try:
1626
1923
  with zipfile.ZipFile(path, "w") as zf:
1627
1924
  for name, data in entries:
@@ -1630,7 +1927,7 @@ def cmd_eject(a):
1630
1927
  zf.writestr(info, data, zipfile.ZIP_DEFLATED)
1631
1928
  except OSError as e:
1632
1929
  die(f"Cannot write the Eject zip {path}: {e}")
1633
- out({"zip": os.path.abspath(path), **manifest})
1930
+ out({"zip": path, **manifest})
1634
1931
 
1635
1932
 
1636
1933
  def main():
@@ -1750,10 +2047,15 @@ def main():
1750
2047
  s.add_argument("--dry-run", action="store_true")
1751
2048
  s.set_defaults(fn=cmd_apply)
1752
2049
 
2050
+ s = sub.add_parser("scan", description=SCAN_HELP, formatter_class=argparse.RawDescriptionHelpFormatter)
2051
+ s.set_defaults(fn=cmd_scan)
2052
+
1753
2053
  s = sub.add_parser("doctor", description=DOCTOR_HELP, formatter_class=argparse.RawDescriptionHelpFormatter)
1754
2054
  s.set_defaults(fn=cmd_doctor)
1755
2055
 
1756
2056
  s = sub.add_parser("eject", description=EJECT_HELP, formatter_class=argparse.RawDescriptionHelpFormatter)
2057
+ s.add_argument("--from", dest="source", required=True, metavar="DIR",
2058
+ help="the Client Skill Set that render.py render wrote")
1757
2059
  s.add_argument("--out", required=True, metavar="PATH",
1758
2060
  help=f"zip file to write, or an existing directory to write {EJECT_NAME} in")
1759
2061
  s.set_defaults(fn=cmd_eject)