xrefkit 0.4.0__tar.gz → 0.4.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.0
+Version: 0.4.1
 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,18 @@ 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.
+
 ## Quick Start
 
 Install the package and initialize an instance:

{xrefkit-0.4.0 → xrefkit-0.4.1}/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,18 @@ 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.
+
 ## Quick Start
 
 Install the package and initialize an instance:

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

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

xrefkit-0.4.1/tests/test_instruction_workflow.py

@@ -0,0 +1,100 @@
+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",
+        "--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")

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

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

{xrefkit-0.4.0 → xrefkit-0.4.1}/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.1}/xrefkit/operations_cli.py

@@ -574,6 +574,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 +702,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.1}/xrefkit/skillrun.py

@@ -748,6 +748,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)
@@ -884,7 +896,7 @@ def update_work_item(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"])
 
     items = _parse_work_items(text)
@@ -1004,7 +1016,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 +1152,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 +1400,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")
@@ -1463,7 +1475,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 +1524,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 +1675,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 +2015,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 +2237,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.1}/xrefkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.0
+Version: 0.4.1
 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,18 @@ 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.
+
 ## Quick Start
 
 Install the package and initialize an instance:

{xrefkit-0.4.0 → xrefkit-0.4.1}/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