xrefkit 0.4.1__tar.gz → 0.4.3__tar.gz

{xrefkit-0.4.1 → xrefkit-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.1
+Version: 0.4.3
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -120,6 +120,9 @@ xrefkit workflow run --task "Perform the requested procedure" `
 
 `verify` and `close` determine procedural completion only. Output quality is
 recorded separately after human acceptance with the existing feedback record.
+Each work item also requires its own completion criterion; if that criterion is
+not yet definable, record the item as unknown, blocked, or escalated with a
+reason instead of inventing a criterion.
 
 ## Quick Start
 

{xrefkit-0.4.1 → xrefkit-0.4.3}/README.md

@@ -81,6 +81,9 @@ xrefkit workflow run --task "Perform the requested procedure" `
 
 `verify` and `close` determine procedural completion only. Output quality is
 recorded separately after human acceptance with the existing feedback record.
+Each work item also requires its own completion criterion; if that criterion is
+not yet definable, record the item as unknown, blocked, or escalated with a
+reason instead of inventing a criterion.
 
 ## Quick Start
 

{xrefkit-0.4.1 → xrefkit-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrefkit"
-version = "0.4.1"
+version = "0.4.3"
 description = "Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit"
 readme = "README.md"
 requires-python = ">=3.11"

{xrefkit-0.4.1 → xrefkit-0.4.3}/tests/test_cli.py

@@ -82,6 +82,8 @@ class CliTests(unittest.TestCase):
                         "WI-001",
                         "--text",
                         "Implement controlled output",
+                        "--completion-criterion",
+                        "output is written and validated",
                         "--status",
                         "done",
                         "--role",
@@ -739,6 +741,8 @@ class CliTests(unittest.TestCase):
                         "WI-001",
                         "--text",
                         "Implement controlled output",
+                        "--completion-criterion",
+                        "output is written and validated",
                         "--status",
                         "in_progress",
                         "--role",
@@ -765,6 +769,8 @@ class CliTests(unittest.TestCase):
                             "WI-001",
                             "--status",
                             "done",
+                            "--completion-criterion",
+                            "output is written and validated",
                             "--role",
                             "sample_skill:executor",
                         ]
@@ -772,7 +778,7 @@ class CliTests(unittest.TestCase):
                 )
 
             text = out.read_text(encoding="utf-8")
-            self.assertIn("- [x] WI-001 status=`done` role=`sample_skill:executor`: Implement controlled output", text)
+            self.assertIn("WI-001 status=`done` role=`sample_skill:executor` criterion=`output is written and validated`", text)
 
     def test_main_skill_close_rejects_pending_concrete_work_item(self) -> None:
         with tempfile.TemporaryDirectory() as tmp:
@@ -808,9 +814,11 @@ class CliTests(unittest.TestCase):
                             str(out),
                             "--item",
                             "WI-001",
-                            "--text",
-                            "Implement controlled output",
-                            "--status",
+                        "--text",
+                        "Implement controlled output",
+                        "--completion-criterion",
+                        "output is written and validated",
+                        "--status",
                             "pending",
                             "--role",
                             "sample_skill:executor",
@@ -1065,9 +1073,11 @@ class CliTests(unittest.TestCase):
                             str(out),
                             "--item",
                             "WI-001",
-                            "--text",
-                            "Implement controlled output",
-                            "--status",
+                        "--text",
+                        "Implement controlled output",
+                        "--completion-criterion",
+                        "output is written and validated",
+                        "--status",
                             "done",
                             "--role",
                             "sample_skill:executor",
@@ -1375,9 +1385,11 @@ class CliTests(unittest.TestCase):
                             str(out),
                             "--item",
                             "WI-001",
-                            "--text",
-                            "Implement controlled output",
-                            "--status",
+                        "--text",
+                        "Implement controlled output",
+                        "--completion-criterion",
+                        "output is written and validated",
+                        "--status",
                             "done",
                             "--role",
                             "sample_skill:executor",

{xrefkit-0.4.1 → xrefkit-0.4.3}/tests/test_dashboard.py

@@ -118,6 +118,8 @@ class DashboardTests(unittest.TestCase):
                 "WI-001",
                 "--text",
                 "Implement controlled output",
+                "--completion-criterion",
+                "output is written and validated",
                 "--status",
                 "done",
                 "--role",

{xrefkit-0.4.1 → xrefkit-0.4.3}/tests/test_instruction_workflow.py

@@ -48,6 +48,8 @@ def test_instruction_workflow_uses_default_conditions_and_shared_protocol(tmp_pa
         "WI-001",
         "--text",
         "Perform the instruction",
+        "--completion-criterion",
+        "instruction result is recorded and verified",
         "--status",
         "done",
         "--role",
@@ -98,3 +100,73 @@ def test_instruction_workflow_uses_default_conditions_and_shared_protocol(tmp_pa
     ) == 0
     assert _run(tmp_path, "skill", "close", "--log", str(out)) == 0
     assert "## Completion Conditions" in out.read_text(encoding="utf-8")
+
+
+def test_workitem_requires_criterion_or_explicit_unknown_reason(tmp_path: Path) -> None:
+    out = tmp_path / "work" / "sessions" / "run.md"
+    assert _run(
+        tmp_path,
+        "workflow",
+        "run",
+        "--task",
+        "Do work",
+        "--out",
+        str(out),
+        "--use-default-completion-conditions",
+    ) == 0
+    assert _run(
+        tmp_path,
+        "skill",
+        "workitem",
+        "--log",
+        str(out),
+        "--item",
+        "WI-001",
+        "--text",
+        "Investigate missing requirement",
+        "--status",
+        "pending",
+        "--role",
+        "instruction:executor",
+    ) == 1
+    assert _run(
+        tmp_path,
+        "skill",
+        "workitem",
+        "--log",
+        str(out),
+        "--item",
+        "WI-001",
+        "--text",
+        "Investigate missing requirement",
+        "--status",
+        "unknown",
+        "--criterion-unknown-reason",
+        "The business owner has not defined the acceptance outcome",
+        "--role",
+        "instruction:executor",
+    ) == 0
+    text = out.read_text(encoding="utf-8")
+    assert "criterion=`` reason=`The business owner has not defined the acceptance outcome`" in text
+    assert _run(tmp_path, "skill", "phase", "--log", str(out), "--phase", "execution", "--status", "done", "--role", "instruction:executor") == 0
+    assert _run(tmp_path, "skill", "verify", "--log", str(out)) == 1
+
+
+def test_workitem_criterion_is_immutable_and_changes_use_supersedes(tmp_path: Path) -> None:
+    out = tmp_path / "work" / "sessions" / "run.md"
+    assert _run(tmp_path, "workflow", "run", "--task", "Do work", "--out", str(out), "--use-default-completion-conditions") == 0
+    base = [
+        "skill", "workitem", "--log", str(out), "--item", "WI-001",
+        "--text", "Implement original outcome", "--completion-criterion", "original outcome is verified",
+        "--status", "pending", "--role", "instruction:executor",
+    ]
+    assert _run(tmp_path, *base) == 0
+    assert _run(tmp_path, *base[:-6], "--completion-criterion", "different outcome is verified", "--status", "pending", "--role", "instruction:executor") == 1
+    assert _run(
+        tmp_path,
+        "skill", "workitem", "--log", str(out), "--item", "WI-002", "--supersedes", "WI-001",
+        "--text", "Implement revised outcome", "--completion-criterion", "revised outcome is verified",
+        "--status", "pending", "--role", "instruction:executor",
+    ) == 0
+    text = out.read_text(encoding="utf-8")
+    assert "WI-002" in text and "supersedes=`WI-001`" in text

{xrefkit-0.4.1 → xrefkit-0.4.3}/tests/test_skill_runtime_audit.py

@@ -84,6 +84,8 @@ class SkillRuntimeAuditTests(unittest.TestCase):
                         "WI-001",
                         "--text",
                         "Implement controlled output",
+                        "--completion-criterion",
+                        "output is written and validated",
                         "--status",
                         "done",
                         "--role",
@@ -322,6 +324,7 @@ class SkillRuntimeAuditTests(unittest.TestCase):
                     [
                         "skill", "workitem", "--log", str(out), "--item", "WI-001",
                         "--text", "Implement controlled output", "--status", "done",
+                        "--completion-criterion", "output is written and validated",
                         "--role", "sample_skill:executor",
                     ]
                 ),
@@ -393,7 +396,7 @@ class SkillRuntimeAuditTests(unittest.TestCase):
                 main(
                     [
                         "skill", "workitem", "--log", str(out), "--item", "WI-001",
-                        "--text", "do work", "--status", "done", "--role", "sample_skill:executor",
+                        "--text", "do work", "--status", "done", "--completion-criterion", "work is verified", "--role", "sample_skill:executor",
                     ]
                 ),
             )

{xrefkit-0.4.1 → xrefkit-0.4.3}/xrefkit/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.4.1"
+__version__ = "0.4.3"

{xrefkit-0.4.1 → xrefkit-0.4.3}/xrefkit/operations_cli.py

@@ -497,6 +497,9 @@ def _build_parser() -> argparse.ArgumentParser:
     p_skill_workitem.add_argument("--log", required=True, help="Skill run log to update")
     p_skill_workitem.add_argument("--item", required=True, help="Stable work item id, such as WI-001")
     p_skill_workitem.add_argument("--text", default=None, help="Work item text; required when adding a new item")
+    p_skill_workitem.add_argument("--completion-criterion", default=None, help="Observable procedural condition for this work item")
+    p_skill_workitem.add_argument("--criterion-unknown-reason", default=None, help="Why the completion criterion cannot yet be defined for unknown/blocked/escalated work")
+    p_skill_workitem.add_argument("--supersedes", default=None, help="Existing work item whose criterion is being replaced by this new item")
     p_skill_workitem.add_argument(
         "--status",
         required=True,

{xrefkit-0.4.1 → xrefkit-0.4.3}/xrefkit/skillrun.py

@@ -179,6 +179,17 @@ WORKLIST_ROWS = [
     ("Handoff", "Record outputs, unresolved items, next owner, and human decision points."),
 ]
 WORKITEM_RE = re.compile(
+    r"^- \[(?P<checkbox>[ x!])\] (?P<item_id>[A-Za-z0-9_.-]+) "
+    r"status=`(?P<status>[^`]+)` role=`(?P<role>[^`]+)` "
+    r"criterion=`(?P<criterion>[^`]*)` reason=`(?P<reason>[^`]*)` "
+    r"supersedes=`(?P<supersedes>[^`]*)`: (?P<text>.*)$"
+)
+WORKITEM_V2_RE = re.compile(
+    r"^- \[(?P<checkbox>[ x!])\] (?P<item_id>[A-Za-z0-9_.-]+) "
+    r"status=`(?P<status>[^`]+)` role=`(?P<role>[^`]+)` "
+    r"criterion=`(?P<criterion>[^`]*)` reason=`(?P<reason>[^`]*)`: (?P<text>.*)$"
+)
+LEGACY_WORKITEM_RE = re.compile(
     r"^- \[(?P<checkbox>[ x!])\] (?P<item_id>[A-Za-z0-9_.-]+) "
     r"status=`(?P<status>[^`]+)` role=`(?P<role>[^`]+)`: (?P<text>.*)$"
 )
@@ -825,6 +836,34 @@ def _parse_work_items(text: str) -> list[dict[str, str]]:
     items: list[dict[str, str]] = []
     for line in body.splitlines():
         match = WORKITEM_RE.match(line)
+        if match:
+            items.append(
+                {
+                    "item_id": match.group("item_id"),
+                    "status": match.group("status"),
+                    "role": match.group("role"),
+                    "criterion": match.group("criterion"),
+                    "reason": match.group("reason"),
+                    "supersedes": match.group("supersedes"),
+                    "text": match.group("text"),
+                }
+            )
+            continue
+        match = WORKITEM_V2_RE.match(line)
+        if match:
+            items.append(
+                {
+                    "item_id": match.group("item_id"),
+                    "status": match.group("status"),
+                    "role": match.group("role"),
+                    "criterion": match.group("criterion"),
+                    "reason": match.group("reason"),
+                    "supersedes": "",
+                    "text": match.group("text"),
+                }
+            )
+            continue
+        match = LEGACY_WORKITEM_RE.match(line)
         if not match:
             continue
         items.append(
@@ -832,14 +871,20 @@ def _parse_work_items(text: str) -> list[dict[str, str]]:
                 "item_id": match.group("item_id"),
                 "status": match.group("status"),
                 "role": match.group("role"),
+                "criterion": "",
+                "reason": "legacy work item has no recorded completion criterion",
+                "supersedes": "",
                 "text": match.group("text"),
             }
         )
     return items
 
 
-def _render_workitem_line(*, item_id: str, status: str, role: str, text: str) -> str:
-    return f"- [{_workitem_checkbox(status)}] {item_id} status=`{status}` role=`{role}`: {text}"
+def _render_workitem_line(*, item_id: str, status: str, role: str, criterion: str, reason: str, supersedes: str, text: str) -> str:
+    return (
+        f"- [{_workitem_checkbox(status)}] {item_id} status=`{status}` role=`{role}` "
+        f"criterion=`{criterion}` reason=`{reason}` supersedes=`{supersedes}`: {text}"
+    )
 
 
 def _overall_workitem_status(items: list[dict[str, str]]) -> str:
@@ -860,7 +905,7 @@ def _replace_concrete_work_items_section(text: str, items: list[dict[str, str]])
         insert_at = text.find("\n## Execution Role")
         if insert_at == -1:
             insert_at = len(text)
-        section = "\n\n## Concrete Work Items\n\n- status: `pending`\n- rule: task-specific work items must be added with `xrefkit skill workitem` and closed as `done` or `escalated`\n"
+        section = "\n\n## Concrete Work Items\n\n- status: `pending`\n- rule: each work item requires a completion criterion; use unknown, blocked, or escalated with a reason when the criterion cannot yet be defined\n"
         text = text[:insert_at] + section + text[insert_at:]
         body, start, end = _section_body(text, "Concrete Work Items")
         if body is None:
@@ -871,7 +916,7 @@ def _replace_concrete_work_items_section(text: str, items: list[dict[str, str]])
         "## Concrete Work Items",
         "",
         f"- status: `{status}`",
-        "- rule: task-specific work items must be added with `xrefkit skill workitem` and closed as `done` or `escalated`",
+        "- rule: each work item requires a completion criterion; use unknown, blocked, or escalated with a reason when the criterion cannot yet be defined",
     ]
     lines.extend(_render_workitem_line(**item) for item in items)
     new_body = "\n".join(lines) + "\n"
@@ -888,12 +933,19 @@ def update_work_item(args) -> SkillRunResult:
     status = str(args.status).lower()
     role = str(args.role).strip()
     item_text = str(args.text or "").strip()
+    criterion = str(getattr(args, "completion_criterion", None) or "").strip().replace("`", "'").replace("\n", " ")
+    reason = str(getattr(args, "criterion_unknown_reason", None) or "").strip().replace("`", "'").replace("\n", " ")
+    supersedes = str(getattr(args, "supersedes", None) or "").strip().replace("`", "'").replace("\n", " ")
     if not item_id:
         return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["missing --item"])
     if status not in VALID_WORKITEM_STATUSES:
         return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=[f"invalid work item status: {status}"])
     if not role:
         return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["missing --role"])
+    if not criterion and not reason and status in {"unknown", "blocked", "escalated"}:
+        return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["completion criterion is undefined; provide --criterion-unknown-reason for unknown, blocked, or escalated work items"])
+    if not criterion and status in {"pending", "in_progress", "done"}:
+        return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["--completion-criterion is required for pending, in_progress, and done work items"])
 
     text = log_path.read_text(encoding="utf-8")
     if not _has_opened_run_gate(text):
@@ -902,14 +954,31 @@ def update_work_item(args) -> SkillRunResult:
     items = _parse_work_items(text)
     existing = next((item for item in items if item["item_id"] == item_id), None)
     if existing:
+        existing_criterion = existing.get("criterion", "")
+        if criterion and criterion != existing_criterion:
+            return SkillRunResult(
+                ok=False,
+                skill_id=None,
+                skill_doc=None,
+                run_log=str(log_path),
+                errors=[
+                    f"completion criterion for {item_id} is immutable; create a new work item with --supersedes {item_id}"
+                ],
+            )
+        if supersedes:
+            return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=[f"--supersedes is only valid when creating a new work item, not updating {item_id}"])
         existing["status"] = status
         existing["role"] = role
+        if reason:
+            existing["reason"] = reason
         if item_text:
             existing["text"] = item_text
     else:
         if not item_text:
             return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["new work item requires --text"])
-        items.append({"item_id": item_id, "status": status, "role": role, "text": item_text})
+        if supersedes and not any(item["item_id"] == supersedes for item in items):
+            return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=[f"superseded work item not found: {supersedes}"])
+        items.append({"item_id": item_id, "status": status, "role": role, "criterion": criterion, "reason": reason, "supersedes": supersedes, "text": item_text})
 
     text = _replace_concrete_work_items_section(text, items)
     text = _append_phase_event(text, phase=f"workitem:{item_id}", status=status, role=role, note=item_text or None)
@@ -1436,6 +1505,17 @@ def _progression_record_errors(
     if not work_items:
         errors.append("at least one concrete work item is required before closure")
     for item in work_items:
+        if item.get("supersedes") and not any(previous["item_id"] == item["supersedes"] for previous in work_items):
+            errors.append(f"work item {item['item_id']} supersedes missing work item {item['supersedes']}")
+        if item.get("supersedes") == item["item_id"]:
+            errors.append(f"work item {item['item_id']} cannot supersede itself")
+        if not item.get("criterion"):
+            if item["status"] in {"unknown", "blocked", "escalated"} and item.get("reason"):
+                pass
+            else:
+                errors.append(f"work item {item['item_id']} must record a completion criterion or a reason why it cannot be defined")
+        if item.get("criterion") == "unknown" and item["status"] in {"pending", "in_progress", "done"}:
+            errors.append(f"work item {item['item_id']} cannot use unknown as its completion criterion while executable")
         if item["status"] not in ACCEPTED_CLOSE_STATUSES:
             errors.append(
                 f"work item {item['item_id']} must be done or escalated before closure; current={item['status']}"

{xrefkit-0.4.1 → xrefkit-0.4.3}/xrefkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.1
+Version: 0.4.3
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -120,6 +120,9 @@ xrefkit workflow run --task "Perform the requested procedure" `
 
 `verify` and `close` determine procedural completion only. Output quality is
 recorded separately after human acceptance with the existing feedback record.
+Each work item also requires its own completion criterion; if that criterion is
+not yet definable, record the item as unknown, blocked, or escalated with a
+reason instead of inventing a criterion.
 
 ## Quick Start