codedeck 0.5.2 → 0.5.3

package/dist/plugin/skills/tlc-spec-driven/scripts/validate_state.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""
+validate_state.py - deterministic completion gate for a feature.
+
+The skill's strongest invariant is "the Verifier is always-on, never prompted;
+Execute is not done until validation.md reports PASS." That is prose the model
+must remember. This turns it into a checkable pass/fail the closing step runs
+automatically, so declaring a feature done without a real Verifier report fails
+loudly instead of slipping through.
+
+It does NOT merely check that validation.md exists - a report that exists but is
+empty, still holds the template placeholder, or has no evidence would pass a
+shallow existence check while proving nothing. This gate requires a real,
+filled verdict plus at least one file:line evidence citation.
+
+Operates only on the .specs/ markdown artifacts (stack- and tool-agnostic). No
+dependencies. Run from the project root (the dir that contains .specs), or pass
+--root. Meant to be invoked by the skill as the closing gate of Execute, the
+same way lessons.py is invoked at distillation - not a manual step.
+
+Usage:
+  python3 <skill-dir>/scripts/validate_state.py [feature]
+  python3 <skill-dir>/scripts/validate_state.py
+
+  Invoke from the skill directory that ships this script (not the project root).
+  Pass --root when cwd is not the project that contains .specs/.
+
+Exit codes: 0 ok, 1 a completed feature is missing a real PASS report,
+            2 usage error.
+"""
+
+import argparse
+import os
+import re
+import sys
+
+def _feature_dirs(root):
+    base = os.path.join(root, ".specs", "features")
+    if not os.path.isdir(base):
+        return base, []
+    dirs = [
+        d for d in sorted(os.listdir(base))
+        if os.path.isdir(os.path.join(base, d))
+    ]
+    return base, dirs
+
+
+def _verdict(text):
+    """Return 'pass', 'fail', 'unfilled', or None from a validation report."""
+    # Look at the '## Validation' heading first, then a '**Result**' line.
+    lines = text.splitlines()
+    candidates = [
+        ln for ln in lines
+        if re.search(r"^#{1,4}\s*validation\b", ln.strip(), re.IGNORECASE)
+        or re.search(r"\*{0,2}result\*{0,2}\s*:", ln.strip(), re.IGNORECASE)
+    ]
+    hay = " ".join(candidates) if candidates else text
+    has_pass = re.search(r"\bPASS\b", hay) is not None
+    has_fail = re.search(r"\bFAIL\b", hay) is not None
+    if has_pass and has_fail:
+        # Both present on the verdict line = unfilled template "[PASS | FAIL]".
+        return "unfilled"
+    if has_pass:
+        return "pass"
+    if has_fail:
+        return "fail"
+    return None
+
+
+def _appears_complete(fdir):
+    """Conservative completeness heuristic for the cross-check mode.
+
+    A feature 'appears complete' if it already has a validation.md, or if it has
+    a tasks.md with at least one task and no unchecked '- [ ]' boxes left. When
+    the signal is ambiguous (no tasks.md, Tasks phase skipped), returns False so
+    an in-flight feature is never falsely flagged.
+    """
+    if os.path.exists(os.path.join(fdir, "validation.md")):
+        return True
+    tasks = os.path.join(fdir, "tasks.md")
+    if not os.path.exists(tasks):
+        return False
+    # tasks is built from the root-scoped feature directory.
+    with open(tasks, encoding="utf-8", errors="replace") as f:  # NOSONAR
+        body = f.read()
+    if not re.search(r"^#{2,4}\s+T\d+\s*:", body, re.MULTILINE):
+        return False
+    if re.search(r"^\s*-\s*\[\s\]", body, re.MULTILINE):
+        return False  # unchecked box remains -> still in progress
+    return True
+
+
+def _check_feature(fdir, name):
+    """Return list of error strings for one feature (empty = pass)."""
+    errors = []
+    vpath = os.path.join(fdir, "validation.md")
+    if not os.path.exists(vpath):
+        errors.append(
+            f"{name}: no validation.md - Execute is not done until the Verifier "
+            f"writes it (author != verifier). Dispatch validation before marking done."
+        )
+        return errors
+    # vpath is built from the root-scoped feature directory.
+    with open(vpath, encoding="utf-8", errors="replace") as f:  # NOSONAR
+        text = f.read()
+    verdict = _verdict(text)
+    if verdict is None:
+        errors.append(f"{name}: validation.md has no PASS/FAIL verdict (a prose-only report does not count)")
+    elif verdict == "unfilled":
+        errors.append(f"{name}: validation.md verdict is still the template placeholder '[PASS | FAIL]' - not filled")
+    elif verdict == "fail":
+        errors.append(f"{name}: validation.md verdict is FAIL - route the ranked gaps to fix tasks, then re-verify (feature is not done)")
+    if verdict == "pass" and not has_evidence(text):
+        errors.append(f"{name}: validation.md is PASS but cites no file:line evidence - evidence-or-zero not satisfied")
+    return errors
+
+
+def has_evidence(text):
+    for raw in text.split():
+        token = raw.strip(chr(96) + "|()[]{}<>,.;")
+        path_part, separator, line = token.rpartition(":")
+        if not separator or not line.isdigit():
+            continue
+        _, extension_separator, extension = path_part.rpartition(".")
+        if extension_separator and extension.isalnum():
+            return True
+    return False
+
+
+def _safe_path(candidate, root):
+    root = os.path.realpath(root)
+    candidate = os.path.realpath(os.path.abspath(candidate))
+    try:
+        inside = os.path.commonpath((root, candidate)) == root
+    except ValueError:
+        inside = False
+    if not inside:
+        raise ValueError(f"feature is outside project root: {candidate}")
+    return candidate
+
+
+def _resolve(root, feature):
+    base, dirs = _feature_dirs(root)
+    if not os.path.isdir(base):
+        print(f"validate_state: no {base} directory - nothing to check.")
+        return []
+    if feature:
+        feature_path = os.path.realpath(os.path.abspath(feature))
+        if os.path.isdir(feature_path):
+            fdir = _safe_path(feature_path, root)
+        else:
+            if os.path.isabs(feature) or os.path.basename(feature) != feature:
+                raise ValueError("feature is outside project root or does not name a feature")
+            fdir = _safe_path(os.path.join(base, feature), root)
+        if not os.path.isdir(fdir):
+            print(f"validate_state: feature not found: {feature}", file=sys.stderr)
+            raise SystemExit(2)
+        return [(fdir, os.path.basename(fdir.rstrip("/")))]
+    if len(dirs) == 1:
+        return [(os.path.join(base, dirs[0]), dirs[0])]
+    if not dirs:
+        print("validate_state: no features under .specs/features/ - nothing to check.")
+        return []
+    # Cross-check mode: only features that appear complete.
+    picked = [(os.path.join(base, d), d) for d in dirs if _appears_complete(os.path.join(base, d))]
+    if not picked:
+        print("validate_state: no completed feature detected (all in progress) - nothing to gate.")
+    return picked
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="validate_state.py", description="Deterministic completion gate: a done feature must have a real PASS validation report.")
+    p.add_argument("feature", nargs="?", default=None, help="Feature dir or name (default: sole feature, else cross-check all completed)")
+    p.add_argument("--root", default=".", help="Project root containing .specs/ (default: current dir)")
+    args = p.parse_args(argv)
+    root = os.path.abspath(args.root)
+
+    try:
+        targets = _resolve(root, args.feature)
+    except ValueError as exc:
+        print(f"validate_state: {exc}", file=sys.stderr)
+        return 2
+    all_errors = []
+    for fdir, name in targets:
+        all_errors += _check_feature(fdir, name)
+
+    for e in all_errors:
+        print(f"  ERROR {e}")
+    n = len(all_errors)
+    checked = ", ".join(name for _, name in targets) or "(none)"
+    print(f"\nvalidate_state: {n} error(s) across [{checked}]")
+    return 1 if n else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/plugin/skills/tlc-spec-driven/scripts/validate_tasks.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""
+validate_tasks.py - deterministic pre-approval checks for a feature tasks.md.
+
+Turns the three pre-approval checks (task granularity, diagram-vs-definition
+cross-check, test co-location) into a checkable pass/fail run BEFORE tasks are
+presented for approval, instead of trusting the model to build the tables by
+hand. Pure standard library, zero dependencies. Operates only on the tasks.md
+markdown artifact, so it is stack-agnostic and tool-agnostic.
+
+What it checks (heuristic markdown inspection, not a full parser):
+  ERROR  - a required section is missing
+  ERROR  - a task is missing its `Tests` or `Gate` field
+  ERROR  - a task depends on a task in a LATER phase (dependencies point back only)
+  ERROR  - a dependency edge shown in the diagram has no matching `Depends on`
+           (and vice-versa) when both sides are parseable
+  WARN   - a task's `Where` names multiple files (granularity smell -> split it)
+  WARN   - a task says `Tests: none` (confirm the coverage matrix agrees)
+  WARN   - the diagram could not be parsed confidently (cross-check skipped)
+
+Usage:
+  python3 <skill-dir>/scripts/validate_tasks.py [target] [--root DIR] [--strict]
+
+  Invoke from the skill directory that ships this script (not the project root).
+  target    Path to a tasks.md, a feature directory, or a project root.
+            Omitted -> auto-detect the single feature under <root>/.specs/features/.
+  --root    Project root that contains .specs/ (default: current dir).
+  --strict  Treat warnings as errors.
+
+Exit codes: 0 pass, 1 errors found (or warnings under --strict), 2 usage error.
+"""
+
+import argparse
+import os
+import re
+import sys
+
+REQUIRED_SECTIONS = ["Test Coverage Matrix", "Gate Check Commands", "Execution Plan", "Task Breakdown"]
+TASK_RE = re.compile(r"^#{2,4}\s+(T\d+)\s*:", re.IGNORECASE)
+EDGE_RE = re.compile(r"\bT\d+\b")
+
+
+def _safe_path(candidate, root):
+    root = os.path.realpath(root)
+    candidate = os.path.realpath(os.path.abspath(candidate))
+    try:
+        inside = os.path.commonpath((root, candidate)) == root
+    except ValueError:
+        inside = False
+    if not inside:
+        raise ValueError(f"target is outside project root: {candidate}")
+    return candidate
+
+
+def resolve_tasks(target, root):
+    root = os.path.realpath(root)
+    if target:
+        target_path = os.path.realpath(os.path.abspath(target))
+        if os.path.isfile(target_path):
+            return _safe_path(target_path, root)
+        if os.path.isdir(target_path):
+            target_path = _safe_path(target_path, root)
+            cand = os.path.join(target_path, "tasks.md")
+            if os.path.isfile(cand):
+                return cand
+            return _autodetect(target_path)
+        if os.path.isabs(target) or os.path.basename(target) != target:
+            raise ValueError("target is outside project root or does not name a feature")
+        # Not a path: treat as a feature name under <root>/.specs/features/<name>/
+        cand = os.path.join(root, ".specs", "features", target, "tasks.md")
+        if os.path.isfile(cand):
+            return _safe_path(cand, root)
+        return None
+    return _autodetect(root)
+
+
+def _autodetect(root):
+    base = os.path.join(root, ".specs", "features")
+    if not os.path.isdir(base):
+        return None
+    features = [d for d in sorted(os.listdir(base)) if os.path.isfile(os.path.join(base, d, "tasks.md"))]
+    if len(features) == 1:
+        return os.path.join(base, features[0], "tasks.md")
+    if len(features) == 0:
+        return None
+    raise SystemExit(
+        "validate_tasks: multiple features found; pass one explicitly:\n  "
+        + "\n  ".join(os.path.join(base, f, "tasks.md") for f in features)
+    )
+
+
+def section_present(lines, name):
+    return any(re.match(r"^#{1,4}\s+" + re.escape(name) + r"\b", ln.strip()) for ln in lines)
+
+
+def field_value(line, name):
+    match = re.match(r"^\*{0,2}" + re.escape(name) + r"\*{0,2}\s*:", line, re.IGNORECASE)
+    return line[match.end():].strip() if match else None
+
+
+def file_hints(text):
+    hints = []
+    for raw in text.split():
+        token = raw.strip(chr(96) + ".,;:()[]{}")
+        token = token.split(":", 1)[0]
+        stem, separator, extension = token.rpartition(".")
+        if separator and stem and 1 <= len(extension) <= 6 and extension.isalnum():
+            hints.append(token)
+    return hints
+
+
+def parse_tasks(lines):
+    """Return a dict: task_id -> {'deps': set, 'tests': str|None, 'gate': str|None, 'where': str}."""
+    tasks = {}
+    current = None
+    for ln in lines:
+        m = TASK_RE.match(ln.strip())
+        if m:
+            current = m.group(1).upper()
+            tasks[current] = {"deps": set(), "tests": None, "gate": None, "where": ""}
+            continue
+        if current is None:
+            continue
+        stripped = ln.strip()
+        body = field_value(stripped, "Depends on")
+        if body is not None:
+            if "none" not in body.lower():
+                for e in EDGE_RE.findall(body.upper()):
+                    tasks[current]["deps"].add(e)
+        value = field_value(stripped, "Where")
+        if value is not None:
+            tasks[current]["where"] = value
+        value = field_value(stripped, "Tests")
+        if value is not None:
+            tasks[current]["tests"] = value
+        value = field_value(stripped, "Gate")
+        if value is not None:
+            tasks[current]["gate"] = value
+    return tasks
+
+
+def parse_phase_membership(lines):
+    """Map task_id -> phase index, read from '### Phase N' headers in the Execution Plan."""
+    membership = {}
+    phase_idx = 0
+    in_phase = False
+    for ln in lines:
+        pm = re.match(r"^#{2,4}\s+Phase\s+(\d+)", ln.strip(), re.IGNORECASE)
+        if pm:
+            phase_idx = int(pm.group(1))
+            in_phase = True
+            continue
+        if in_phase:
+            # Map a task to a phase ONLY when it appears as a task header (### Tn:),
+            # never when it is merely referenced (e.g. in a `Depends on:` line or a
+            # diagram arrow), which would misattribute the referenced task to this phase.
+            hm = TASK_RE.match(ln.strip())
+            if hm:
+                membership[hm.group(1).upper()] = phase_idx
+    return membership
+
+
+def parse_diagram_edges(lines):
+    """Best-effort: parse 'Tx -> Ty' / 'Tx → Ty' arrow chains from fenced blocks.
+    Returns (edges:set[(src,dst)], parsed:bool)."""
+    edges = set()
+    in_fence = False
+    found_any_arrow = False
+    for ln in lines:
+        if ln.strip().startswith("```"):
+            in_fence = not in_fence
+            continue
+        if not in_fence:
+            continue
+        # normalize arrow glyphs
+        norm = ln.replace("→", "->").replace("──", "-").replace("-", "-")
+        if "->" not in norm:
+            continue
+        chain = EDGE_RE.findall(norm.upper())
+        # only treat as a chain if arrows connect them left-to-right
+        segments = [s for s in re.split(r"->", norm)]
+        seq = []
+        for seg in segments:
+            ids = EDGE_RE.findall(seg.upper())
+            seq.append(ids[-1] if ids else None)
+        for a, b in zip(seq, seq[1:]):
+            if a and b:
+                edges.add((a, b))
+                found_any_arrow = True
+    return edges, found_any_arrow
+
+
+def check(tasks_path):
+    # resolve_tasks confines the canonical path to the project root.
+    with open(tasks_path, "r", encoding="utf-8") as f:  # NOSONAR
+        lines = f.read().splitlines()
+    errors, warnings = [], []
+
+    for name in REQUIRED_SECTIONS:
+        if not section_present(lines, name):
+            errors.append(f"missing required section: ## {name}")
+
+    tasks = parse_tasks(lines)
+    if not tasks:
+        warnings.append("no tasks (### T1: ...) parsed - is this file filled in?")
+        return errors, warnings
+
+    # Field presence + granularity smell.
+    for tid, t in tasks.items():
+        if t["tests"] is None:
+            errors.append(f"{tid}: missing `Tests` field")
+        elif t["tests"].lower().startswith("none"):
+            warnings.append(f"{tid}: Tests: none - confirm the Test Coverage Matrix says 'none' for this layer")
+        if t["gate"] is None:
+            errors.append(f"{tid}: missing `Gate` field")
+        files = file_hints(t["where"])
+        if len(set(files)) > 1:
+            warnings.append(f"{tid}: `Where` names multiple files {sorted(set(files))} - granularity smell, consider splitting")
+
+    # Forward-phase dependency.
+    membership = parse_phase_membership(lines)
+    for tid, t in tasks.items():
+        p_here = membership.get(tid)
+        if p_here is None:
+            continue
+        for dep in t["deps"]:
+            p_dep = membership.get(dep)
+            if p_dep is not None and p_dep > p_here:
+                errors.append(f"{tid} (phase {p_here}) depends on {dep} (phase {p_dep}) - dependencies must point backward or within the same phase")
+
+    # Diagram vs definition cross-check (best effort).
+    edges, parsed = parse_diagram_edges(lines)
+    if not parsed:
+        warnings.append("diagram arrows not parsed confidently - diagram/definition cross-check skipped (verify by hand)")
+    else:
+        def intra_phase(a, b):
+            # Parity applies only within a phase. A backward cross-phase dependency
+            # is validated by the forward-phase check above and needs no diagram arrow;
+            # phase diagrams are drawn per phase, so cross-phase edges are out of scope here.
+            pa, pb = membership.get(a), membership.get(b)
+            if pa is None or pb is None:
+                return True  # unknown phase -> keep best-effort parity
+            return pa == pb
+
+        dep_edges = set()
+        for tid, t in tasks.items():
+            for dep in t["deps"]:
+                dep_edges.add((dep, tid))  # arrow points dep -> task
+        only_in_diagram = {(a, b) for (a, b) in (edges - dep_edges) if intra_phase(a, b)}
+        only_in_defs = {(a, b) for (a, b) in (dep_edges - edges) if intra_phase(a, b)}
+        for a, b in sorted(only_in_diagram):
+            if a in tasks and b in tasks:
+                errors.append(f"diagram shows {a} -> {b} but {b} has no matching `Depends on: {a}`")
+        for a, b in sorted(only_in_defs):
+            errors.append(f"{b} declares `Depends on: {a}` but the diagram has no {a} -> {b} arrow")
+
+    return errors, warnings
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="validate_tasks.py", description="Pre-approval checks for a feature tasks.md.")
+    p.add_argument("target", nargs="?", default=None)
+    p.add_argument("--root", default=".")
+    p.add_argument("--strict", action="store_true")
+    args = p.parse_args(argv)
+
+    try:
+        tasks_path = resolve_tasks(args.target, args.root)
+    except ValueError as exc:
+        print(f"validate_tasks: {exc}", file=sys.stderr)
+        return 2
+    if not tasks_path:
+        print("validate_tasks: could not locate a tasks.md. Pass a path or run from the project root.", file=sys.stderr)
+        return 2
+
+    errors, warnings = check(tasks_path)
+    for w in warnings:
+        print(f"  WARN  {w}")
+    for e in errors:
+        print(f"  ERROR {e}")
+    fail = errors or (warnings and args.strict)
+    print(f"\nvalidate_tasks: {len(errors)} error(s), {len(warnings)} warning(s) in {tasks_path}")
+    return 1 if fail else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/plugin/statusline.sh

@@ -253,7 +253,6 @@ const fields = [
   contextField(),
   tokenField(),
   runUsage ? runField() : localField(),
-  runUsage && paint(TEXT, String(Math.max(0, Math.round(runUsage.activeSessionCount))) + " agents"),
 ].filter(Boolean);
 
 writeSync(1, fields.join(paint(MUTED, " · ")));