xrefkit 0.4.7__tar.gz → 0.4.8__tar.gz

{xrefkit-0.4.7 → xrefkit-0.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.7
+Version: 0.4.8
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -178,6 +178,22 @@ If the `xrefkit` command is not available on `PATH`, use the module form:
 python -m xrefkit --help
 ```
 
+### Markdown WBS validation and rollups
+
+Keep one task per row in a Markdown table, then validate and regenerate the
+feature, phase, and feature-by-phase views without editing the source table:
+
+```powershell
+python -m xrefkit wbs validate samples/wbs.md
+python -m xrefkit wbs rollup samples/wbs.md
+python -m xrefkit wbs csv samples/wbs.md .tmp/wbs.csv
+```
+
+The validator rejects missing or extra cells, duplicate IDs, non-numeric or
+negative effort, and statuses outside `todo`, `doing`, and `done`. CSV output
+uses UTF-8 with BOM for Excel compatibility; the Markdown WBS remains the
+source of truth.
+
 To use the integrated MCP server, install the optional MCP dependencies:
 
 ```powershell

{xrefkit-0.4.7 → xrefkit-0.4.8}/README.md

@@ -139,6 +139,22 @@ If the `xrefkit` command is not available on `PATH`, use the module form:
 python -m xrefkit --help
 ```
 
+### Markdown WBS validation and rollups
+
+Keep one task per row in a Markdown table, then validate and regenerate the
+feature, phase, and feature-by-phase views without editing the source table:
+
+```powershell
+python -m xrefkit wbs validate samples/wbs.md
+python -m xrefkit wbs rollup samples/wbs.md
+python -m xrefkit wbs csv samples/wbs.md .tmp/wbs.csv
+```
+
+The validator rejects missing or extra cells, duplicate IDs, non-numeric or
+negative effort, and statuses outside `todo`, `doing`, and `done`. CSV output
+uses UTF-8 with BOM for Excel compatibility; the Markdown WBS remains the
+source of truth.
+
 To use the integrated MCP server, install the optional MCP dependencies:
 
 ```powershell

{xrefkit-0.4.7 → xrefkit-0.4.8}/pyproject.toml

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

xrefkit-0.4.8/tests/test_brownfield_file_editing_protocol.py

@@ -0,0 +1,55 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_brownfield_file_editing_protocol_is_in_canonical_and_packaged_skill() -> None:
+    canonical = (ROOT / "skills" / "brownfield-workflow" / "SKILL.md").read_text(encoding="utf-8")
+    packaged = (
+        ROOT / "packages" / "xrefkit-skills-brownfield" / "src" / "xrefkit_skills_brownfield"
+        / "skills" / "brownfield_workflow" / "entry.md"
+    ).read_text(encoding="utf-8")
+
+    for keyword in (
+        "encoding",
+        "BOM",
+        "newline",
+        "Unicode",
+        "strict",
+        "after_bytes",
+        "mojibake",
+        "concurrency",
+        "revision token",
+        "compare-and-swap",
+        "abort",
+        "atomically",
+        "specification",
+        "semantic",
+        "authoritative",
+        "hypothesis",
+        "semantic_alignment",
+        "Historical conflict investigation",
+        "bounded",
+        "Git",
+        "uncommitted",
+        "newest",
+        "Uncommitted-file policy",
+        "pre_existing_human_or_unknown",
+        "ai_owned_current_work",
+        "mixed_or_overlapping",
+        "untracked",
+        "stash",
+        "New-file extension conformity",
+        "peer",
+        "companion files",
+        "extension-specific",
+        "cluster",
+        "majority",
+        "same directory",
+        "confidence",
+        "weak margin",
+        "repository-wide fallback",
+    ):
+        assert keyword in canonical
+        assert keyword in packaged

xrefkit-0.4.8/tests/test_human_evaluation.py

@@ -0,0 +1,93 @@
+import contextlib
+import io
+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 _closed_run(tmp_path: Path) -> Path:
+    log = tmp_path / "work" / "sessions" / "preceding.md"
+    assert _run(
+        tmp_path,
+        "workflow", "run", "--task", "Produce a bounded output", "--out", str(log),
+        "--use-default-completion-conditions",
+    ) == 0
+    assert _run(
+        tmp_path, "skill", "workitem", "--log", str(log), "--item", "WI-001",
+        "--text", "Produce output", "--completion-criterion", "output is recorded",
+        "--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 passed", "instruction:checker"),
+    ):
+        assert _run(
+            tmp_path, "skill", "artifact", "--log", str(log), "--artifact", artifact_id,
+            "--kind", kind, "--target", target, "--item", "WI-001", "--status", "done",
+            "--role", role,
+        ) == 0
+    assert _run(tmp_path, "skill", "phase", "--log", str(log), "--phase", "execution", "--status", "done", "--role", "instruction:executor") == 0
+    assert _run(tmp_path, "skill", "phase", "--log", str(log), "--phase", "handoff", "--status", "done", "--role", "instruction:handoff_owner") == 0
+    assert _run(tmp_path, "skill", "verify", "--log", str(log)) == 0
+    assert _run(tmp_path, "skill", "close", "--log", str(log)) == 0
+    return log
+
+
+def test_human_evaluation_is_optional_and_scoped(tmp_path: Path) -> None:
+    log = _closed_run(tmp_path)
+    assert _run(
+        tmp_path, "skill", "evaluate", "--log", str(log),
+        "--decision", "accepted_with_conditions",
+        "--classification", "correction",
+        "--next-handling", "repair_previous_run",
+        "--purpose-fit", "The overall purpose remains valid",
+        "--verified", "WI-001 and EVD-001",
+        "--uncertainty", "target B source is not snapshotted",
+        "--scope-finding", "WI-A|accepted|Target A is acceptable",
+        "--scope-finding", "WI-B|correction|Target B needs repair",
+        "--scope-link", "WI-B|EVD-B",
+        "--context-ref", "criteria:v1",
+        "--comparability", "gap",
+        "--comparability-gap", "target B source snapshot is unavailable",
+        "--evaluated-at", "2026-08-19T01:02:03Z",
+        "--proposed-classification", "continuation",
+    ) == 0
+    text = log.read_text(encoding="utf-8")
+    assert '"event":"human.evaluation"' in text
+    assert '"classification":"correction"' in text
+    assert '"preceding_run_id"' in text
+    assert '"target":"WI-B"' in text
+    assert '"linked_targets":["EVD-B"]' in text
+    assert '"comparability":"gap"' in text
+    assert '"classification_source":"human_confirmed"' in text
+
+
+def test_human_evaluation_does_not_accept_an_open_run(tmp_path: Path) -> None:
+    log = tmp_path / "work" / "sessions" / "open.md"
+    assert _run(
+        tmp_path, "workflow", "run", "--task", "Open work", "--out", str(log),
+        "--use-default-completion-conditions",
+    ) == 0
+    assert _run(
+        tmp_path, "skill", "evaluate", "--log", str(log), "--decision", "accepted",
+        "--classification", "continuation", "--next-handling", "continue_next_step",
+        "--purpose-fit", "still fits", "--verified", "none", "--uncertainty", "none",
+    ) == 1
+
+
+def test_comparability_gap_requires_a_reason(tmp_path: Path) -> None:
+    log = _closed_run(tmp_path)
+    assert _run(
+        tmp_path, "skill", "evaluate", "--log", str(log), "--decision", "accepted",
+        "--classification", "continuation", "--next-handling", "continue_next_step",
+        "--purpose-fit", "still fits", "--verified", "none", "--uncertainty", "none",
+        "--comparability", "gap",
+    ) == 1

{xrefkit-0.4.7 → xrefkit-0.4.8}/tests/test_skills_sync.py

@@ -21,12 +21,12 @@ def _zip_bytes() -> bytes:
 
 def test_sync_bundle_extracts_skill_and_knowledge(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
     release = {
-        "tag_name": "skills-2026.07.30",
+        "tag_name": "xrefkit-skills-demo-v1.0.0",
         "assets": [{"name": "xrefkit-skills-demo-1.0.0.zip", "browser_download_url": "https://example.test/demo.zip"}],
     }
 
-    def fake_json(_url: str) -> dict:
-        return release
+    def fake_json(_url: str) -> object:
+        return [release]
 
     def fake_download(_asset: dict) -> tuple[str, bytes]:
         return "xrefkit-skills-demo-1.0.0.zip", _zip_bytes()
@@ -36,7 +36,7 @@ def test_sync_bundle_extracts_skill_and_knowledge(monkeypatch: pytest.MonkeyPatc
 
     result = sync_bundle(repo=tmp_path, source_repository="owner/repo", bundle="demo")
 
-    assert result.release == "skills-2026.07.30"
+    assert result.release == "xrefkit-skills-demo-v1.0.0"
     assert (tmp_path / "skills/demo/SKILL.md").is_file()
     assert (tmp_path / "knowledge/demo.md").is_file()
     state = json.loads((tmp_path / ".xrefkit/skill-sync/demo.json").read_text(encoding="utf-8"))
@@ -44,8 +44,8 @@ def test_sync_bundle_extracts_skill_and_knowledge(monkeypatch: pytest.MonkeyPatc
 
 
 def test_sync_bundle_refuses_unmanaged_collision(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
-    release = {"tag_name": "v1", "assets": [{"name": "xrefkit-skills-demo-1.0.0.zip", "browser_download_url": "https://example.test/demo.zip"}]}
-    monkeypatch.setattr("xrefkit.skills_sync._github_json", lambda _url: release)
+    release = {"tag_name": "xrefkit-skills-demo-v1.0.0", "assets": [{"name": "xrefkit-skills-demo-1.0.0.zip", "browser_download_url": "https://example.test/demo.zip"}]}
+    monkeypatch.setattr("xrefkit.skills_sync._github_json", lambda _url: [release])
     monkeypatch.setattr("xrefkit.skills_sync._download_asset", lambda _asset: ("demo.zip", _zip_bytes()))
     target = tmp_path / "skills/demo/SKILL.md"
     target.parent.mkdir(parents=True)

{xrefkit-0.4.7 → xrefkit-0.4.8}/xrefkit/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.4.7"
+__version__ = "0.4.8"

{xrefkit-0.4.7 → xrefkit-0.4.8}/xrefkit/cli.py

@@ -16,6 +16,7 @@ def _print_help() -> None:
         "commands:\n"
         "  init       initialize or validate an XRefKit instance\n"
         "  xref       manage XIDs and references\n"
+        "  wbs        validate and summarize a Markdown WBS\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"
@@ -60,6 +61,10 @@ def main(argv: Sequence[str] | None = None) -> int:
         from .tools import main as tools_main
 
         return tools_main(args[1:])
+    if command == "wbs":
+        from .wbs import main as wbs_main
+
+        return wbs_main(args[1:])
     if command == "catalog":
         from .catalog_cli import main as catalog_main
 

{xrefkit-0.4.7 → xrefkit-0.4.8}/xrefkit/models/__init__.py

@@ -11,6 +11,7 @@ from .common import (
     XidRef,
 )
 from .effective_bundle import BundleReferences, DomainKnowledgeCatalogEntry, EffectiveSkillBundle, LoadedTexts
+from .human_evaluation import HumanEvaluation, ScopedEvaluation
 from .local_manifest import IncludeRef, LocalDomainSkill, LocalManifest
 from .package_manifest import PackageManifest
 from .run_log import RunLogAggregate, RunLogEvent
@@ -38,4 +39,6 @@ __all__ = [
     "XidLoadedRef",
     "XidRef",
     "BundleReferences",
+    "HumanEvaluation",
+    "ScopedEvaluation",
 ]

xrefkit-0.4.8/xrefkit/models/human_evaluation.py

@@ -0,0 +1,93 @@
+"""Schema for optional human evaluation at a completed-run boundary."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+
+EvaluationDecision = Literal[
+    "accepted",
+    "accepted_with_conditions",
+    "correction",
+    "rejected_or_returned_to_human",
+    "needs_clarification",
+]
+RelationshipClassification = Literal[
+    "continuation",
+    "correction",
+    "scope_change",
+    "new_work",
+    "needs_clarification",
+]
+NextHandling = Literal["continue_next_step", "repair_previous_run", "human_takeover"]
+Comparability = Literal["comparable", "gap", "not_assessed"]
+
+
+class ScopedEvaluation(BaseModel):
+    """Optional item/artifact-level finding within one preceding run."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    target: str = Field(min_length=1)
+    decision: EvaluationDecision
+    note: str = Field(min_length=1)
+    linked_targets: list[str] = Field(default_factory=list)
+
+    @field_validator("target", "note", mode="before")
+    @classmethod
+    def _strip_scalar(cls, value: object) -> object:
+        return str(value).strip()
+
+    @field_validator("linked_targets", mode="before")
+    @classmethod
+    def _strip_links(cls, value: object) -> object:
+        if value is None:
+            return []
+        return [str(item).strip() for item in value if str(item).strip()]
+
+
+class HumanEvaluation(BaseModel):
+    """Human-confirmed disposition; private model reasoning is out of scope."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    preceding_run_id: str = Field(min_length=1)
+    decision: EvaluationDecision
+    classification: RelationshipClassification
+    next_handling: NextHandling
+    purpose_fit: str = Field(min_length=1)
+    verified_basis: list[str] = Field(min_length=1)
+    remaining_uncertainty: list[str] = Field(min_length=1)
+    carry_forward: list[str] = Field(default_factory=list)
+    linked_targets: list[str] = Field(default_factory=list)
+    scoped_findings: list[ScopedEvaluation] = Field(default_factory=list)
+    proposed_classification: RelationshipClassification | None = None
+    classification_source: Literal["human_confirmed"] = "human_confirmed"
+    reviewer: str | None = None
+    evaluated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    context_refs: list[str] = Field(default_factory=list)
+    comparability: Comparability = "not_assessed"
+    comparability_gaps: list[str] = Field(default_factory=list)
+
+    @model_validator(mode="after")
+    def _require_comparability_reason(self) -> "HumanEvaluation":
+        if self.comparability == "gap" and not self.comparability_gaps:
+            raise ValueError("comparability=gap requires at least one comparability gap")
+        return self
+
+    @field_validator("preceding_run_id", "purpose_fit", "reviewer", mode="before")
+    @classmethod
+    def _strip_scalar(cls, value: object) -> object:
+        return None if value is None else str(value).strip()
+
+    @field_validator(
+        "verified_basis", "remaining_uncertainty", "carry_forward", "linked_targets", mode="before"
+    )
+    @classmethod
+    def _strip_list(cls, value: object) -> object:
+        if value is None:
+            return []
+        return [str(item).strip() for item in value if str(item).strip()]

{xrefkit-0.4.7 → xrefkit-0.4.8}/xrefkit/operations_cli.py

@@ -471,6 +471,38 @@ def _build_parser() -> argparse.ArgumentParser:
     p_skill_feedback.add_argument("--note", required=True, help="Observed feedback or outcome")
     p_skill_feedback.add_argument("--json", action="store_true", help="Emit JSON")
 
+    p_skill_evaluate = skill_sub.add_parser(
+        "evaluate",
+        help="Optionally record a human-confirmed evaluation and next-request relationship for a closed run",
+    )
+    p_skill_evaluate.add_argument("--log", required=True, help="Completed preceding run log to update")
+    p_skill_evaluate.add_argument("--decision", required=True, choices=[
+        "accepted", "accepted_with_conditions", "correction",
+        "rejected_or_returned_to_human", "needs_clarification",
+    ])
+    p_skill_evaluate.add_argument("--classification", required=True, choices=[
+        "continuation", "correction", "scope_change", "new_work", "needs_clarification",
+    ], help="Human-confirmed relationship of the subsequent request to the preceding run")
+    p_skill_evaluate.add_argument("--next-handling", required=True, choices=[
+        "continue_next_step", "repair_previous_run", "human_takeover",
+    ])
+    p_skill_evaluate.add_argument("--purpose-fit", required=True, help="Human-stated fit to the preceding purpose/intent")
+    p_skill_evaluate.add_argument("--verified", action="append", default=[], help="Verified artifact/check basis; repeatable, or use 'none'")
+    p_skill_evaluate.add_argument("--uncertainty", action="append", default=[], help="Remaining uncertainty/risk; repeatable, or use 'none'")
+    p_skill_evaluate.add_argument("--carry-forward", action="append", default=[], help="Constraint or added context for the next run; repeatable")
+    p_skill_evaluate.add_argument("--link", action="append", default=[], help="Preceding artifact, check, or evidence link; repeatable")
+    p_skill_evaluate.add_argument("--scope-finding", action="append", default=[], help="Scoped finding as TARGET|DECISION|NOTE; repeatable")
+    p_skill_evaluate.add_argument("--scope-link", action="append", default=[], help="Scoped evidence link as TARGET|LINK; repeatable")
+    p_skill_evaluate.add_argument("--proposed-classification", choices=[
+        "continuation", "correction", "scope_change", "new_work", "needs_clarification",
+    ], help="Optional AI proposal; --classification remains human-confirmed")
+    p_skill_evaluate.add_argument("--reviewer", default=None, help="Optional human reviewer identifier")
+    p_skill_evaluate.add_argument("--evaluated-at", default=None, help="Optional ISO-8601 evaluation timestamp")
+    p_skill_evaluate.add_argument("--context-ref", action="append", default=[], help="Versioned/declarative prior-run context reference; repeatable")
+    p_skill_evaluate.add_argument("--comparability", choices=["comparable", "gap", "not_assessed"], default="not_assessed")
+    p_skill_evaluate.add_argument("--comparability-gap", action="append", default=[], help="Why prior and current evidence/criteria are not comparable; repeatable")
+    p_skill_evaluate.add_argument("--json", action="store_true", help="Emit JSON")
+
     p_skill_phase = skill_sub.add_parser("phase", help="Update a Skill run log phase state")
     p_skill_phase.add_argument("--log", required=True, help="Skill run log to update")
     p_skill_phase.add_argument(
@@ -672,6 +704,10 @@ def main(argv: list[str] | None = None) -> int:
             from xrefkit.skillrun import cmd_skill_feedback
 
             return cmd_skill_feedback(args)
+        if args.skill_cmd == "evaluate":
+            from xrefkit.skillrun import cmd_skill_evaluate
+
+            return cmd_skill_evaluate(args)
         if args.skill_cmd == "phase":
             from xrefkit.skillrun import cmd_skill_phase
 

{xrefkit-0.4.7 → xrefkit-0.4.8}/xrefkit/skillrun.py

@@ -28,6 +28,7 @@ from xrefkit.skillmeta import (
     resolve_os_contract,
     validate_skill_meta,
 )
+from xrefkit.models.human_evaluation import HumanEvaluation
 
 
 @dataclass
@@ -134,6 +135,13 @@ def _locked_log_update(func):
 
 
 VALID_PHASES = {"startup", "planning", "execution", "check", "quality", "closure", "handoff"}
+EVALUATION_DECISIONS = {
+    "accepted",
+    "accepted_with_conditions",
+    "correction",
+    "rejected_or_returned_to_human",
+    "needs_clarification",
+}
 VALID_PHASE_STATUSES = {"pending", "in_progress", "done", "blocked", "unknown", "escalated"}
 VALID_WORKITEM_STATUSES = {"pending", "in_progress", "done", "blocked", "unknown", "escalated"}
 VALID_ARTIFACT_STATUSES = {"pending", "in_progress", "done", "blocked", "unknown", "escalated"}
@@ -601,6 +609,11 @@ def _render_log(
 - status: `pending`
 - rule: record human acceptance, correction, or rejection with `xrefkit skill feedback --kind human`
 
+## Human Evaluation
+
+- status: `pending`
+- rule: optional run-boundary evaluation; control returns to the human without waiting, and a subsequent request may record a human-confirmed relationship with `xrefkit skill evaluate`
+
 ## Outcome Feedback
 
 - status: `pending`
@@ -2253,6 +2266,110 @@ def update_feedback_observation(args) -> SkillRunResult:
     )
 
 
+@_locked_log_update
+def update_human_evaluation(args) -> SkillRunResult:
+    """Record optional human evaluation after control has returned."""
+    log_path = Path(args.log).resolve()
+    text, error = _validate_observation_log(log_path)
+    if error is not None:
+        return error
+    assert text is not None
+    closure_status = _section_status(text, "Closure Gate")
+    if closure_status not in ACCEPTED_CLOSE_STATUSES:
+        return SkillRunResult(
+            ok=False,
+            skill_id=_log_skill_id(text),
+            skill_doc=None,
+            run_log=str(log_path),
+            errors=[
+                "human evaluation requires the preceding run Closure Gate to be done or escalated; "
+                f"current={closure_status or 'missing'}"
+            ],
+            run_id=_log_field(text, "run_id"),
+        )
+
+    verified_basis = [str(value).strip() for value in getattr(args, "verified", []) if str(value).strip()]
+    remaining_uncertainty = [
+        str(value).strip() for value in getattr(args, "uncertainty", []) if str(value).strip()
+    ]
+    scoped_links: dict[str, list[str]] = {}
+    scope_errors: list[str] = []
+    for raw_link in getattr(args, "scope_link", []):
+        parts = str(raw_link).split("|", 1)
+        if len(parts) != 2 or not parts[0].strip() or not parts[1].strip():
+            scope_errors.append("--scope-link must use TARGET|LINK")
+            continue
+        scoped_links.setdefault(parts[0].strip(), []).append(parts[1].strip())
+    scoped_findings: list[dict[str, object]] = []
+    for raw_finding in getattr(args, "scope_finding", []):
+        parts = str(raw_finding).split("|", 2)
+        if len(parts) != 3 or not all(part.strip() for part in parts):
+            scope_errors.append("--scope-finding must use TARGET|DECISION|NOTE")
+            continue
+        target, decision, note = (part.strip() for part in parts)
+        if decision not in EVALUATION_DECISIONS:
+            scope_errors.append(f"invalid scoped finding decision: {decision}")
+            continue
+        scoped_findings.append({
+            "target": target,
+            "decision": decision,
+            "note": note,
+            "linked_targets": scoped_links.get(target, []),
+        })
+    if scope_errors:
+        return SkillRunResult(
+            ok=False,
+            skill_id=_log_skill_id(text),
+            skill_doc=None,
+            run_log=str(log_path),
+            errors=scope_errors,
+            run_id=_log_field(text, "run_id"),
+        )
+    payload = {
+        "preceding_run_id": _log_field(text, "run_id"),
+        "decision": args.decision,
+        "classification": args.classification,
+        "next_handling": args.next_handling,
+        "purpose_fit": args.purpose_fit,
+        "verified_basis": verified_basis or ["none"],
+        "remaining_uncertainty": remaining_uncertainty or ["none"],
+        "carry_forward": [str(value).strip() for value in getattr(args, "carry_forward", []) if str(value).strip()],
+        "linked_targets": [str(value).strip() for value in getattr(args, "link", []) if str(value).strip()],
+        "scoped_findings": scoped_findings,
+        "proposed_classification": getattr(args, "proposed_classification", None),
+        "classification_source": "human_confirmed",
+        "reviewer": str(getattr(args, "reviewer", None) or "").strip() or None,
+        "evaluated_at": getattr(args, "evaluated_at", None),
+        "context_refs": [str(value).strip() for value in getattr(args, "context_ref", []) if str(value).strip()],
+        "comparability": getattr(args, "comparability", "not_assessed"),
+        "comparability_gaps": [str(value).strip() for value in getattr(args, "comparability_gap", []) if str(value).strip()],
+    }
+    if not payload["evaluated_at"]:
+        payload.pop("evaluated_at")
+    try:
+        evaluation = HumanEvaluation.model_validate(payload)
+    except Exception as exc:
+        return SkillRunResult(
+            ok=False,
+            skill_id=_log_skill_id(text),
+            skill_doc=None,
+            run_log=str(log_path),
+            errors=[f"invalid human evaluation: {exc}"],
+            run_id=_log_field(text, "run_id"),
+        )
+    event = {"event": "human.evaluation", **evaluation.model_dump(mode="json", exclude_none=True)}
+    text = _append_observation_event(text, section="Human Evaluation", event=event)
+    _atomic_write_text(log_path, text)
+    return SkillRunResult(
+        ok=True,
+        skill_id=_log_skill_id(text),
+        skill_doc=None,
+        run_log=str(log_path),
+        errors=[],
+        run_id=_log_field(text, "run_id"),
+    )
+
+
 @_locked_log_update
 def update_token_usage(args) -> SkillRunResult:
     log_path = Path(args.log).resolve()
@@ -2779,3 +2896,7 @@ def cmd_skill_knowledge(args) -> int:
 
 def cmd_skill_feedback(args) -> int:
     return _cmd_observation(args, update_feedback_observation, "feedback")
+
+
+def cmd_skill_evaluate(args) -> int:
+    return _cmd_observation(args, update_human_evaluation, "evaluate")

{xrefkit-0.4.7 → xrefkit-0.4.8}/xrefkit/skills_sync.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 import argparse
 import hashlib
 import json
-import re
 import tempfile
 import urllib.error
 import urllib.parse
@@ -18,7 +17,6 @@ from pathlib import Path, PurePosixPath
 DEFAULT_SOURCE_REPOSITORY = "synthaicode/XRefKit"
 DEFAULT_GITHUB_API = "https://api.github.com"
 ASSET_PREFIX = "xrefkit-skills-"
-VERSION_SUFFIX_RE = re.compile(r"^(?P<bundle>.+)-(?P<version>\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?)$")
 ALLOWED_ROOTS = {"skills", "knowledge", "review_axes", "schemas"}
 
 
@@ -44,7 +42,7 @@ class SyncResult:
         }
 
 
-def _github_json(url: str) -> dict[str, object]:
+def _github_json(url: str) -> object:
     request = urllib.request.Request(
         url,
         headers={
@@ -57,8 +55,6 @@ def _github_json(url: str) -> dict[str, object]:
             payload = json.loads(response.read().decode("utf-8"))
     except (urllib.error.URLError, urllib.error.HTTPError) as exc:
         raise RuntimeError(f"could not read GitHub release metadata: {url}") from exc
-    if not isinstance(payload, dict):
-        raise RuntimeError(f"GitHub release metadata was not an object: {url}")
     return payload
 
 
@@ -69,7 +65,17 @@ def _release(source_repository: str, release: str) -> dict[str, object]:
     else:
         encoded_release = urllib.parse.quote(release, safe="")
         url = f"{DEFAULT_GITHUB_API}/repos/{encoded_repo}/releases/tags/{encoded_release}"
-    return _github_json(url)
+    payload = _github_json(url)
+    return payload
+
+
+def _releases(source_repository: str) -> list[dict[str, object]]:
+    encoded_repo = urllib.parse.quote(source_repository, safe="/")
+    url = f"{DEFAULT_GITHUB_API}/repos/{encoded_repo}/releases?per_page=100"
+    payload = _github_json(url)
+    if not isinstance(payload, list):
+        raise RuntimeError(f"GitHub releases metadata was not a list: {url}")
+    return [item for item in payload if isinstance(item, dict)]
 
 
 def _assets(release: dict[str, object]) -> list[dict[str, object]]:
@@ -94,6 +100,52 @@ def _asset_for_bundle(release: dict[str, object], bundle: str) -> dict[str, obje
     return candidates[0]
 
 
+def _latest_release_for_bundle(source_repository: str, bundle: str) -> dict[str, object]:
+    tag_prefix = f"{ASSET_PREFIX}{bundle}-v"
+    candidates = []
+    for release in _releases(source_repository):
+        tag = release.get("tag_name")
+        if not isinstance(tag, str) or not tag.startswith(tag_prefix) or release.get("draft"):
+            continue
+        try:
+            _asset_for_bundle(release, bundle)
+        except RuntimeError:
+            continue
+        candidates.append(release)
+    if not candidates:
+        raise RuntimeError(
+            f"could not find a published Skill bundle release for {bundle}; "
+            f"expected tag prefix {tag_prefix}"
+        )
+    candidates.sort(
+        key=lambda release: str(release.get("published_at") or release.get("created_at") or ""),
+        reverse=True,
+    )
+    return candidates[0]
+
+
+def _release_for_bundle(source_repository: str, release: str, bundle: str) -> dict[str, object]:
+    if release == "latest":
+        return _latest_release_for_bundle(source_repository, bundle)
+    return _release(source_repository, release)
+
+
+def _bundle_names(releases: list[dict[str, object]]) -> list[str]:
+    names: list[str] = []
+    for release in releases:
+        tag = release.get("tag_name")
+        if not isinstance(tag, str) or not tag.startswith(ASSET_PREFIX) or "-v" not in tag:
+            continue
+        bundle = tag[len(ASSET_PREFIX) :].rsplit("-v", 1)[0]
+        try:
+            _asset_for_bundle(release, bundle)
+        except RuntimeError:
+            continue
+        if bundle not in names:
+            names.append(bundle)
+    return names
+
+
 def _download_asset(asset: dict[str, object]) -> tuple[str, bytes]:
     name = asset.get("name")
     url = asset.get("browser_download_url")
@@ -163,7 +215,7 @@ def sync_bundle(
     repo = repo.resolve()
     if not repo.is_dir():
         raise FileNotFoundError(f"XRefKit repository not found: {repo}")
-    release_payload = _release(source_repository, release)
+    release_payload = _release_for_bundle(source_repository, release, bundle)
     asset = _asset_for_bundle(release_payload, bundle)
     asset_name, data = _download_asset(asset)
     digest = hashlib.sha256(data).hexdigest()
@@ -240,7 +292,7 @@ def main(argv: list[str] | None = None) -> int:
     sync.add_argument("--repo", default=".", help="Target XRefKit repository; defaults to the current directory")
     sync.add_argument("--source-repository", default=DEFAULT_SOURCE_REPOSITORY, help="GitHub owner/repository containing releases")
     sync.add_argument("--bundle", action="append", help="Bundle name, for example csharp; repeat for multiple bundles")
-    sync.add_argument("--all", action="store_true", help="Synchronize every xrefkit-skills-*.zip asset in the release")
+    sync.add_argument("--all", action="store_true", help="Synchronize every bundle with a matching Skill release")
     sync.add_argument("--release", default="latest", help="Release tag, or latest (default)")
     sync.add_argument("--force", action="store_true", help="Allow overwriting files not owned by a previous sync")
     sync.add_argument("--dry-run", action="store_true", help="Download and validate without writing the repository")
@@ -248,16 +300,9 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
     if not args.bundle and not args.all:
         parser.error("one of --bundle or --all is required")
-    release_payload = _release(args.source_repository, args.release)
     bundles = list(args.bundle or [])
     if args.all:
-        for asset in _assets(release_payload):
-            name = asset.get("name")
-            if not isinstance(name, str) or not name.startswith(ASSET_PREFIX) or not name.endswith(".zip"):
-                continue
-            stem = name[:-4][len(ASSET_PREFIX) :]
-            match = VERSION_SUFFIX_RE.match(stem)
-            bundles.append(match.group("bundle") if match else stem)
+        bundles.extend(_bundle_names(_releases(args.source_repository)))
     bundles = list(dict.fromkeys(bundles))
     results = [
         sync_bundle(

{xrefkit-0.4.7 → xrefkit-0.4.8}/xrefkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.7
+Version: 0.4.8
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -178,6 +178,22 @@ If the `xrefkit` command is not available on `PATH`, use the module form:
 python -m xrefkit --help
 ```
 
+### Markdown WBS validation and rollups
+
+Keep one task per row in a Markdown table, then validate and regenerate the
+feature, phase, and feature-by-phase views without editing the source table:
+
+```powershell
+python -m xrefkit wbs validate samples/wbs.md
+python -m xrefkit wbs rollup samples/wbs.md
+python -m xrefkit wbs csv samples/wbs.md .tmp/wbs.csv
+```
+
+The validator rejects missing or extra cells, duplicate IDs, non-numeric or
+negative effort, and statuses outside `todo`, `doing`, and `done`. CSV output
+uses UTF-8 with BOM for Excel compatibility; the Markdown WBS remains the
+source of truth.
+
 To use the integrated MCP server, install the optional MCP dependencies:
 
 ```powershell

{xrefkit-0.4.7 → xrefkit-0.4.8}/xrefkit.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ README.md
 pyproject.toml
 tests/test_base_sync_ownership.py
 tests/test_boundary_analysis.py
+tests/test_brownfield_file_editing_protocol.py
 tests/test_calibration_lint.py
 tests/test_check_skill_knowledge_xids.py
 tests/test_cli.py
@@ -19,6 +20,7 @@ tests/test_error_policy_locator.py
 tests/test_fm_multiroot.py
 tests/test_gate.py
 tests/test_goal_desired_state.py
+tests/test_human_evaluation.py
 tests/test_instruction_workflow.py
 tests/test_knowledge_relations_validator.py
 tests/test_mcp_setup.py
@@ -93,6 +95,7 @@ xrefkit/mcp/startup_contract_pack.py
 xrefkit/models/__init__.py
 xrefkit/models/common.py
 xrefkit/models/effective_bundle.py
+xrefkit/models/human_evaluation.py
 xrefkit/models/local_manifest.py
 xrefkit/models/package_manifest.py
 xrefkit/models/run_log.py