xrefkit 0.4.0__tar.gz → 0.4.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.0
+Version: 0.4.2
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -91,7 +91,7 @@ XRefKit makes AI work explicit by separating:
 
 - Skills: executable work units, each identified by a capability/tuning/responsibility triad and carrying its execution and check contract
 - Knowledge: source-backed domain facts and local rules loaded only when needed
-- Workflow protocol: the generic, deterministic per-Skill control (phases, verification, closure) that wraps every Skill run
+- Workflow protocol: the generic, deterministic control for Skill-backed and instruction-backed runs (phases, verification, closure)
 - Semantic routing: selecting the right Skill for a goal from user intent and the Skill catalog
 - Evidence: logs, judgments, concerns, and quality checks
 - XIDs: stable references that survive file movement and restructuring so AI can load targeted context without treating the whole repository as one prompt
@@ -109,6 +109,21 @@ and handoff records from collapsing into one opaque instruction block.
 4. Agents are routed semantically to the right Skill and load only the relevant context.
 5. Evidence and quality gates make incomplete or unsupported work visible.
 
+When an instruction has no matching Skill, open an instruction-backed workflow
+run explicitly. The run requires either user-supplied procedural completion
+conditions or an explicit opt-in to the repository defaults:
+
+```powershell
+xrefkit workflow run --task "Perform the requested procedure" `
+  --use-default-completion-conditions --json
+```
+
+`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
 
 Install the package and initialize an instance:

{xrefkit-0.4.0 → xrefkit-0.4.2}/README.md

@@ -52,7 +52,7 @@ XRefKit makes AI work explicit by separating:
 
 - Skills: executable work units, each identified by a capability/tuning/responsibility triad and carrying its execution and check contract
 - Knowledge: source-backed domain facts and local rules loaded only when needed
-- Workflow protocol: the generic, deterministic per-Skill control (phases, verification, closure) that wraps every Skill run
+- Workflow protocol: the generic, deterministic control for Skill-backed and instruction-backed runs (phases, verification, closure)
 - Semantic routing: selecting the right Skill for a goal from user intent and the Skill catalog
 - Evidence: logs, judgments, concerns, and quality checks
 - XIDs: stable references that survive file movement and restructuring so AI can load targeted context without treating the whole repository as one prompt
@@ -70,6 +70,21 @@ and handoff records from collapsing into one opaque instruction block.
 4. Agents are routed semantically to the right Skill and load only the relevant context.
 5. Evidence and quality gates make incomplete or unsupported work visible.
 
+When an instruction has no matching Skill, open an instruction-backed workflow
+run explicitly. The run requires either user-supplied procedural completion
+conditions or an explicit opt-in to the repository defaults:
+
+```powershell
+xrefkit workflow run --task "Perform the requested procedure" `
+  --use-default-completion-conditions --json
+```
+
+`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
 
 Install the package and initialize an instance:

{xrefkit-0.4.0 → xrefkit-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrefkit"
-version = "0.4.0"
+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.0 → 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.0 → 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.2/tests/test_instruction_workflow.py

@@ -0,0 +1,152 @@
+import contextlib
+import io
+import json
+from pathlib import Path
+
+from xrefkit.__main__ import main
+
+
+def _run(root: Path, *args: str) -> int:
+    with contextlib.redirect_stdout(io.StringIO()):
+        argv = list(args)
+        if argv[:2] == ["workflow", "run"]:
+            argv.extend(["--root", str(root)])
+        return main(argv)
+
+
+def test_instruction_workflow_requires_completion_conditions(tmp_path: Path) -> None:
+    out = tmp_path / "work" / "sessions" / "run.md"
+    assert _run(tmp_path, "workflow", "run", "--task", "Do work", "--out", str(out)) == 1
+    assert not out.exists()
+
+
+def test_instruction_workflow_uses_default_conditions_and_shared_protocol(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
+    text = out.read_text(encoding="utf-8")
+    assert "# Workflow Run Log" in text
+    assert "## Run Load Gate" in text
+    assert "- basis: `default`" in text
+    assert "- quality_policy: `human_acceptance`" in text
+
+    assert _run(
+        tmp_path,
+        "skill",
+        "workitem",
+        "--log",
+        str(out),
+        "--item",
+        "WI-001",
+        "--text",
+        "Perform the instruction",
+        "--completion-criterion",
+        "instruction result is recorded and verified",
+        "--status",
+        "done",
+        "--role",
+        "instruction:executor",
+    ) == 0
+    for artifact_id, kind, target, role in (
+        ("OUT-001", "output", "output.md", "instruction:executor"),
+        ("EVD-001", "evidence", "test command", "instruction:checker"),
+    ):
+        assert _run(
+            tmp_path,
+            "skill",
+            "artifact",
+            "--log",
+            str(out),
+            "--artifact",
+            artifact_id,
+            "--kind",
+            kind,
+            "--target",
+            target,
+            "--item",
+            "WI-001",
+            "--status",
+            "done",
+            "--role",
+            role,
+        ) == 0
+    assert _run(tmp_path, "skill", "phase", "--log", str(out), "--phase", "execution", "--status", "done", "--role", "instruction:executor") == 0
+    assert _run(tmp_path, "skill", "phase", "--log", str(out), "--phase", "handoff", "--status", "done", "--role", "instruction:handoff_owner") == 0
+    assert _run(tmp_path, "skill", "verify", "--log", str(out)) == 0
+
+    # Quality is a human decision and is recorded separately from progression.
+    assert _run(
+        tmp_path,
+        "skill",
+        "feedback",
+        "--log",
+        str(out),
+        "--kind",
+        "human",
+        "--status",
+        "accepted",
+        "--target",
+        "OUT-001",
+        "--note",
+        "human accepted output quality",
+    ) == 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.0 → 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.0 → xrefkit-0.4.2}/xrefkit/__init__.py

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

{xrefkit-0.4.0 → xrefkit-0.4.2}/xrefkit/cli.py

@@ -6,7 +6,7 @@ import sys
 from collections.abc import Sequence
 
 
-_OPERATIONS = {"xref", "ctx", "goal", "gate", "pack", "dashboard", "analysis", "skill"}
+_OPERATIONS = {"xref", "ctx", "goal", "gate", "pack", "dashboard", "analysis", "skill", "workflow"}
 _V2 = {"package", "show"}
 
 
@@ -18,6 +18,7 @@ def _print_help() -> None:
         "  xref       manage XIDs and references\n"
         "  ctx        build compact context packs\n"
         "  skill      discover, validate, run, verify, and close Skills\n"
+        "  workflow   run the generic protocol for instructions without a Skill\n"
         "  tools      list and run XID-backed client tools\n"
         "  catalog    list and maintain Knowledge and structure catalogs\n"
         "  pack       validate and build runtime/content packs\n"

{xrefkit-0.4.0 → 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,
@@ -574,6 +576,33 @@ def _build_parser() -> argparse.ArgumentParser:
     p_skill_verify.add_argument("--note", default=None, help="Optional check event note")
     p_skill_verify.add_argument("--json", action="store_true", help="Emit JSON")
 
+    workflow = subparsers.add_parser(
+        "workflow",
+        help="Run the generic workflow protocol for an instruction without a Skill",
+    )
+    workflow_sub = workflow.add_subparsers(dest="workflow_cmd", required=True)
+    p_workflow_run = workflow_sub.add_parser(
+        "run",
+        help="Open an instruction-backed workflow run with explicit or default completion conditions",
+    )
+    p_workflow_run.add_argument("--root", default=".", help="Project root (default: .)")
+    p_workflow_run.add_argument("--task", default=None, help="Instruction text")
+    p_workflow_run.add_argument("--task-file", default=None, help="Read instruction text from a UTF-8 file")
+    p_workflow_run.add_argument("--out", default=None, help="Write workflow run log to this path")
+    p_workflow_run.add_argument("--run-id", default=None, help="Caller-supplied UUID")
+    p_workflow_run.add_argument(
+        "--completion-condition",
+        action="append",
+        default=[],
+        help="Explicit procedural completion condition; may be repeated",
+    )
+    p_workflow_run.add_argument(
+        "--use-default-completion-conditions",
+        action="store_true",
+        help="Use the repository's procedural completion conditions when the instruction omits them",
+    )
+    p_workflow_run.add_argument("--json", action="store_true", help="Emit JSON")
+
     return parser
 
 
@@ -675,6 +704,12 @@ def main(argv: list[str] | None = None) -> int:
 
         return cmd_skill(args)
 
+    if args.command == "workflow":
+        if args.workflow_cmd == "run":
+            from xrefkit.skillrun import cmd_workflow_run
+
+            return cmd_workflow_run(args)
+
     if args.command == "pack":
         if args.pack_cmd == "list":
             from xrefkit.packmeta import cmd_pack_list

{xrefkit-0.4.0 → 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>.*)$"
 )
@@ -748,6 +753,18 @@ def _log_skill_id(text: str) -> str | None:
     return text[start:end]
 
 
+def _has_opened_run_gate(text: str) -> bool:
+    """Return whether this log was opened by a supported workflow runner.
+
+    Skill runs retain their historical gate text.  Instruction-backed workflow
+    runs use the generic gate text, but share the same progression machinery.
+    """
+    return (
+        "## Skill Load Gate\n\n- status: `opened_by_xrefkit_skill_run`" in text
+        or "## Run Load Gate\n\n- status: `opened_by_xrefkit_workflow_run`" in text
+    )
+
+
 def _log_model_tier(text: str) -> str | None:
     prefix = "- model_tier: `"
     start = text.find(prefix)
@@ -813,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(
@@ -820,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:
@@ -848,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:
@@ -859,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"
@@ -876,15 +911,21 @@ 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 "## Skill Load Gate\n\n- status: `opened_by_xrefkit_skill_run`" not in text:
+    if not _has_opened_run_gate(text):
         return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["skill run log is missing an opened Skill Load Gate"])
 
     items = _parse_work_items(text)
@@ -892,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)
@@ -1004,7 +1049,7 @@ def update_artifact(args) -> SkillRunResult:
         return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["missing --role"])
 
     text = log_path.read_text(encoding="utf-8")
-    if "## Skill Load Gate\n\n- status: `opened_by_xrefkit_skill_run`" not in text:
+    if not _has_opened_run_gate(text):
         return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["skill run log is missing an opened Skill Load Gate"])
 
     artifacts = _parse_artifacts(text)
@@ -1140,7 +1185,7 @@ def update_concern(args) -> SkillRunResult:
         return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["missing --role"])
 
     text = log_path.read_text(encoding="utf-8")
-    if "## Skill Load Gate\n\n- status: `opened_by_xrefkit_skill_run`" not in text:
+    if not _has_opened_run_gate(text):
         return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["skill run log is missing an opened Skill Load Gate"])
 
     concerns = _parse_concerns(text)
@@ -1388,7 +1433,7 @@ def _validate_handoff_sources(root: Path, source_logs: list[str]) -> tuple[list[
             errors.append(f"handoff source log not found: {source_path}")
             continue
         text = source_path.read_text(encoding="utf-8")
-        if "## Skill Load Gate\n\n- status: `opened_by_xrefkit_skill_run`" not in text:
+        if not _has_opened_run_gate(text):
             errors.append(f"handoff source log was not opened by xrefkit skill run: {source_path}")
             continue
         closure_status = _section_status(text, "Closure Gate")
@@ -1424,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']}"
@@ -1463,7 +1515,7 @@ def verify_progression_run(args) -> SkillRunResult:
         return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=None, errors=[f"log not found: {log_path}"])
 
     text = log_path.read_text(encoding="utf-8")
-    if "## Skill Load Gate\n\n- status: `opened_by_xrefkit_skill_run`" not in text:
+    if not _has_opened_run_gate(text):
         return SkillRunResult(
             ok=False,
             skill_id=None,
@@ -1512,7 +1564,7 @@ def close_skill_run(args) -> SkillRunResult:
         return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=None, errors=[f"log not found: {log_path}"])
 
     text = log_path.read_text(encoding="utf-8")
-    if "## Skill Load Gate\n\n- status: `opened_by_xrefkit_skill_run`" not in text:
+    if not _has_opened_run_gate(text):
         return SkillRunResult(
             ok=False,
             skill_id=None,
@@ -1663,7 +1715,7 @@ def _validate_observation_log(log_path: Path) -> tuple[str | None, SkillRunResul
             run_log=str(log_path),
             errors=[f"could not read skill run log: {exc}"],
         )
-    if "## Skill Load Gate\n\n- status: `opened_by_xrefkit_skill_run`" not in text:
+    if not _has_opened_run_gate(text):
         return None, SkillRunResult(
             ok=False,
             skill_id=None,
@@ -2003,7 +2055,7 @@ def update_token_usage(args) -> SkillRunResult:
         )
 
     text = log_path.read_text(encoding="utf-8")
-    if "## Skill Load Gate\n\n- status: `opened_by_xrefkit_skill_run`" not in text:
+    if not _has_opened_run_gate(text):
         return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=str(log_path), errors=["skill run log is missing an opened Skill Load Gate"])
 
     total_tokens = total_arg if total_arg is not None else (input_tokens or 0) + (output_tokens or 0)
@@ -2225,6 +2277,126 @@ def run_skill(args) -> SkillRunResult:
     )
 
 
+DEFAULT_INSTRUCTION_COMPLETION_CONDITIONS = (
+    "all concrete work items are done or escalated",
+    "an output artifact and an evidence artifact are recorded",
+    "unknowns and risks are resolved or escalated",
+    "execution, check, and handoff phases are complete or escalated",
+)
+
+
+def run_workflow_instruction(args) -> SkillRunResult:
+    """Open a generic workflow run for an instruction without a Skill.
+
+    This intentionally creates the same run-log shape consumed by the
+    progression commands.  It does not infer business quality; that remains a
+    human acceptance decision recorded separately with ``skill feedback``.
+    """
+    root = Path(args.root).resolve()
+    task, task_errors = _read_task(args)
+    if task_errors:
+        return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=None, errors=task_errors)
+
+    explicit = [str(value).strip() for value in getattr(args, "completion_condition", []) if str(value).strip()]
+    use_default = bool(getattr(args, "use_default_completion_conditions", False))
+    if not explicit and not use_default:
+        return SkillRunResult(
+            ok=False,
+            skill_id=None,
+            skill_doc=None,
+            run_log=None,
+            errors=[
+                "completion conditions are required; provide --completion-condition or explicitly opt into --use-default-completion-conditions"
+            ],
+        )
+    conditions = explicit or list(DEFAULT_INSTRUCTION_COMPLETION_CONDITIONS)
+    basis = "explicit" if explicit else "default"
+
+    raw_run_id = str(getattr(args, "run_id", None) or uuid.uuid4())
+    try:
+        run_id = str(uuid.UUID(raw_run_id))
+    except ValueError:
+        return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=None, errors=[f"run_id must be a UUID: {raw_run_id}"])
+
+    out_path = Path(args.out) if args.out else _default_log_path(root, "instruction")
+    if not out_path.is_absolute():
+        out_path = root / out_path
+    sessions_dir = root / "work" / "sessions"
+    if sessions_dir.exists():
+        for existing_log in sessions_dir.rglob("*.md"):
+            try:
+                existing_text = existing_log.read_text(encoding="utf-8")
+            except (OSError, UnicodeError):
+                continue
+            if _log_field(existing_text, "run_id") == run_id:
+                return SkillRunResult(ok=False, skill_id=None, skill_doc=None, run_log=None, errors=[f"run_id is already used by an existing workflow run: {existing_log}"])
+
+    assigned_roles = _assign_runtime_roles(skill_id="instruction", execution_mode="local_default", model_tier=None)
+    log = _render_log(
+        run_id=run_id,
+        skill_id="instruction",
+        maturity="not_applicable",
+        meta_path=Path("-") ,
+        skill_doc=Path("-"),
+        execution_mode="local_default",
+        guard_policy="required",
+        capability_layering="not_applicable",
+        workflow_protocol="required",
+        capability="instruction execution",
+        tuning="generic procedural completion",
+        role_responsibilities={"executor": "execute the user instruction"},
+        capability_refs=[],
+        assigned_roles=assigned_roles,
+        task=str(task),
+        os_contract=dict(REQUIRED_OS_CONTRACT),
+        handoff_sources=[],
+        model_tier=None,
+        domain_knowledge={"available": [], "selected": {}, "requirements": []},
+    )
+    log = log.replace("# Skill Run Log", "# Workflow Run Log", 1)
+    log = log.replace("## Skill Load Gate", "## Run Load Gate", 1)
+    log = log.replace("opened_by_xrefkit_skill_run", "opened_by_xrefkit_workflow_run", 1)
+    log = log.replace("- rule: do not open or execute the Skill procedure until this runtime envelope exists", "- rule: do not treat the instruction as procedurally complete until this workflow envelope closes", 1)
+    log = log.replace("## Skill Routing Trace", "## Instruction Routing Trace", 1)
+    condition_lines = [
+        "## Completion Conditions",
+        "",
+        f"- basis: `{basis}`",
+        "- quality_policy: `human_acceptance`",
+        "- rule: workflow verification checks procedural records; a human confirms output quality separately",
+    ] + [f"- condition: {condition.replace('`', "'")}" for condition in conditions]
+    marker = "\n## Startup Inputs\n"
+    log = log.replace(marker, "\n" + "\n".join(condition_lines) + "\n" + marker, 1)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    with _LogFileLock(out_path.with_name(f".{out_path.name}.lock")):
+        _atomic_write_text(out_path, log)
+    return SkillRunResult(
+        ok=True,
+        skill_id="instruction",
+        skill_doc=None,
+        run_log=str(out_path),
+        errors=[],
+        assigned_roles=assigned_roles,
+        run_id=run_id,
+    )
+
+
+def cmd_workflow_run(args) -> int:
+    result = run_workflow_instruction(args)
+    if args.json:
+        print(json.dumps(result.to_dict(), ensure_ascii=False, indent=2))
+    elif result.ok:
+        print(f"ok: {result.run_log}")
+        print(f"  run_id: {result.run_id}")
+        print("  run_type: instruction")
+        print("  next: add work items, record artifacts/evidence, verify, human-accept output, then close")
+    else:
+        print("fail: workflow run")
+        for error in result.errors:
+            print(f"  error: {error}")
+    return 0 if result.ok else 1
+
+
 def cmd_skill_run(args) -> int:
     result = run_skill(args)
     if args.json:

{xrefkit-0.4.0 → xrefkit-0.4.2}/xrefkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.0
+Version: 0.4.2
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -91,7 +91,7 @@ XRefKit makes AI work explicit by separating:
 
 - Skills: executable work units, each identified by a capability/tuning/responsibility triad and carrying its execution and check contract
 - Knowledge: source-backed domain facts and local rules loaded only when needed
-- Workflow protocol: the generic, deterministic per-Skill control (phases, verification, closure) that wraps every Skill run
+- Workflow protocol: the generic, deterministic control for Skill-backed and instruction-backed runs (phases, verification, closure)
 - Semantic routing: selecting the right Skill for a goal from user intent and the Skill catalog
 - Evidence: logs, judgments, concerns, and quality checks
 - XIDs: stable references that survive file movement and restructuring so AI can load targeted context without treating the whole repository as one prompt
@@ -109,6 +109,21 @@ and handoff records from collapsing into one opaque instruction block.
 4. Agents are routed semantically to the right Skill and load only the relevant context.
 5. Evidence and quality gates make incomplete or unsupported work visible.
 
+When an instruction has no matching Skill, open an instruction-backed workflow
+run explicitly. The run requires either user-supplied procedural completion
+conditions or an explicit opt-in to the repository defaults:
+
+```powershell
+xrefkit workflow run --task "Perform the requested procedure" `
+  --use-default-completion-conditions --json
+```
+
+`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
 
 Install the package and initialize an instance:

{xrefkit-0.4.0 → xrefkit-0.4.2}/xrefkit.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ tests/test_error_policy_locator.py
 tests/test_fm_multiroot.py
 tests/test_gate.py
 tests/test_goal_desired_state.py
+tests/test_instruction_workflow.py
 tests/test_knowledge_relations_validator.py
 tests/test_ownership.py
 tests/test_packmeta.py