cadence-skill-installer 0.2.8 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadence-skill-installer",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "Install the Cadence skill into supported AI tool skill directories.",
   "repository": "https://github.com/snowdamiz/cadence",
   "private": false,

package/skill/SKILL.md

@@ -37,24 +37,31 @@ description: Structured project operating system for end-to-end greenfield or br
 3. Scaffold initializes and persists `state.cadence-scripts-dir` for later subskill commands.
 4. If `.cadence` exists, skip scaffold.
 
-## Prerequisite Gate (Mandatory On First Turn)
-1. Invoke `skills/prerequisite-gate/SKILL.md`.
-2. Continue lifecycle and delivery execution only after prerequisite gate pass.
+## Workflow Route Gate (Mandatory Every Turn)
+1. After scaffold handling, run `python3 scripts/read-workflow-state.py` and parse the JSON response.
+2. Treat `next_item` and `route.skill_name` from that response as the authoritative workflow route.
+3. Do not invoke a state-changing subskill unless it matches `route.skill_name`.
+
+## Prerequisite Gate (Conditional)
+1. Invoke `skills/prerequisite-gate/SKILL.md` only when `route.skill_name` is `prerequisite-gate`.
+2. If `route.skill_name` is not `prerequisite-gate` (for example `ideator`), skip prerequisite gate and follow the active route instead.
 
 ## Progress / Resume Flow
 1. Invoke `skills/project-progress/SKILL.md` when the user asks to continue/resume or requests progress status (for example: "continue the project", "how far along are we?", "where did we leave off?").
 2. Use that skill's state-based routing result to continue from the correct next phase.
 
 ## Manual Subskill Safety Gate
-1. If the user manually requests a Cadence subskill, run `python3 scripts/assert-workflow-route.py --skill-name <subskill>` before executing it.
-2. If route assertion fails, stop and surface the exact script error.
-3. Do not execute state-changing subskill steps when assertion fails.
+1. If the user manually requests a Cadence subskill, first resolve `PROJECT_ROOT` with `python3 scripts/resolve-project-root.py`.
+2. Run `python3 scripts/assert-workflow-route.py --skill-name <subskill> --project-root "$PROJECT_ROOT"` before executing that subskill.
+3. If route assertion fails, stop and surface the exact script error.
+4. Do not execute state-changing subskill steps when assertion fails.
 
 ## Ideation Flow
-1. Do not switch to `skills/ideator/SKILL.md` inside this conversation.
-2. After scaffold and prerequisite gates pass for a net-new project, hand off to a fresh chat so context resets cleanly.
-3. Tell the user: `Start a new chat and either say "help me define my project" or share your project brief.`
-4. Stop here and wait for the user to continue in the new chat.
+1. When scaffold and prerequisite both complete in this same conversation for a net-new project, hand off to a fresh chat so context resets cleanly.
+2. Use this exact handoff line: `Start a new chat and either say "help me define my project" or share your project brief.`
+3. In subsequent conversations, if the workflow route is `ideator`, do not rerun prerequisite gate.
+4. If the user asks to define the project or provides a brief while route is `ideator`, invoke `skills/ideator/SKILL.md`.
+5. If route is `ideator` and the user has not provided ideation input yet, prompt with the same handoff line and wait.
 
 ## Ideation Update Flow
 1. If the user wants to modify or discuss existing ideation, invoke `skills/ideation-updater/SKILL.md`.

package/skill/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Cadence"
   short_description: "Lifecycle + delivery system for structured project execution"
-  default_prompt: "Use Cadence to guide this project from lifecycle setup through phased execution, traceability, audit, and milestone completion. Always read and apply the active SOUL persona from .cadence/SOUL.json (fallback: SOUL.json). Keep user-facing responses concise and outcome-focused, and never expose internal skill-routing or command-execution traces unless the user explicitly asks. If user intent indicates resuming/continuing work or asking progress, invoke skills/project-progress/SKILL.md first, report current phase, then route to the next step. If the user manually requests a Cadence subskill, run scripts/assert-workflow-route.py with that skill name first and block state-changing execution on mismatch. For net-new project starts, after scaffold and prerequisite gates pass, do not switch skills in-thread; tell the user: Start a new chat and either say \"help me define my project\" or share your project brief."
+  default_prompt: "Use Cadence to guide this project from lifecycle setup through phased execution, traceability, audit, and milestone completion. Always read and apply the active SOUL persona from .cadence/SOUL.json (fallback: SOUL.json). Keep user-facing responses concise and outcome-focused, and never expose internal skill-routing or command-execution traces unless the user explicitly asks. At the start of each Cadence turn, run scripts/check-project-repo-status.py, run scaffold only when .cadence is missing, then run scripts/read-workflow-state.py and treat route.skill_name as authoritative for the next state-changing skill. Invoke skills/prerequisite-gate/SKILL.md only when route.skill_name is prerequisite-gate. If route.skill_name is ideator, do not run prerequisite again. For net-new project starts where scaffold and prerequisite just completed in-thread, hand off with: Start a new chat and either say \"help me define my project\" or share your project brief. In later chats, if route.skill_name is ideator and the user asks to define the project or provides a brief, invoke skills/ideator/SKILL.md. If user intent indicates resuming/continuing work or asking progress, invoke skills/project-progress/SKILL.md first, report current phase, then route to the next step. If the user manually requests a Cadence subskill, resolve PROJECT_ROOT with scripts/resolve-project-root.py and then run scripts/assert-workflow-route.py --skill-name <subskill> --project-root \"$PROJECT_ROOT\" before any state-changing actions."

package/skill/scripts/assert-workflow-route.py

@@ -3,70 +3,81 @@
 
 from __future__ import annotations
 
+import argparse
 import copy
 import json
 import sys
 from pathlib import Path
 
+from project_root import resolve_project_root, write_project_root_hint
 from workflow_state import default_data, reconcile_workflow_state
 
 
-CADENCE_DIR = Path(".cadence")
-CADENCE_JSON_PATH = CADENCE_DIR / "cadence.json"
+SCRIPT_DIR = Path(__file__).resolve().parent
 
 
-def load_state() -> dict:
-    cadence_exists = CADENCE_DIR.exists()
+def load_state(project_root: Path, requested_skill: str) -> dict:
+    cadence_dir = project_root / ".cadence"
+    cadence_json_path = cadence_dir / "cadence.json"
+    cadence_exists = cadence_dir.exists()
 
-    if not CADENCE_JSON_PATH.exists():
+    if not cadence_json_path.exists():
+        if requested_skill != "scaffold":
+            print(
+                f"MISSING_CADENCE_STATE: project_root={project_root}",
+                file=sys.stderr,
+            )
+            raise SystemExit(2)
         data = default_data()
         return reconcile_workflow_state(data, cadence_dir_exists=cadence_exists)
 
     try:
-        with CADENCE_JSON_PATH.open("r", encoding="utf-8") as file:
+        with cadence_json_path.open("r", encoding="utf-8") as file:
             original_data = json.load(file)
     except json.JSONDecodeError as exc:
-        print(f"INVALID_CADENCE_JSON: {exc}", file=sys.stderr)
+        print(f"INVALID_CADENCE_JSON: {exc} path={cadence_json_path}", file=sys.stderr)
         raise SystemExit(1)
 
     return reconcile_workflow_state(copy.deepcopy(original_data), cadence_dir_exists=cadence_exists)
 
 
-def parse_args(argv: list[str]) -> tuple[str, bool]:
-    if not argv or len(argv) > 3:
-        print("Usage: assert-workflow-route.py --skill-name <name> [--allow-complete]", file=sys.stderr)
-        raise SystemExit(2)
-
-    skill_name = ""
-    allow_complete = False
-    idx = 0
-    while idx < len(argv):
-        token = argv[idx]
-        if token == "--skill-name":
-            if idx + 1 >= len(argv):
-                print("MISSING_SKILL_NAME", file=sys.stderr)
-                raise SystemExit(2)
-            skill_name = str(argv[idx + 1]).strip()
-            idx += 2
-            continue
-        if token == "--allow-complete":
-            allow_complete = True
-            idx += 1
-            continue
-
-        print(f"UNKNOWN_ARGUMENT: {token}", file=sys.stderr)
-        raise SystemExit(2)
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Assert that a requested Cadence skill matches the workflow route.",
+    )
+    parser.add_argument("--skill-name", required=True, help="Requested subskill name.")
+    parser.add_argument(
+        "--allow-complete",
+        action="store_true",
+        help="Allow success when workflow is already complete.",
+    )
+    parser.add_argument(
+        "--project-root",
+        default="",
+        help="Explicit project root path override.",
+    )
+    return parser.parse_args()
 
-    if not skill_name:
-        print("MISSING_SKILL_NAME", file=sys.stderr)
-        raise SystemExit(2)
 
-    return skill_name, allow_complete
+def main() -> int:
+    args = parse_args()
+    requested_skill = str(args.skill_name).strip()
+    allow_complete = bool(args.allow_complete)
+    explicit_project_root = args.project_root.strip() or None
 
+    try:
+        project_root, root_source = resolve_project_root(
+            script_dir=SCRIPT_DIR,
+            explicit_project_root=explicit_project_root,
+            require_cadence=False,
+            allow_hint=True,
+        )
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
 
-def main() -> int:
-    requested_skill, allow_complete = parse_args(sys.argv[1:])
-    data = load_state()
+    write_project_root_hint(SCRIPT_DIR, project_root)
+    data = load_state(project_root, requested_skill)
 
     workflow = data.get("workflow", {})
     next_item = workflow.get("next_item", {})
@@ -87,7 +98,8 @@ def main() -> int:
                 "WORKFLOW_ROUTE_MISMATCH: "
                 f"expected={expected} "
                 f"requested={requested_skill} "
-                f"next_item={next_item_id}"
+                f"next_item={next_item_id} "
+                f"project_root={project_root}"
             ),
             file=sys.stderr,
         )
@@ -102,6 +114,8 @@ def main() -> int:
                 "next_item_id": next_item_id,
                 "next_item_title": next_item_title,
                 "workflow_complete": next_item_id == "complete",
+                "project_root": str(project_root),
+                "project_root_source": root_source,
             }
         )
     )

package/skill/scripts/check-project-repo-status.py

@@ -11,11 +11,13 @@ import sys
 from pathlib import Path
 from typing import Any
 
+from project_root import write_project_root_hint
 from workflow_state import default_data, reconcile_workflow_state
 
 
 CADENCE_DIR = Path(".cadence")
 CADENCE_JSON_PATH = CADENCE_DIR / "cadence.json"
+SCRIPT_DIR = Path(__file__).resolve().parent
 
 
 def run_command(command: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
@@ -140,6 +142,7 @@ def ensure_default_state(data: dict[str, Any]) -> dict[str, Any]:
 def main() -> int:
     args = parse_args()
     project_root = Path(args.project_root).resolve()
+    write_project_root_hint(SCRIPT_DIR, project_root)
 
     repo_status = detect_git_repo(project_root)
     cadence_exists = (project_root / CADENCE_JSON_PATH).exists()

package/skill/scripts/handle-prerequisite-state.py

@@ -1,49 +1,80 @@
 #!/usr/bin/env python3
 """Read or update prerequisite pass state in .cadence/cadence.json."""
 
+import argparse
 import json
-import sys
 from pathlib import Path
 
+from project_root import resolve_project_root, write_project_root_hint
 from workflow_state import default_data, reconcile_workflow_state
 
 
-CADENCE_JSON_PATH = Path(".cadence") / "cadence.json"
+SCRIPT_DIR = Path(__file__).resolve().parent
 
 
-def load_data():
-    if not CADENCE_JSON_PATH.exists():
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Read or update prerequisites-pass in cadence.json.",
+    )
+    parser.add_argument(
+        "pass_state",
+        nargs="?",
+        choices=("0", "1"),
+        help="Set prerequisites-pass to 0 or 1. Omit to read current value.",
+    )
+    parser.add_argument(
+        "--project-root",
+        default="",
+        help="Explicit project root path override.",
+    )
+    return parser.parse_args()
+
+
+def cadence_json_path(project_root: Path) -> Path:
+    return project_root / ".cadence" / "cadence.json"
+
+
+def load_data(project_root: Path):
+    state_path = cadence_json_path(project_root)
+    if not state_path.exists():
         return default_data()
-    with CADENCE_JSON_PATH.open("r", encoding="utf-8") as file:
+    with state_path.open("r", encoding="utf-8") as file:
         data = json.load(file)
-    return reconcile_workflow_state(data, cadence_dir_exists=CADENCE_JSON_PATH.parent.exists())
+    return reconcile_workflow_state(data, cadence_dir_exists=state_path.parent.exists())
 
 
-def save_data(data):
-    CADENCE_JSON_PATH.parent.mkdir(parents=True, exist_ok=True)
-    with CADENCE_JSON_PATH.open("w", encoding="utf-8") as file:
+def save_data(project_root: Path, data):
+    state_path = cadence_json_path(project_root)
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    with state_path.open("w", encoding="utf-8") as file:
         json.dump(data, file, indent=4)
         file.write("\n")
 
 
 def main():
-    if len(sys.argv) > 2:
-        print("Usage: handle-prerequisite-state.py [0|1]", file=sys.stderr)
-        return 2
-
-    if len(sys.argv) == 2 and sys.argv[1] not in {"0", "1"}:
-        print("Usage: handle-prerequisite-state.py [0|1]", file=sys.stderr)
-        return 2
-
-    data = load_data()
-
-    if len(sys.argv) == 1:
+    args = parse_args()
+    explicit_project_root = args.project_root.strip() or None
+    try:
+        project_root, _ = resolve_project_root(
+            script_dir=SCRIPT_DIR,
+            explicit_project_root=explicit_project_root,
+            require_cadence=False,
+            allow_hint=True,
+        )
+    except ValueError as exc:
+        print(str(exc))
+        return 1
+
+    write_project_root_hint(SCRIPT_DIR, project_root)
+    data = load_data(project_root)
+
+    if args.pass_state is None:
         print("true" if bool(data.get("prerequisites-pass", False)) else "false")
         return 0
 
-    data["prerequisites-pass"] = sys.argv[1] == "1"
-    data = reconcile_workflow_state(data, cadence_dir_exists=CADENCE_JSON_PATH.parent.exists())
-    save_data(data)
+    data["prerequisites-pass"] = args.pass_state == "1"
+    data = reconcile_workflow_state(data, cadence_dir_exists=cadence_json_path(project_root).parent.exists())
+    save_data(project_root, data)
     print("true" if data["prerequisites-pass"] else "false")
     return 0
 

package/skill/scripts/init-cadence-scripts-dir.py

@@ -1,43 +1,79 @@
 #!/usr/bin/env python3
 """Persist Cadence helper scripts directory in .cadence/cadence.json."""
 
+import argparse
 import json
 from pathlib import Path
 
+from project_root import resolve_project_root, write_project_root_hint
 from workflow_state import default_data, reconcile_workflow_state
 
 
-CADENCE_DIR = Path(".cadence")
-CADENCE_JSON_PATH = CADENCE_DIR / "cadence.json"
+SCRIPT_DIR = Path(__file__).resolve().parent
 
 
-def load_data():
-    if not CADENCE_JSON_PATH.exists():
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Persist cadence-scripts-dir in a project cadence.json.",
+    )
+    parser.add_argument(
+        "--project-root",
+        default="",
+        help="Explicit project root path override.",
+    )
+    return parser.parse_args()
+
+
+def cadence_paths(project_root: Path) -> tuple[Path, Path]:
+    cadence_dir = project_root / ".cadence"
+    cadence_json_path = cadence_dir / "cadence.json"
+    return cadence_dir, cadence_json_path
+
+
+def load_data(project_root: Path):
+    cadence_dir, cadence_json_path = cadence_paths(project_root)
+    if not cadence_json_path.exists():
         return default_data()
-    with CADENCE_JSON_PATH.open("r", encoding="utf-8") as file:
+    with cadence_json_path.open("r", encoding="utf-8") as file:
         data = json.load(file)
-    return reconcile_workflow_state(data, cadence_dir_exists=CADENCE_DIR.exists())
+    return reconcile_workflow_state(data, cadence_dir_exists=cadence_dir.exists())
 
 
-def save_data(data):
-    CADENCE_DIR.mkdir(parents=True, exist_ok=True)
-    with CADENCE_JSON_PATH.open("w", encoding="utf-8") as file:
+def save_data(project_root: Path, data):
+    cadence_dir, cadence_json_path = cadence_paths(project_root)
+    cadence_dir.mkdir(parents=True, exist_ok=True)
+    with cadence_json_path.open("w", encoding="utf-8") as file:
         json.dump(data, file, indent=4)
         file.write("\n")
 
 
 def main():
-    if not CADENCE_DIR.exists():
+    args = parse_args()
+    explicit_project_root = args.project_root.strip() or None
+    try:
+        project_root, _ = resolve_project_root(
+            script_dir=SCRIPT_DIR,
+            explicit_project_root=explicit_project_root,
+            require_cadence=False,
+            allow_hint=True,
+        )
+    except ValueError as exc:
+        print(str(exc))
+        return 1
+
+    cadence_dir, _ = cadence_paths(project_root)
+    if not cadence_dir.exists():
         print("MISSING_CADENCE_DIR")
         return 1
 
-    scripts_dir = str(Path(__file__).resolve().parent)
+    scripts_dir = str(SCRIPT_DIR)
 
-    data = load_data()
+    data = load_data(project_root)
     state = data.setdefault("state", {})
     state["cadence-scripts-dir"] = scripts_dir
-    data = reconcile_workflow_state(data, cadence_dir_exists=CADENCE_DIR.exists())
-    save_data(data)
+    data = reconcile_workflow_state(data, cadence_dir_exists=cadence_dir.exists())
+    save_data(project_root, data)
+    write_project_root_hint(SCRIPT_DIR, project_root)
 
     print(json.dumps({"status": "ok", "cadence_scripts_dir": scripts_dir}))
     return 0

package/skill/scripts/project_root.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Project-root resolution and persistence helpers for Cadence scripts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+PROJECT_ROOT_HINT_FILE = ".last-project-root"
+
+
+def hint_file_path(script_dir: Path) -> Path:
+    return script_dir / PROJECT_ROOT_HINT_FILE
+
+
+def write_project_root_hint(script_dir: Path, project_root: Path) -> None:
+    """Best-effort write of the most recent Cadence project root."""
+    try:
+        hint_path = hint_file_path(script_dir)
+        hint_path.write_text(f"{project_root.resolve()}\n", encoding="utf-8")
+    except OSError:
+        # Hint persistence is convenience only; never fail gate scripts for this.
+        return
+
+
+def read_project_root_hint(script_dir: Path) -> Path | None:
+    hint_path = hint_file_path(script_dir)
+    try:
+        raw = hint_path.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+
+    if not raw:
+        return None
+
+    candidate = Path(raw).expanduser().resolve()
+    if (candidate / ".cadence").is_dir():
+        return candidate
+    return None
+
+
+def find_cadence_project_root(start: Path) -> Path | None:
+    current = start.resolve()
+    for candidate in [current, *current.parents]:
+        if (candidate / ".cadence").is_dir():
+            return candidate
+    return None
+
+
+def resolve_project_root(
+    *,
+    script_dir: Path,
+    explicit_project_root: str | None = None,
+    require_cadence: bool = False,
+    allow_hint: bool = True,
+) -> tuple[Path, str]:
+    """Resolve the active project root.
+
+    Resolution order:
+    1) Explicit `--project-root`
+    2) Nearest ancestor of cwd containing `.cadence`
+    3) Most recent persisted hint (if enabled)
+    4) cwd fallback
+    """
+
+    source = "cwd"
+    if explicit_project_root:
+        project_root = Path(explicit_project_root).expanduser().resolve()
+        source = "explicit"
+    else:
+        project_root = find_cadence_project_root(Path.cwd()) or Path.cwd().resolve()
+        if (project_root / ".cadence").is_dir():
+            source = "cwd"
+        elif allow_hint:
+            hinted_root = read_project_root_hint(script_dir)
+            if hinted_root is not None:
+                project_root = hinted_root
+                source = "hint"
+            else:
+                source = "cwd-fallback"
+        else:
+            source = "cwd-fallback"
+
+    if require_cadence and not (project_root / ".cadence").is_dir():
+        raise ValueError(f"MISSING_CADENCE_DIR: {project_root}")
+
+    if not project_root.exists():
+        raise ValueError(f"PROJECT_ROOT_NOT_FOUND: {project_root}")
+
+    if not project_root.is_dir():
+        raise ValueError(f"PROJECT_ROOT_NOT_DIRECTORY: {project_root}")
+
+    return project_root, source

package/skill/scripts/read-workflow-state.py

@@ -1,30 +1,50 @@
 #!/usr/bin/env python3
 """Read and normalize Cadence workflow state from .cadence/cadence.json."""
 
+import argparse
 import copy
 import json
 import sys
 from pathlib import Path
 
+from project_root import resolve_project_root, write_project_root_hint
 from workflow_state import default_data, reconcile_workflow_state
 
 
-CADENCE_DIR = Path(".cadence")
-CADENCE_JSON_PATH = CADENCE_DIR / "cadence.json"
+SCRIPT_DIR = Path(__file__).resolve().parent
 
 
-def load_state():
-    cadence_exists = CADENCE_DIR.exists()
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Read and normalize Cadence workflow state.",
+    )
+    parser.add_argument(
+        "--project-root",
+        default="",
+        help="Explicit project root path override.",
+    )
+    return parser.parse_args()
 
-    if not CADENCE_JSON_PATH.exists():
+
+def cadence_paths(project_root: Path) -> tuple[Path, Path]:
+    cadence_dir = project_root / ".cadence"
+    cadence_json_path = cadence_dir / "cadence.json"
+    return cadence_dir, cadence_json_path
+
+
+def load_state(project_root: Path):
+    cadence_dir, cadence_json_path = cadence_paths(project_root)
+    cadence_exists = cadence_dir.exists()
+
+    if not cadence_json_path.exists():
         data = default_data()
         data = reconcile_workflow_state(data, cadence_dir_exists=cadence_exists)
         if cadence_exists:
-            save_state(data)
+            save_state(project_root, data)
         return data
 
     try:
-        with CADENCE_JSON_PATH.open("r", encoding="utf-8") as file:
+        with cadence_json_path.open("r", encoding="utf-8") as file:
             original_data = json.load(file)
     except json.JSONDecodeError as exc:
         print(f"INVALID_CADENCE_JSON: {exc}", file=sys.stderr)
@@ -32,18 +52,19 @@ def load_state():
 
     data = reconcile_workflow_state(copy.deepcopy(original_data), cadence_dir_exists=cadence_exists)
     if data != original_data:
-        save_state(data)
+        save_state(project_root, data)
     return data
 
 
-def save_state(data):
-    CADENCE_DIR.mkdir(parents=True, exist_ok=True)
-    with CADENCE_JSON_PATH.open("w", encoding="utf-8") as file:
+def save_state(project_root: Path, data):
+    cadence_dir, cadence_json_path = cadence_paths(project_root)
+    cadence_dir.mkdir(parents=True, exist_ok=True)
+    with cadence_json_path.open("w", encoding="utf-8") as file:
         json.dump(data, file, indent=4)
         file.write("\n")
 
 
-def build_response(data):
+def build_response(data, project_root: Path, project_root_source: str):
     workflow = data.get("workflow", {})
     next_item = workflow.get("next_item", {})
     route = workflow.get("next_route", {"skill_name": "", "skill_path": "", "reason": ""})
@@ -69,12 +90,28 @@ def build_response(data):
         "next_phase": str(workflow.get("next_phase", next_item_id)),
         "route": route,
         "message": message,
+        "project_root": str(project_root),
+        "project_root_source": project_root_source,
     }
 
 
 def main():
-    data = load_state()
-    response = build_response(data)
+    args = parse_args()
+    explicit_project_root = args.project_root.strip() or None
+    try:
+        project_root, project_root_source = resolve_project_root(
+            script_dir=SCRIPT_DIR,
+            explicit_project_root=explicit_project_root,
+            require_cadence=False,
+            allow_hint=True,
+        )
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(1)
+
+    write_project_root_hint(SCRIPT_DIR, project_root)
+    data = load_state(project_root)
+    response = build_response(data, project_root, project_root_source)
     print(json.dumps(response))