xrefkit 0.4.1__tar.gz → 0.4.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.1
+Version: 0.4.2
 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.2}/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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrefkit"
-version = "0.4.1"
+version = "0.4.2"
 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.2}/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.2}/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.2}/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,53 @@ 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

{xrefkit-0.4.1 → xrefkit-0.4.2}/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.2}/xrefkit/__init__.py

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

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

@@ -497,6 +497,8 @@ 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(
         "--status",
         required=True,

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

@@ -179,6 +179,11 @@ 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>[^`]*)`: (?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 +830,19 @@ 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"),
+                    "text": match.group("text"),
+                }
+            )
+            continue
+        match = LEGACY_WORKITEM_RE.match(line)
         if not match:
             continue
         items.append(
@@ -832,14 +850,19 @@ 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",
                 "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, text: str) -> str:
+    return (
+        f"- [{_workitem_checkbox(status)}] {item_id} status=`{status}` role=`{role}` "
+        f"criterion=`{criterion}` reason=`{reason}`: {text}"
+    )
 
 
 def _overall_workitem_status(items: list[dict[str, str]]) -> str:
@@ -860,7 +883,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 +894,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 +911,18 @@ 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", " ")
     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):
@@ -904,12 +933,16 @@ def update_work_item(args) -> SkillRunResult:
     if existing:
         existing["status"] = status
         existing["role"] = role
+        if criterion:
+            existing["criterion"] = criterion
+        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})
+        items.append({"item_id": item_id, "status": status, "role": role, "criterion": criterion, "reason": reason, "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 +1469,13 @@ 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 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.2}/xrefkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.1
+Version: 0.4.2
 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