cowork-flow 1.9.2 → 2.1.0

package/template/skills/runtime-health/scripts/doctor.py

@@ -672,52 +672,6 @@ def check_runtime(repo_root: Path) -> list[str]:
     return errors
 
 
-def check_spec_checks(repo_root: Path) -> list[dict[str, str]]:
-    """Spec-check declaration health: parse errors and command entry
-    existence. Execution belongs to `run spec-check`; doctor only proves
-    the declarations can run, before a completion gate finds out they
-    cannot."""
-    issues: list[dict[str, str]] = []
-    import shutil
-
-    try:
-        from services.spec_check import collect_spec_declarations
-    except Exception as error:
-        return [
-            {
-                "kind": "spec-checks",
-                "spec": "",
-                "message": f"spec-check service unavailable: {error}",
-            }
-        ]
-    for spec_decls in collect_spec_declarations(repo_root):
-        for message in spec_decls.errors:
-            issues.append(
-                {"kind": "spec-checks", "spec": spec_decls.spec, "message": message}
-            )
-        for decl in spec_decls.decls:
-            entry = (decl.cmd_win if sys.platform == "win32" else decl.cmd) or decl.cmd
-            first_token = entry.split()[0] if entry.split() else ""
-            if not first_token:
-                issues.append(
-                    {
-                        "kind": "spec-checks",
-                        "spec": spec_decls.spec,
-                        "message": f"empty command declaration: {decl.cmd!r}",
-                    }
-                )
-                continue
-            if shutil.which(first_token) is None:
-                issues.append(
-                    {
-                        "kind": "spec-checks",
-                        "spec": spec_decls.spec,
-                        "message": f"command entry not found: {first_token}",
-                    }
-                )
-    return issues
-
-
 def _global_mcp_registered() -> bool:
     """Tolerant probe of user-level host configs for a cowork-flow MCP
     entry. Read-only; missing files simply mean "not registered"."""
@@ -1098,6 +1052,82 @@ def check_qoder_plugin(repo_root: Path) -> list[dict[str, str]]:
     return []
 
 
+_ZCODE_PLUGIN_CONTRACT = "runtime-health:zcode-plugin"
+
+
+def _zcode_warning(code: str, path: Path, message: str, hint: str) -> list[dict[str, str]]:
+    return [
+        _issue(
+            code=code,
+            severity="warning",
+            path=str(path),
+            message=message,
+            command_hint=hint,
+            contract=_ZCODE_PLUGIN_CONTRACT,
+        )
+    ]
+
+
+def _zcode_marketplace_path() -> Path:
+    home = Path(os.environ.get("ZCODE_HOME") or (Path.home() / ".zcode"))
+    return (
+        home
+        / "cli"
+        / "plugins"
+        / "marketplaces"
+        / "cowork-flow-local"
+        / "marketplace.json"
+    )
+
+
+def check_zcode_plugin(repo_root: Path) -> list[dict[str, str]]:
+    """ZCode plugin health. Advisory, and silent while the project never selected
+    the ZCode host: the plugin is a machine-level asset installed once into the
+    ZCode config directory, so it never updates through sync or npm.
+
+    Staleness is judged on the payload's stamped manifest version rather than
+    per file: the payload also carries a materialized copy of the project
+    runtime, and that copy may legitimately differ from this project."""
+    adapter = repo_root / DIR_WORKFLOW / "adapters" / "zcode" / "adapter.yaml"
+    if not adapter.is_file():
+        return []
+
+    marketplace = _zcode_marketplace_path()
+    payload = _machine_plugin_payload("zcode")
+    if payload is None:
+        return _zcode_warning(
+            "PLUGIN-NOT-INSTALLED",
+            marketplace,
+            "this project declares the ZCode host, but no cowork-flow plugin is "
+            "installed in the ZCode config directory, so ZCode sessions inject no "
+            "workflow context",
+            "cwf host add zcode",
+        )
+
+    manifest_relative = _payload_manifest("zcode", repo_root) or ".zcode-plugin/plugin.json"
+    manifest = payload / manifest_relative
+    recorded = _marker_version(manifest)
+    if recorded is None:
+        return _zcode_warning(
+            "PLUGIN-UNKNOWN-VERSION",
+            manifest,
+            "the installed ZCode plugin carries no readable manifest version, so "
+            "its injection logic may predate the current release",
+            "cwf host add zcode --force",
+        )
+    project_version = _project_version(repo_root)
+    if project_version and recorded != project_version:
+        return _zcode_warning(
+            "PLUGIN-STALE",
+            manifest,
+            f"the ZCode plugin was installed from {recorded} but this project "
+            f"runs {project_version}; the plugin does not update with sync or npm, "
+            "so injection may lag the project runtime",
+            "cwf host add zcode --force",
+        )
+    return []
+
+
 _CLAUDE_CODE_PLUGIN_CONTRACT = "runtime-health:claude-code-plugin"
 _CLAUDE_CODE_PLUGIN_NAME = "cowork-flow"
 _CLAUDE_CODE_SKILL = "skills/cowork-flow-bootstrap/SKILL.md"
@@ -1524,15 +1554,7 @@ def _machine_plugin_payload(platform_id: str) -> Path | None:
         payload = Path(str(entry.get("installPath") or "")) if entry else None
         return payload if payload is not None and payload.is_dir() else None
     if platform_id == "zcode":
-        home = Path(os.environ.get("ZCODE_HOME") or (Path.home() / ".zcode"))
-        marketplace = (
-            home
-            / "cli"
-            / "plugins"
-            / "marketplaces"
-            / "cowork-flow-local"
-            / "marketplace.json"
-        )
+        marketplace = _zcode_marketplace_path()
         try:
             data = json.loads(marketplace.read_text(encoding="utf-8"))
         except (OSError, json.JSONDecodeError, ValueError):
@@ -1654,7 +1676,6 @@ def _all_check_result(repo_root: Path) -> dict[str, object]:
     task_hygiene_issues = check_task_hygiene(repo_root)
     state_recovery_issues = check_state_recovery(repo_root)
     session_hygiene_issues = check_session_hygiene(repo_root)
-    spec_check_issues = check_spec_checks(repo_root)
     mcp_issues = check_mcp_registration(repo_root)
     dsh_preset_issues = check_dsh_preset(repo_root)
     kimi_hook_issues = check_kimi_hook(repo_root)
@@ -1662,6 +1683,7 @@ def _all_check_result(repo_root: Path) -> dict[str, object]:
     codex_plugin_issues = check_codex_plugin(repo_root)
     claude_code_plugin_issues = check_claude_code_plugin(repo_root)
     opencode_plugin_issues = check_opencode_plugin(repo_root)
+    zcode_plugin_issues = check_zcode_plugin(repo_root)
     kimi_code_plugin_issues = check_kimi_code_plugin(repo_root)
     skill_delivery_issues = check_skill_delivery(repo_root)
     errors: list[dict[str, object]] = []
@@ -1675,7 +1697,6 @@ def _all_check_result(repo_root: Path) -> dict[str, object]:
         {"kind": "distribution", "message": error}
         for error in distribution_errors
     )
-    errors.extend({"kind": "spec-checks", **issue} for issue in spec_check_issues)
     return {
         "ok": not errors,
         "errors": errors,
@@ -1684,7 +1705,6 @@ def _all_check_result(repo_root: Path) -> dict[str, object]:
             "taskHygiene": task_hygiene_issues,
             "stateRecovery": state_recovery_issues,
             "sessionHygiene": session_hygiene_issues,
-            "specChecks": spec_check_issues,
             "mcpRegistration": mcp_issues,
             "dshPreset": dsh_preset_issues,
             "kimiHook": kimi_hook_issues,
@@ -1692,6 +1712,7 @@ def _all_check_result(repo_root: Path) -> dict[str, object]:
             "codexPlugin": codex_plugin_issues,
             "claudeCodePlugin": claude_code_plugin_issues,
             "opencodePlugin": opencode_plugin_issues,
+            "zcodePlugin": zcode_plugin_issues,
             "kimiCodePlugin": kimi_code_plugin_issues,
             "skillDelivery": skill_delivery_issues,
         },
@@ -1733,6 +1754,10 @@ def _run_checks(repo_root: Path, *, structured: bool = False) -> int:
         print(f"OpenCode plugin ({issue['code']}): {issue['message']}")
         if issue.get("commandHint"):
             print(f"  fix: {issue['commandHint']}")
+    for issue in result["issues"]["zcodePlugin"]:
+        print(f"ZCode plugin ({issue['code']}): {issue['message']}")
+        if issue.get("commandHint"):
+            print(f"  fix: {issue['commandHint']}")
     for issue in result["issues"]["kimiCodePlugin"]:
         print(f"Kimi Code plugin ({issue['code']}): {issue['message']}")
         if issue.get("commandHint"):

package/template/skills/spec-sync/SKILL.md

@@ -33,7 +33,6 @@ Keep each update concrete:
 - Show the contract or command shape.
 - Include good/bad cases when useful.
 - State tests or checks that protect the behavior.
-- When a clause is machine-checkable (可机检), add or refresh its `checks:` declaration in the same pass (main session only — never rewrite the clause text): the command must pass on a clean tree, a negative case must prove it can fail, `files` must narrow the scope, and a `spec-check` run after writing must confirm the declaration parses.
 - Update the matching `index.md` when adding a new topic.
 - Check for duplicate guidance and remove stale wording before finishing.
 

package/template/skills/task-planning/SKILL.md

@@ -128,7 +128,7 @@ Then list task briefs, followed by integrated verification and completion checks
 
 - For Tiny tasks, keep the brief short but still name exact file boundaries, completion conditions, and verification commands.
 - For behavior changes, include a failing test before implementation when behavior can be tested.
-- For implementation tasks whose changed files are covered by spec `checks:` declarations, include the spec self-check in the task's Verification Command (for example `./.cowork-flow/run spec-check`): delegated subagents receive no edit-phase hook feedback on some hosts (zcode), so the explicit command is the reliable pull path for both self-check and acceptance.
+- For implementation tasks whose changed files are covered by `.cowork-flow/spec/` requirements, name the covered spec files in the plan so review can check them clause by clause.
 - Do not add shallow tests just to satisfy process. Avoid tests that only assert existence, mirror implementation details, count mock calls without behavior, or snapshot empty structure.
 - For complex problems, test depth first: business invariants, cross-layer contracts, state transitions, error boundaries, and real regression paths before narrow unit cases.
 - Map behavior-changing tests to stable `decision-anchor.md` acceptance IDs when useful; do not create `tdd.jsonl` or write TDD evidence records into `check.jsonl`.

package/template/skills/task-review/SKILL.md

@@ -39,11 +39,11 @@ Read only what is needed for the current task:
 - **Tests**: test intent is explicit; tests fail for meaningful regressions, reject shallow tests such as existence/mock/snapshot-only checks, and cover boundary/error paths when relevant.
 - **Evidence coverage**: when the decision anchor declares acceptance criteria (`AC-xxx`), verify each one has an evidence record in `<task>/evidence.jsonl` — or a recorded `meta.evidenceExempt` exemption from an explicit `--allow-missing-evidence` completion. Schema and gate codes (`LIFECYCLE-AC-001..004`) are defined in `.cowork-flow/spec/contracts/evidence-completion.md`. A record must point at real proof (test, command output, or manual verification note); a record that restates the AC without evidence is a finding.
 - **Receipt freshness**: a strict task's completion gate requires the latest receipt to match the current change fingerprint, which covers the changed paths' content, the anchor's goal and AC text, the bound plan, `dev_type`, the referenced spec bodies, and `implement.jsonl`. Appending a scope entry to `implement.jsonl` — or editing a referenced spec body — therefore invalidates the receipt, so the review is re-run on the final state. That is the intended cost, not a defect. Evidence appends, AC ticks, and `.cowork-flow/.runtime/**` stay fingerprint-neutral, so closeout never invalidates what it just checked.
-- **User specs**: every applicable backend/frontend requirement is verified against the diff and marked `pass`, `finding`, or `not_applicable` with reason. Every `finding` is fixed during review; an unfixed spec violation blocks completion and is never accepted as-is or deferred to the user. For each requirement, also ask whether it is machine-checkable (可机检) and already declared with `checks:`; identifying checkable clauses and adding or refreshing declarations is a main-session duty (never rewrite the clause text — raise a conflict through the review instead), and a declared check must earn its place: the command passes on a clean tree, a negative case proves it can fail, `files` narrows the scope, and a `spec-check` run after declaring confirms the declaration parses. Delegated subagents do not edit specs; they report candidates up.
+- **User specs**: every applicable backend/frontend requirement is verified against the diff and marked `pass`, `finding`, or `not_applicable` with reason. Every `finding` is fixed during review; an unfixed spec violation blocks completion and is never accepted as-is or deferred to the user. For each requirement, also ask whether it is machine-checkable (可机检) and name the command that decides it together with what that command reports when the clause is broken: a machine-checkable clause left with no deciding command is itself a finding. Review never rewrites the clause text — a conflict between a clause and the implementation is raised through the review for the user to decide. Delegated subagents do not edit specs; they report candidates up.
 - **Specs**: project specs are updated when behavior/contracts changed, or the review states why no spec update is needed.
 - **Code quality**: naming, layering, error handling, state boundaries, security-sensitive paths, and complexity are reviewed against applicable user specs.
 - **Lifecycle blockers**: state/scope blockers are fixed before acceptance; review does not invent hard blockers for natural-language specs.
-- **Delegated acceptance**: when the implementation came from a delegated subagent, run `./.cowork-flow/run spec-check` before accepting its report — delegated sessions receive no edit-phase hook feedback on some hosts (zcode), so the report can be silently non-compliant; every violation is fixed or blocks acceptance.
+- **Delegated acceptance**: when the implementation came from a delegated subagent, verify the changed paths against the task scope and the applicable `spec/` requirements before accepting its report — delegated sessions receive no edit-phase hook feedback on some hosts, so the report can be silently out of scope or out of spec; every violation is fixed or blocks acceptance.
 - **Advisory facts**: helper output is used to focus review, not to declare pass/fail or block completion.
 - **Anti-self-proof**: every claimed pass maps to source, diff, test output, or lifecycle output.
 - **Anti-rationalization**: every accepted gap has an explicit user decision or narrow technical reason.
@@ -85,7 +85,7 @@ Return a concise review result with:
 - `status`: `pass`, `needs_fix`, or `blocked`.
 - `findings`: severity, file, line/scope, impact, fix, plus the `clause` / `command` / `negativeProof` triple defined in Review Report Format.
 - `test_intent_review`: why tests prove the intended behavior or what is missing.
-- `user_spec_review`: applicable spec files, per-requirement result, findings, and the "clause → command → negative proof" list for every `checks:` declaration added or refreshed in this review (`none` when nothing became machine-checkable).
+- `user_spec_review`: applicable spec files, per-requirement result, findings, and the "clause → command → negative proof" list for every machine-checkable requirement the review judged (`none` when nothing was machine-checkable).
 - `lifecycle_check_review`: lifecycle commands run, blocker status, and resolution.
 - `verification`: exact commands run from this checkout.
 - `specUpdates`: files updated or reason no update was needed.

package/template/.cowork-flow/scripts/adapters/cli/spec_check.py

@@ -1,178 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""`run spec-check [--phase edit|lifecycle] [--file <path>...] [--json]`.
-
-Executes user-declared spec checks (frontmatter `checks:`) and prints a
-normalized one-line summary unless `--json`/`--verbose` asks for more. See
-services/spec_check.py for the three-state contract (pass/violation/unchecked).
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-
-if __package__:
-    from . import _bootstrap as _bootstrap  # noqa: F401
-else:
-    import _bootstrap  # noqa: F401
-
-from infra.paths import get_repo_root
-from services.spec_check import SpecCheckError, run_checks, summary_has
-
-
-def _report_exit_code(report: dict) -> int:
-    """Map a report to the public spec-check exit contract."""
-    if summary_has(report, "violation"):
-        return 1
-    # An executor failure means the checks never produced a verdict; it must
-    # never exit 0 just because the synthetic report carries no counter.
-    if (
-        summary_has(report, "unchecked")
-        or summary_has(report, "executorError")
-        or report.get("parseErrors")
-    ):
-        return 2
-    return 0
-
-
-def _parse_error_line(parse_errors: list) -> str:
-    """Render parse failures so text mode cannot look like a clean run."""
-    details = []
-    for item in parse_errors[:3]:
-        if isinstance(item, dict):
-            spec = item.get("spec") or "?"
-            error = item.get("error") or "unknown parse error"
-            details.append(f"{spec}: {error}")
-    suffix = f": {'; '.join(details)}" if details else ""
-    return f"spec-check: {len(parse_errors)} parse error(s){suffix}"
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog="spec-check",
-        description=(
-            "Run user-declared spec checks (frontmatter checks:) for one phase."
-        ),
-    )
-    parser.add_argument(
-        "--phase",
-        choices=("edit", "lifecycle"),
-        default="lifecycle",
-        help="edit: only declarations matching the given files (2.5s clamp); "
-        "lifecycle: every declaration honoring its files scope.",
-    )
-    parser.add_argument(
-        "--file",
-        action="append",
-        default=None,
-        help="Changed file path to match against declaration files filters; "
-        "repeatable. Drives the edit-phase filter and single-file queries.",
-    )
-    parser.add_argument(
-        "--verbose",
-        action="store_true",
-        help="Print full command output per result (query mode only).",
-    )
-    parser.add_argument(
-        "--throttled",
-        action="store_true",
-        help="Editor-phase mode: single-line report for one file, throttled "
-        "per file (empty output when nothing to report).",
-    )
-    parser.add_argument(
-        "--json",
-        action="store_true",
-        dest="as_json",
-        help="Print the machine-readable report.",
-    )
-    return parser
-
-
-def _run_throttled(repo_root, changed_files: list[str]) -> int:
-    from services.spec_check import run_edit_checks
-
-    if len(changed_files) != 1:
-        print("Error: --throttled requires exactly one --file", file=sys.stderr)
-        return 2
-    print(run_edit_checks(repo_root, changed_files[0]))
-    return 0
-
-
-def _print_text_report(report: dict, *, verbose: bool) -> None:
-    if verbose:
-        for result in report.get("results", []):
-            print(f"--- {result.get('spec')} :: {result.get('cmd')}")
-            for line in result.get("output", []):
-                print(line)
-            if result.get("reason"):
-                print(f"reason: {result['reason']}")
-
-    parse_errors = report.get("parseErrors") or []
-    if parse_errors:
-        print(_parse_error_line(parse_errors))
-        return
-
-    summary = report.get("summary", {})
-    if not parse_errors and summary.get("declarations") == 0:
-        # Zero declarations is a fact, not a pass: name it so a missing or
-        # silently ignored declaration block cannot look like a clean run.
-        print(
-            "spec-check: no checks declared "
-            f"({report.get('specFiles', 0)} spec files scanned)"
-        )
-        # The reader of this branch is the session that has just been told
-        # nothing is enforced, not a human skimming a terminal: without the
-        # write path and the syntax reference in the same breath, the fact it
-        # is looking at has no obvious next action attached to it.
-        print(
-            "next: write .cowork-flow/spec/<name>.md with frontmatter "
-            "checks: (any .md under spec/ outside contracts/, runtime/, "
-            "schemas/); syntax and example: "
-            ".cowork-flow/spec/contracts/spec-checks.md"
-        )
-        return
-
-    from services.spec_check import normalized_one_line
-
-    line = normalized_one_line(report)
-    if line:
-        print(line)
-        return
-    print(
-        "spec-check: {pass} passed, {violation} violations, "
-        "{unchecked} unchecked".format(
-            **{**{"pass": 0, "violation": 0, "unchecked": 0}, **summary}
-        )
-    )
-
-
-def main() -> int:
-    args = _build_parser().parse_args()
-    repo_root = get_repo_root()
-
-    if args.throttled:
-        return _run_throttled(repo_root, args.file or [])
-
-    try:
-        report = run_checks(
-            repo_root,
-            phase=args.phase,
-            changed_files=args.file or [],
-        )
-    except SpecCheckError as error:
-        print(f"Error: {error}", file=sys.stderr)
-        return 2
-
-    exit_code = _report_exit_code(report)
-    if args.as_json:
-        print(json.dumps(report, ensure_ascii=False, indent=2))
-        return exit_code
-
-    _print_text_report(report, verbose=args.verbose)
-    return exit_code
-
-
-if __name__ == "__main__":
-    sys.exit(main())