refactoring

Co-authored-by: Koru Agent <agent@coru.dev>

Author: tom-sapletta-com

.gitignore

@@ -1,5 +1,6 @@
 # Byte-compiled / optimized / DLL files
 .idea/cli2wup.iml
+.intent/
 .idea/dsl2wup.iml
 .idea/mcp2wup.iml
 .idea/nlp2wup.iml

CHANGELOG.md

@@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **Continuous todo2code Intent-vs-Reality monitoring.** The opt-in
+  `intent_monitoring` section runs deterministic or LLM-backed audits on
+  startup, periodically and after debounced file changes. Findings enter the
+  normal WUP health/event/Planfile stream as `<project>:intent`, and both the
+  todo2code CLI and its Python SDK bridge are supported.
 - **Pluggable endpoint-discovery adapters (`wup/discovery.py`).** `deps.json` is
   now built by per-ecosystem adapters — FastAPI, Flask, Django, NestJS, Express,
   Fastify, Hono, Go (gin/echo/net-http) and OpenAPI/Swagger — selected by repo
@@ -59,6 +64,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   always writing `app/src/routes`. This fixes `No valid paths to watch` on
   projects whose code lives under a different top-level folder (e.g. a monorepo
   module using `services/`).
+- `wup watch .` now detects source directories inside immediate project
+  subfolders (for example `api/src` and `worker/services`) through
+  `wup/config.py::detect_watch_paths`. Existing older auto-generated configs
+  whose `app/src/routes` paths do not exist fall back through
+  `wup/core.py::WupWatcher.build_watched_paths` instead of exiting with
+  `No valid paths to watch`; regression coverage lives in
+  `tests/test_multi_project.py`.
 
 - **Simultaneous multi-project watching.** `wup watch` now accepts several
   project directories and watches them at once in a single process
@@ -1554,4 +1566,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Update .idea/.gitignore
 - Update drug/__init__.py
 - Update drug/core.py
-

README.md

@@ -113,6 +113,13 @@ wup testql-endpoints /path/to/scenarios --output testql-deps.json
 Pass several project roots to watch them all at once in a single process. Each
 project keeps its own `wup.yaml`, dependency map, file observer and test queue.
 
+When the current directory is a workspace containing projects in immediate
+subfolders, plain `wup watch .` auto-detects their common source directories,
+for example `api/src`, `worker/services` and `frontend/app`. This also repairs
+the runtime behaviour of older auto-generated configs that still point only to
+missing root-level `app`, `src` and `routes` directories. The config file is not
+rewritten by this fallback.
+
 ```bash
 # Watch several projects at the same time
 wup watch ./service-a ./service-b ./service-c
@@ -132,6 +139,50 @@ path is resolved per project, so each project uses its own `deps.json`.
 > The live `--dashboard` and single `--config` options apply to single-project
 > runs only; when watching multiple projects each uses its own `wup.yaml`.
 
+### Continuous Intent Monitoring with todo2code
+
+WUP can run todo2code on startup, periodically and after debounced source-file
+changes. Diagnostics are projected into the regular service-health stream as
+`<project>:intent`: blocking findings produce `down`, review-required findings
+produce `degraded`, and a clean audit produces `up`.
+
+The integration is opt-in and deterministic by default, so merely installing
+WUP never starts paid LLM requests:
+
+```yaml
+intent_monitoring:
+  enabled: true
+  runner: cli
+  command:
+    - node
+    - /path/to/todo2code/dist/src/cli.js
+  interval_s: 300
+  debounce_s: 10
+  run_on_start: true
+  run_on_change: true
+  mode: deterministic
+  task_file: TASK.md
+  todo_file: TODO.md
+  changelog_file: CHANGELOG.md
+  docs:
+    - README.md
+    - docs/**/*.md
+  output_dir: .wup/intent
+  fail_severities:
+    - blocking
+    - review_required
+```
+
+Set `runner: python` to use the dependency-free `todo2code-sdk` bridge. Install
+it from todo2code's `sdk/python` directory and set `cli_path` to the built
+`dist/src/cli.js`. The Python package still delegates semantic processing to
+the canonical Node/TypeScript runtime.
+
+`mode: prefer-llm` or `mode: require-llm` enables LLM enrichment for NL and
+TODO/CHANGELOG. Documentation and final-summary LLM calls remain separately
+controlled by `docs_llm` and `summary_llm`. Use these modes deliberately: an
+audit may run after every debounce interval and therefore incur provider cost.
+
 ### Initialize Configuration
 
 ```bash
@@ -250,6 +301,8 @@ The generated `wup.yaml` includes:
 - **Metadata header**: Version, generation date, documentation links
 - **Dependencies info**: WUP version and optional wupbro dashboard
 - **Quick start guide**: Common commands to get started
+- **Detected watch paths**: Existing common source directories at the project
+  root and one level below it
 
 Example `wup.yaml`:
 

app.doql.events.pb

@@ -0,0 +1,208 @@
+"""Tests for continuous todo2code Intent-vs-Reality monitoring."""
+
+from __future__ import annotations
+
+import json
+import sys
+import types
+from pathlib import Path
+from types import SimpleNamespace
+
+from wup.config import load_config, save_config
+from wup.intent_monitor import IntentAuditResult, Todo2CodeIntentMonitor
+from wup.models.config import IntentMonitoringConfig, ProjectConfig, WupConfig
+from wup.testql_watcher import TestQLWatcher
+
+
+def _diagnostics(tmp_path: Path, items: list[dict]) -> Path:
+    path = tmp_path / "diagnostics.json"
+    path.write_text(json.dumps({"diagnostics": items}), encoding="utf-8")
+    return path
+
+
+def test_config_round_trip_preserves_intent_monitoring(tmp_path: Path) -> None:
+    config = WupConfig(
+        project=ProjectConfig(name="demo"),
+        intent_monitoring=IntentMonitoringConfig(
+            enabled=True,
+            runner="python",
+            cli_path="/opt/todo2code/dist/src/cli.js",
+            interval_s=120,
+            mode="require-llm",
+            docs_llm=True,
+            fail_codes=["PLANNED_NOT_IMPLEMENTED"],
+        ),
+    )
+    save_config(config, tmp_path / "wup.yaml")
+
+    loaded = load_config(tmp_path)
+
+    assert loaded.intent_monitoring.enabled is True
+    assert loaded.intent_monitoring.runner == "python"
+    assert loaded.intent_monitoring.interval_s == 120
+    assert loaded.intent_monitoring.mode == "require-llm"
+    assert loaded.intent_monitoring.docs_llm is True
+    assert loaded.intent_monitoring.fail_codes == ["PLANNED_NOT_IMPLEMENTED"]
+
+
+def test_cli_monitor_maps_blocking_diagnostics_to_down(tmp_path: Path, monkeypatch) -> None:
+    path = _diagnostics(
+        tmp_path,
+        [{"severity": "blocking", "code": "PLANNED_NOT_IMPLEMENTED"}],
+    )
+    calls = []
+
+    def fake_run(command, **kwargs):
+        calls.append((command, kwargs))
+        payload = {"diagnosticsPath": str(path), "runDirectory": str(tmp_path / "run")}
+        return SimpleNamespace(returncode=0, stdout=json.dumps(payload), stderr="")
+
+    monkeypatch.setattr("wup.intent_monitor.subprocess.run", fake_run)
+    results = []
+    config = IntentMonitoringConfig(
+        enabled=True,
+        command=["node", "/opt/todo2code/cli.js"],
+        mode="deterministic",
+    )
+    monitor = Todo2CodeIntentMonitor(tmp_path, config, results.append)
+
+    result = monitor.run_once()
+
+    assert result.status == "down"
+    assert len(result.diagnostics) == 1
+    assert results == [result]
+    command, kwargs = calls[0]
+    assert command[:3] == ["node", "/opt/todo2code/cli.js", "pipeline"]
+    assert "--no-docs-llm" in command
+    assert "--no-summary-llm" in command
+    assert kwargs.get("shell", False) is False
+
+
+def test_cli_monitor_resolves_single_javascript_launcher(tmp_path: Path, monkeypatch) -> None:
+    path = _diagnostics(tmp_path, [])
+    cli_path = tmp_path / "cli.js"
+    cli_path.write_text("", encoding="utf-8")
+    observed = {}
+
+    monkeypatch.setattr("wup.intent_monitor.shutil.which", lambda command: str(cli_path))
+
+    def fake_run(command, **kwargs):
+        observed["command"] = command
+        return SimpleNamespace(
+            returncode=0,
+            stdout=json.dumps({"diagnosticsPath": str(path)}),
+            stderr="",
+        )
+
+    monkeypatch.setattr("wup.intent_monitor.subprocess.run", fake_run)
+    monitor = Todo2CodeIntentMonitor(
+        tmp_path,
+        IntentMonitoringConfig(enabled=True, command=["t2c"]),
+        lambda result: None,
+    )
+
+    result = monitor.run_once()
+
+    assert result.status == "up"
+    assert observed["command"][:2] == ["node", str(cli_path.resolve())]
+
+
+def test_monitor_filters_codes_and_maps_review_required_to_degraded(tmp_path: Path) -> None:
+    path = _diagnostics(
+        tmp_path,
+        [
+            {"severity": "review_required", "code": "CHANGELOG_WITHOUT_IMPLEMENTATION"},
+            {"severity": "blocking", "code": "UNRELATED"},
+        ],
+    )
+    config = IntentMonitoringConfig(
+        fail_codes=["CHANGELOG_WITHOUT_IMPLEMENTATION"]
+    )
+    monitor = Todo2CodeIntentMonitor(tmp_path, config, lambda result: None)
+
+    result = monitor._result_from_payload({"diagnosticsPath": str(path)})
+
+    assert result.status == "degraded"
+    assert [item["code"] for item in result.diagnostics] == [
+        "CHANGELOG_WITHOUT_IMPLEMENTATION"
+    ]
+
+
+def test_monitor_reports_runner_failure_as_down(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setattr(
+        "wup.intent_monitor.subprocess.run",
+        lambda *args, **kwargs: SimpleNamespace(
+            returncode=2, stdout="", stderr="structured output invalid"
+        ),
+    )
+    results = []
+    monitor = Todo2CodeIntentMonitor(
+        tmp_path, IntentMonitoringConfig(enabled=True), results.append
+    )
+
+    result = monitor.run_once()
+
+    assert result.status == "down"
+    assert "structured output invalid" in result.message
+    assert results == [result]
+
+
+def test_python_runner_uses_todo2code_sdk_bridge(tmp_path: Path, monkeypatch) -> None:
+    path = _diagnostics(tmp_path, [])
+    observed = {}
+
+    class FakeRuntime:
+        def __init__(self, root, **kwargs):
+            observed["root"] = root
+            observed["init"] = kwargs
+
+        def invoke(self, arguments):
+            observed["arguments"] = arguments
+            payload = {"diagnosticsPath": str(path), "runDirectory": "python-run"}
+            return SimpleNamespace(stdout=json.dumps(payload))
+
+    module = types.ModuleType("todo2code")
+    module.TypeScriptRuntime = FakeRuntime
+    monkeypatch.setitem(sys.modules, "todo2code", module)
+    config = IntentMonitoringConfig(
+        enabled=True,
+        runner="python",
+        cli_path="/opt/todo2code/dist/src/cli.js",
+        mode="prefer-llm",
+        docs_llm=True,
+    )
+    monitor = Todo2CodeIntentMonitor(tmp_path, config, lambda result: None)
+
+    result = monitor.run_once()
+
+    assert result.status == "up"
+    assert observed["root"] == tmp_path.resolve()
+    assert observed["init"]["cli_path"] == config.cli_path
+    assert observed["arguments"][:2] == ["pipeline", str(tmp_path.resolve())]
+    assert observed["arguments"][observed["arguments"].index("--markdown-mode") + 1] == "prefer-llm"
+    assert "--no-docs-llm" not in observed["arguments"]
+    assert "--no-communication" in observed["arguments"]
+
+
+def test_testql_watcher_projects_intent_result_as_project_health() -> None:
+    watcher = object.__new__(TestQLWatcher)
+    watcher.config = SimpleNamespace(project=SimpleNamespace(name="workspace"))
+    transitions = []
+    watcher._record_health_transition = lambda **values: transitions.append(values)
+    result = IntentAuditResult(
+        status="down",
+        message="todo2code found 3 intent issue(s), 1 blocking",
+        diagnostics_path="/tmp/diagnostics.json",
+    )
+
+    watcher._record_intent_audit(result)
+
+    assert transitions == [
+        {
+            "service": "workspace:intent",
+            "status": "down",
+            "stage": "intent",
+            "message": result.message,
+            "track_file": result.diagnostics_path,
+        }
+    ]

tests/test_intent_monitor.py

@@ -58,6 +58,29 @@ def test_detect_watch_paths_backend_frontend(tmp_path: Path) -> None:
     assert "app/**" not in paths
 
 
+def test_detect_watch_paths_finds_source_dirs_in_project_subfolders(
+    tmp_path: Path,
+) -> None:
+    (tmp_path / "api" / "src").mkdir(parents=True)
+    (tmp_path / "worker" / "services").mkdir(parents=True)
+
+    assert detect_watch_paths(tmp_path) == ["api/src/**", "worker/services/**"]
+
+
+def test_detect_watch_paths_combines_root_and_project_subfolders(tmp_path: Path) -> None:
+    (tmp_path / "src").mkdir()
+    (tmp_path / "worker" / "src").mkdir(parents=True)
+
+    assert detect_watch_paths(tmp_path) == ["src/**", "worker/src/**"]
+
+
+def test_detect_watch_paths_skips_nested_vendor_and_hidden_dirs(tmp_path: Path) -> None:
+    (tmp_path / "node_modules" / "package" / "src").mkdir(parents=True)
+    (tmp_path / ".cache" / "src").mkdir(parents=True)
+
+    assert detect_watch_paths(tmp_path) == ["app/**", "src/**", "routes/**"]
+
+
 def test_default_config_watches_only_real_dirs(tmp_path: Path) -> None:
     (tmp_path / "services").mkdir()
     cfg = get_default_config(tmp_path)
@@ -122,6 +145,25 @@ def test_prepare_observer_none_when_no_valid_paths(tmp_path: Path) -> None:
     assert watcher.prepare_observer() is None
 
 
+def test_watcher_falls_back_to_source_dirs_in_project_subfolders(
+    tmp_path: Path,
+) -> None:
+    nested_src = tmp_path / "api" / "src"
+    nested_services = tmp_path / "worker" / "services"
+    nested_src.mkdir(parents=True)
+    nested_services.mkdir(parents=True)
+    watcher = _watcher(tmp_path, paths=["app/**", "src/**", "routes/**"])
+
+    assert watcher.build_watched_paths() == [str(nested_src), str(nested_services)]
+
+
+def test_watcher_does_not_replace_invalid_custom_paths(tmp_path: Path) -> None:
+    (tmp_path / "src").mkdir()
+    watcher = _watcher(tmp_path, paths=["misspelled-source/**"])
+
+    assert watcher.build_watched_paths() == []
+
+
 def test_multi_watcher_returns_false_when_all_invalid(tmp_path: Path) -> None:
     w1 = _watcher(tmp_path, paths=["missing-a/**"])
     w2 = _watcher(tmp_path, paths=["missing-b/**"])