cowork-flow 0.0.41 → 0.0.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.41",
+  "version": "0.0.42",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/src/commands/install-zcode-plugin.js

@@ -72,6 +72,7 @@ export async function runInstallZCodePlugin(args = []) {
   const { dryRun, force } = parseArgs(args);
   const pluginSrc = join(templateRoot, ".zcode");
   const skillsSrc = join(templateRoot, "skills");
+  const specSrc = join(templateRoot, ".cowork-flow", "spec");
   const { version } = await readPackageInfo();
 
   if (!(await pathExists(pluginSrc))) {
@@ -80,6 +81,9 @@ export async function runInstallZCodePlugin(args = []) {
   if (!(await pathExists(skillsSrc))) {
     throw new Error(`Skills source missing at ${skillsSrc}. Reinstall cowork-flow.`);
   }
+  if (!(await pathExists(specSrc))) {
+    throw new Error(`Spec source missing at ${specSrc}. Reinstall cowork-flow.`);
+  }
 
   const cacheRoot = await getZCodeCacheDir();
   const destDir = join(cacheRoot, version);
@@ -94,6 +98,7 @@ export async function runInstallZCodePlugin(args = []) {
     console.log(`[dry-run] Would install ZCode plugin:`);
     console.log(`  Plugin: ${pluginSrc} -> ${destDir}`);
     console.log(`  Skills: ${skillsSrc} -> ${join(destDir, 'skills')}`);
+    console.log(`  Spec: ${specSrc} -> ${join(destDir, 'scaffold', '.cowork-flow', 'spec')}`);
     return;
   }
 
@@ -110,6 +115,12 @@ export async function runInstallZCodePlugin(args = []) {
   const scaffoldVersionPath = join(destDir, "scaffold", ".cowork-flow", ".version");
   await writeFile(scaffoldVersionPath, `${version}\n`, "utf8");
 
+  // Materialize scaffold specs from the main template instead of maintaining
+  // a second static copy under template/.zcode/scaffold/.
+  const scaffoldSpecDest = join(destDir, "scaffold", ".cowork-flow", "spec");
+  await rm(scaffoldSpecDest, { recursive: true, force: true });
+  await cp(specSrc, scaffoldSpecDest, { recursive: true, force: true });
+
   // Sync canonical scripts from main template (single source of truth).
   // The .zcode/hooks/runtime/scripts/ copy is stale; overwrite with the
   // authoritative version from template/.cowork-flow/scripts/.

package/template/.claude/agents/cowork-check.md

@@ -38,8 +38,11 @@ Load context before checking:
 2. Read `<task>/decision-anchor.md`.
 3. Read the plan file linked from this task (check `<task>/task.json` `relatedFiles` for a plan path, or search `.cowork-flow/plans/` for a plan file referencing this task directory). Use the plan's Verify commands and Expected results as the checklist for each step.
 4. Read `<task>/check.jsonl`.
-5. Read `git diff`.
-6. Include `test_intent_review` in the review output for meaningful behavior
+5. Read each JSONL `file` entry from `<task>/check.jsonl`.
+6. Read `<task>/quality-review.jsonl` if present and verify machine warning,
+   checklist, and Definition of Done evidence.
+7. Read `git diff`.
+8. Include `test_intent_review` in the review output for meaningful behavior
    breaks coverage and shallow tests rejection.
 
 Authoritative internal protocols:
@@ -59,3 +62,11 @@ Rules:
 - Report findings, changed files, and exact verification commands.
 - Include test intent findings that map tests back to decision-anchor acceptance or
   regression behavior.
+- Run the deterministic coding gate before accepting quality:
+  `./.cowork-flow/run python .cowork-flow/scripts/common/gates/validate_coding_standards.py --validate --repo-root .`.
+  This gate enforces machine-decidable UTF-8/IO checks; backend/frontend
+  natural-language markdown remains checklist context, not dynamic hard validators.
+- Treat machine warning output as review evidence: fix real issues or require
+  acknowledged warning records in `<task>/quality-review.jsonl`.
+- Verify `<task>/quality-review.jsonl` covers Definition of Done, checklist
+  sources, affected files, and exact verification commands before acceptance.

package/template/.claude/agents/cowork-implement.md

@@ -36,12 +36,16 @@ the task.
 Load context before editing:
 1. Read the task directory from the bound runtime context.
 2. Read `<task>/decision-anchor.md`.
-3. Read .
+3. Read `<task>/info.md` if present.
 4. Read `<task>/implement.jsonl`.
 5. Read each JSONL `file` entry.
 6. Read the plan file linked from this task (check `<task>/task.json` `relatedFiles` for a plan path, or search `.cowork-flow/plans/` for a plan file referencing this task directory). Follow the plan steps in order — each step has Files, Action, Verify, and Expected fields.
-7. For behavior-change tasks, create or verify `<task>/tdd.jsonl` before
+7. Read quality source entries from context; backend/frontend natural-language
+   specs are review checklists, not dynamic hard validators.
+8. For behavior-change tasks, create or verify `<task>/tdd.jsonl` before
    implementation or record a documented exemption.
+9. Before reporting completion, write `<task>/quality-review.jsonl` with
+   checklist, machine warning, and Definition of Done evidence.
 
 Authoritative internal protocols:
 - `.cowork-flow/spec/protocols/tdd.md`
@@ -62,3 +66,11 @@ Rules:
   include redCommand, redExitCode, greenCommand, greenExitCode, and
   decision-anchor acceptance ID mapping.
 - Report changed files and exact verification commands.
+- Before editing source files, run the deterministic coding gate:
+  `./.cowork-flow/run python .cowork-flow/scripts/common/gates/validate_coding_standards.py --validate --repo-root .`.
+  This gate enforces machine-decidable UTF-8/IO checks; backend/frontend
+  natural-language markdown remains checklist context, not dynamic hard validators.
+- Fix machine warning findings or record acknowledged warning evidence in
+  `<task>/quality-review.jsonl`.
+- Record Definition of Done and quality checklist evidence in
+  `<task>/quality-review.jsonl`.

package/template/.codex/agents/cowork-check.toml

@@ -29,8 +29,11 @@ Load context before checking:
 2. Read `<task>/decision-anchor.md`.
 3. Read the plan file linked from this task (check `<task>/task.json` `relatedFiles` for a plan path, or search `.cowork-flow/plans/` for a plan file referencing this task directory). Use the plan's Verify commands and Expected results as the checklist for each step.
 4. Read `<task>/check.jsonl`.
-5. Read `git diff`.
-6. Include `test_intent_review` in the review output for meaningful behavior breaks coverage and shallow tests rejection.
+5. Read each JSONL `file` entry from `<task>/check.jsonl`.
+6. Read `<task>/quality-review.jsonl` if present and verify machine warning,
+   checklist, and Definition of Done evidence.
+7. Read `git diff`.
+8. Include `test_intent_review` in the review output for meaningful behavior breaks coverage and shallow tests rejection.
 
 Authoritative internal protocols:
 - `.cowork-flow/spec/protocols/review.md`
@@ -47,13 +50,15 @@ Rules:
 - MUST NOT commit, archive, or mutate cowork-flow task state.
 - Report findings, changed files, and exact verification commands.
 - Include test intent findings that map tests back to decision-anchor acceptance criteria or regression behavior.
-- BEFORE declaring decision-anchor acceptance passed, run the spec-driven coding gate and
+- BEFORE declaring decision-anchor acceptance passed, run the deterministic coding gate and
   treat a nonzero exit as a hard blocker:
   ./.cowork-flow/run python .cowork-flow/scripts/common/gates/validate_coding_standards.py --validate --repo-root .
-  This naturally enforces every rule the user added to
-  .cowork-flow/spec/backend/*.md and spec/frontend/*.md — they are not just
-  documentation but active validators. On violation, either fix the code or
-  explicitly discard the rule from the spec; do not skip the gate.
+  This gate enforces machine-decidable UTF-8/IO checks. Backend/frontend
+  natural-language markdown remains checklist context, not dynamic hard validators.
+- Treat machine warning output as review evidence: fix real issues or require
+  an acknowledged warning record in `<task>/quality-review.jsonl`.
+- Verify `<task>/quality-review.jsonl` covers Definition of Done, checklist
+  sources, affected files, and exact verification commands before acceptance.
 """
 
 [features]

package/template/.codex/agents/cowork-implement.toml

@@ -31,7 +31,11 @@ Load context before editing:
 4. Read `<task>/implement.jsonl`.
 5. Read each JSONL `file` entry.
 6. Read the plan file linked from this task (check `<task>/task.json` `relatedFiles` for a plan path, or search `.cowork-flow/plans/` for a plan file referencing this task directory). Follow the plan steps in order — each step has Files, Action, Verify, and Expected fields.
-7. For behavior-change tasks, create or verify `<task>/tdd.jsonl` before implementation or record a documented exemption.
+7. Read quality source entries from context; backend/frontend natural-language
+   specs are review checklists, not dynamic hard validators.
+8. For behavior-change tasks, create or verify `<task>/tdd.jsonl` before implementation or record a documented exemption.
+9. Before reporting completion, write `<task>/quality-review.jsonl` with
+   checklist, machine warning, and Definition of Done evidence.
 
 Authoritative internal protocols:
 - `.cowork-flow/spec/protocols/tdd.md`
@@ -49,12 +53,15 @@ Rules:
 - Keep edits inside requested scope.
 - Do not treat shallow tests as TDD evidence; red-green-refactor proof must include redCommand, redExitCode, greenCommand, greenExitCode, and decision-anchor acceptance ID mapping.
 - Report changed files and exact verification commands.
-- BEFORE editing any source file, run the spec-driven coding gate and treat a
+- BEFORE editing any source file, run the deterministic coding gate and treat a
   nonzero exit as a hard blocker:
   ./.cowork-flow/run python .cowork-flow/scripts/common/gates/validate_coding_standards.py --validate --repo-root .
-  Parse every *.md under .cowork-flow/spec/backend and spec/frontend; rules
-  declared there activate validators dynamically. On violation, fix the code
-  (do not disable the rule) and re-run until exit code 0.
+  This gate enforces machine-decidable UTF-8/IO checks. Backend/frontend
+  natural-language markdown remains checklist context, not dynamic hard validators.
+- Run or inspect machine warning output, fix real issues, and record any
+  acknowledged warning in `<task>/quality-review.jsonl`.
+- Record Definition of Done coverage and quality checklist evidence in
+  `<task>/quality-review.jsonl`.
 """
 
 [features]

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.41
+0.0.42

package/template/.cowork-flow/scripts/application/task_context.py

@@ -9,6 +9,10 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from common.core.files import read_text_utf8
+from common.core.quality_sources import (
+    quality_review_artifact_entry,
+    quality_source_entries,
+)
 from common.core.skill_registry import SkillRegistryError, load_skill_registry
 from common.core.paths import (
     DIR_AGENTS,
@@ -457,13 +461,15 @@ def get_check_context(repo_root: Path, dev_type: str) -> list[dict]:
             "reason": "Workflow review, completion, and archive routing",
         },
     ]
-    entries.extend(
-        {
-            "file": spec_file,
-            "reason": f"Verify {Path(spec_file).name} compliance",
-        }
-        for spec_file in discover_spec_files(repo_root, dev_type)
-    )
+    if dev_type == "spec":
+        entries.extend(
+            {
+                "file": spec_file,
+                "reason": f"Verify {Path(spec_file).name} compliance",
+            }
+            for spec_file in discover_spec_files(repo_root, dev_type)
+        )
+    entries.extend(quality_source_entries(repo_root, dev_type))
     return entries
 
 
@@ -519,8 +525,12 @@ class TaskContextService:
                 "task directory does not exist",
             )
 
+        implement_entries = self._implement_entries(dev_type)
+        implement_entries.append(
+            quality_review_artifact_entry(task_dir, self.repo_root)
+        )
         entries_by_file = {
-            "implement.jsonl": self._implement_entries(dev_type),
+            "implement.jsonl": implement_entries,
             "check.jsonl": get_check_context(self.repo_root, dev_type),
             "debug.jsonl": get_debug_context(dev_type, self.repo_root),
         }

package/template/.cowork-flow/scripts/common/core/quality_sources.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Resolve precise quality context sources for review/check stages."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+QUALITY_REVIEW_FILE = "quality-review.jsonl"
+SPEC_ROOT = ".cowork-flow/spec"
+REFERENCE_DOD = f"{SPEC_ROOT}/references/definition-of-done.md"
+REFERENCE_TESTING = f"{SPEC_ROOT}/references/testing-checklist.md"
+REFERENCE_SECURITY = f"{SPEC_ROOT}/references/security-checklist.md"
+
+_MARKDOWN_LINK_RE = re.compile(r"\[[^\]]+\]\(([^)#]+)(?:#[^)]+)?\)")
+_SECURITY_HINT_RE = re.compile(
+    r"(?i)(auth|credential|jwt|oauth|password|permission|secret|security|session|token|\.env)"
+)
+
+
+def quality_source_entries(
+    repo_root: Path,
+    dev_type: str,
+    *,
+    paths: tuple[str, ...] = (),
+) -> list[dict]:
+    """Return narrow quality/spec sources a checker should read."""
+    entries: list[dict] = []
+    seen: set[str] = set()
+    for source in quality_source_paths(repo_root, dev_type, paths=paths):
+        if source in seen:
+            continue
+        seen.add(source)
+        entries.append(
+            {
+                "file": source,
+                "reason": _quality_source_reason(source),
+            }
+        )
+    return entries
+
+
+def quality_source_paths(
+    repo_root: Path,
+    dev_type: str,
+    *,
+    paths: tuple[str, ...] = (),
+) -> list[str]:
+    """Return existing repo-relative quality source paths."""
+    root = Path(repo_root)
+    sources: list[str] = []
+    for category in _categories_for(dev_type):
+        index = f"{SPEC_ROOT}/{category}/index.md"
+        sources.extend(_existing_paths(root, (index,)))
+        sources.extend(_linked_markdown_sources(root, index, category))
+
+    sources.extend(_existing_paths(root, (REFERENCE_DOD, REFERENCE_TESTING)))
+    if _security_relevant(paths):
+        sources.extend(_existing_paths(root, (REFERENCE_SECURITY,)))
+    return sources
+
+
+def quality_review_artifact_entry(task_dir: Path, repo_root: Path) -> dict:
+    """Return the task-local quality-review artifact context entry."""
+    task_path = _repo_relative_task_path(task_dir, repo_root)
+    return {
+        "file": f"{task_path}/{QUALITY_REVIEW_FILE}",
+        "reason": "Task-local quality review evidence required before complete",
+    }
+
+
+def _categories_for(dev_type: str) -> tuple[str, ...]:
+    if dev_type == "backend":
+        return ("backend",)
+    if dev_type == "frontend":
+        return ("frontend",)
+    if dev_type == "fullstack":
+        return ("backend", "frontend")
+    return ()
+
+
+def _linked_markdown_sources(
+    repo_root: Path,
+    index_path: str,
+    category: str,
+) -> list[str]:
+    index = repo_root / index_path
+    if not index.is_file():
+        return []
+    try:
+        text = index.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+
+    sources: list[str] = []
+    for match in _MARKDOWN_LINK_RE.finditer(text):
+        target = match.group(1).strip()
+        if "://" in target or target.startswith("#"):
+            continue
+        normalized = _normalize_markdown_target(category, target)
+        if normalized is not None:
+            sources.extend(_existing_paths(repo_root, (normalized,)))
+    return sources
+
+
+def _normalize_markdown_target(category: str, target: str) -> str | None:
+    without_anchor = target.split("#", 1)[0].strip()
+    if not without_anchor.endswith(".md"):
+        return None
+    if without_anchor.startswith("./"):
+        without_anchor = without_anchor[2:]
+    if without_anchor.startswith("../") or without_anchor.startswith("/"):
+        return None
+    return f"{SPEC_ROOT}/{category}/{without_anchor}"
+
+
+def _existing_paths(repo_root: Path, paths: tuple[str, ...]) -> list[str]:
+    return [path for path in paths if (repo_root / path).is_file()]
+
+
+def _security_relevant(paths: tuple[str, ...]) -> bool:
+    return any(_SECURITY_HINT_RE.search(path) is not None for path in paths)
+
+
+def _quality_source_reason(source: str) -> str:
+    if source == REFERENCE_DOD:
+        return "Verify Definition of Done evidence"
+    if source == REFERENCE_TESTING:
+        return "Verify test depth and anti-shallow-test coverage"
+    if source == REFERENCE_SECURITY:
+        return "Verify security-sensitive changes"
+    return f"Verify {Path(source).name} quality rules"
+
+
+def _repo_relative_task_path(task_dir: Path, repo_root: Path) -> str:
+    try:
+        return Path(task_dir).resolve().relative_to(Path(repo_root).resolve()).as_posix()
+    except ValueError:
+        return Path(task_dir).as_posix()

package/template/.cowork-flow/scripts/common/gates/gates.py

@@ -25,6 +25,7 @@ STAGE_GATES = {
         "test_intent",
         "runtime_rules",
         "coding_standards",
+        "quality_machine_checks",
         "complexity",
     ),
     "task_complete": (
@@ -33,12 +34,14 @@ STAGE_GATES = {
         "test_intent",
         "runtime_rules",
         "coding_standards",
+        "quality_machine_checks",
+        "quality_review",
         "complexity",
     ),
 }
 
 
-def _validator_bindings() -> tuple[ValidatorBinding, ...]:
+def _core_validator_bindings() -> tuple[ValidatorBinding, ...]:
     return (
         ValidatorBinding(
             key="runtime_rules",
@@ -73,6 +76,30 @@ def _validator_bindings() -> tuple[ValidatorBinding, ...]:
             function="validate_coding_standards",
             positional=("repo_root", "task_dir"),
         ),
+    )
+
+
+def _quality_validator_bindings() -> tuple[ValidatorBinding, ...]:
+    return (
+        ValidatorBinding(
+            key="quality_machine_checks",
+            module="validate_coding_standards",
+            function="validate_machine_checks",
+            positional=("repo_root", "task_dir"),
+        ),
+        ValidatorBinding(
+            key="quality_review",
+            module="quality_review",
+            function="validate_quality_review",
+            positional=("repo_root", "task_dir"),
+        ),
+    )
+
+
+def _validator_bindings() -> tuple[ValidatorBinding, ...]:
+    return (
+        *_core_validator_bindings(),
+        *_quality_validator_bindings(),
         ValidatorBinding(
             key="complexity",
             module="validate_coding_standards",
@@ -82,7 +109,7 @@ def _validator_bindings() -> tuple[ValidatorBinding, ...]:
     )
 
 
-def _gate_definitions() -> tuple[GateDefinition, ...]:
+def _core_gate_definitions() -> tuple[GateDefinition, ...]:
     return (
         GateDefinition(
             id="runtime_rules",
@@ -117,6 +144,31 @@ def _gate_definitions() -> tuple[GateDefinition, ...]:
             required=True,
             block_message="Coding standards gate blocked lifecycle transition",
         ),
+    )
+
+
+def _quality_gate_definitions() -> tuple[GateDefinition, ...]:
+    return (
+        GateDefinition(
+            id="quality_machine_checks",
+            validator_key="quality_machine_checks",
+            required=False,
+            block_message="",
+            warning_message="Quality machine-check warnings",
+        ),
+        GateDefinition(
+            id="quality_review",
+            validator_key="quality_review",
+            required=True,
+            block_message="Quality review gate blocked lifecycle transition",
+        ),
+    )
+
+
+def _gate_definitions() -> tuple[GateDefinition, ...]:
+    return (
+        *_core_gate_definitions(),
+        *_quality_gate_definitions(),
         GateDefinition(
             id="complexity",
             validator_key="complexity",