trackfw 9.2.0 → 9.3.1

package/README.md

@@ -19,12 +19,12 @@ ADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned
 Every piece of work traces back to a decision. Every decision links to a requirement. Every requirement lands in a roadmap. No orphan work, no undocumented choices.
 
 > 🚧 **Platform support: Linux and macOS are supported. Windows support is partial.**
-> The CLIs install on Windows and core governance commands run — but the generated
-> guard hooks are POSIX shell scripts, and **on several agent CLIs they do not execute
-> on Windows.** They are written to disk and reported as installed while never running.
-> Native Windows hooks are planned, not yet in progress (tracked in
-> [REQ-2026-09-05](docs/req/REQ-2026-09-05-os-hooks-de-guard-nao-executam-no-windows-na-maioria-dos-clis-de-agente-e-o-validate-reporta-instalado.md)).
-> **Read [Windows support (partial)](#windows-support-partial) before adopting on Windows.**
+> The CLIs install on Windows and core governance commands run. Since v9.3.0, guard
+> hooks call `trackfw guard <name>` (the Go binary) instead of a POSIX shell script —
+> measured blocking and allowing correctly in PowerShell 5, cmd.exe, and Git Bash on
+> Windows; Claude Code and Codex CLI proven end-to-end. Windows CI still reports known
+> test failures. There are limits worth knowing; **read
+> [Windows support (partial)](#windows-support-partial) before adopting on Windows.**
 
 ---
 
@@ -112,14 +112,17 @@ declaration.
 
 Shared behavior follows the [command contract](docs/cli-parity.md).
 
-> **The CLI installs on Node ≥ 18 alone — the generated guard hooks do not run on
-> Node alone.** They are POSIX shell scripts and need a POSIX shell to execute. On
-> Windows, see [Windows support](#windows-support-partial) before relying on them.
+> **The npm package delivers the same Go binary, and the guard hooks run it from `PATH`.**
+> Since v9.3.0, hooks call `trackfw guard <name>` directly; no POSIX shell is needed. On
+> Windows, the npm shim is a `.ps1` that PowerShell's `ExecutionPolicy Restricted` blocks —
+> see [Windows support](#windows-support-partial) before relying on the hooks.
 
 ### Windows support (partial)
 
-🚧 **Windows support is partial. Native Windows hooks are planned but not yet being
-worked on. Read this before adopting `trackfw` on Windows.**
+🚧 **Windows support is partial. Read this before adopting `trackfw` on Windows.**
+
+Since v9.3.0, guard hooks call `trackfw guard <name>` (the Go binary) and run on
+Windows. Windows CI still reports known test failures mapped by root cause.
 
 We publish a Windows binary and the npm/pip packages install on Windows. That is not
 the same as the tool working end to end, and we would rather tell you where the edges
@@ -138,32 +141,79 @@ are than let you find them after adoption.
 
 - Our Windows CI still reports **known test failures**. They are mapped by root cause,
   not unknown — but they are not zero.
-**Guard hooks on Windows — measured, per agent CLI**
+**Guard hooks on Windows — measured state (since v9.3.0)**
+
+Since v9.3.0, guard hooks call `trackfw guard <name>` (the Go binary) instead of a
+`.sh` script. The same binary runs in every shell; for a given agent CLI, the hook
+line in the committed config is the same string across PowerShell, cmd.exe, and Git
+Bash — a team with mixed OS can commit one config and have it work on all machines.
 
-The guard hooks are `.sh` scripts, executed by *your* AI agent CLI. Which shell that CLI
-uses on Windows decides whether they run at all. We measured it:
+The hook line emitted depends on the shell the agent CLI uses on Windows — a fact of
+the vendor, not of the OS:
 
-| Agent CLI | Shell on Windows | Do the hooks run? | Basis |
+| Agent CLI | Shell on Windows | Hook line emitted | Basis |
 |---|---|---|---|
-| Gemini CLI | PowerShell, always | ❌ **No** | measured in vendor source |
-| Codex CLI | PowerShell on the normal path | ❌ **No** | measured in vendor source |
-| GitHub Copilot CLI | — | ❌ **No** — we populate the wrong config field | vendor docs + our code |
-| Claude Code | Git Bash if installed, else PowerShell | ⚠️ **Only with Git Bash** | vendor documentation |
-| Cursor · Kiro | unknown | ❓ **Unknown** | closed, undocumented |
-
-🔴 **This is the failure mode we care most about, because it is silent.** A guard that
-never executes still reports health over something it never inspected. On the CLIs marked
-❌, `trackfw validate` will tell you the hook is installed — and it will never fire.
-
-**Until native Windows hooks ship, do not rely on `credential_guard` or
-`git_branch_guard` as an enforced control on Windows.** Treat them as documentation of
-intent, not as enforcement.
-
-We are **not** going to answer this by requiring Git Bash: it would fix one CLI out of
-six and push the cost onto you. Windows hooks should run on Windows. Native hook
-generation is the direction — see
-[`docs/portabilidade/2026-09-05-contrato-de-execucao-de-hook-por-cli-de-agente-no-windows.md`](docs/portabilidade/2026-09-05-contrato-de-execucao-de-hook-por-cli-de-agente-no-windows.md)
-for the full measurement, per CLI, with the level of certainty of each row.
+| Claude Code | Git Bash (if installed), else PowerShell | `trackfw guard <name>; exit $LASTEXITCODE` | vendor docs (2026-10-04) |
+| Codex CLI | PowerShell | `trackfw guard <name>; exit $LASTEXITCODE` | vendor source (2026-10-04) |
+| Gemini CLI | PowerShell | `trackfw guard <name>; exit $LASTEXITCODE` | vendor source (2026-10-04) |
+| Cursor | PowerShell | `trackfw guard <name>; exit $LASTEXITCODE` | vendor bundle (2026-09-06) |
+| Windsurf | PowerShell | `trackfw guard <name>; exit $LASTEXITCODE` | vendor docs (2026-10-04) |
+| GitHub Copilot | PowerShell / cross-platform `command` field | `trackfw guard <name>; exit $LASTEXITCODE` | vendor docs (2026-10-04) |
+| Kiro | cmd.exe | `trackfw guard <name>` | vendor docs (2026-10-04) |
+| Amazon Q | cmd.exe | `trackfw guard <name>` | vendor source (2026-10-04) |
+
+The `; exit $LASTEXITCODE` suffix is required for PowerShell 5: without it, PowerShell
+converts exit 2 (deny) from the child process into exit 1, and 6 of 8 CLIs treat exit 1
+as a non-blocking error. cmd.exe and bash propagate the exit code directly; they do not
+need the suffix.
+
+**What was measured in the VM (Windows 11 ARM64, 2026-10-06):** PowerShell 5, cmd.exe,
+and Git Bash (non-login, explicit PATH to the branch binary) all block
+`git push origin main` (exit 2) and allow `ls` (exit 0) correctly. `pwsh` (PowerShell 7)
+was not installed on the VM — not measured. Subsequent testing with real agent CLIs on the
+same VM proved end-to-end blocking and allowing for two CLIs; the remaining CLIs have the
+hook line verified in each shell but were not run agent-to-end:
+
+| Agent CLI | End-to-end proven on Windows | Evidence |
+|---|---|---|
+| Claude Code | ✅ real agent — `git push` blocked by guard, `git status` allowed | Claude Code 2.1.292, 2026-10-07 (ML-5B) |
+| Codex CLI | ✅ real agent — `git push` blocked ("Blocked by hook" + guard REASON), `git status` allowed | Codex CLI 0.160.1, KG interactive session, 2026-10-07 (ML-5C) |
+| Cursor | Hook line measured in shell; agent not run end-to-end | — |
+| Windsurf | Hook line measured in shell; agent not run end-to-end | — |
+| Gemini CLI | Hook line measured in shell; agent not run end-to-end | — |
+| Kiro | Hook line measured in `cmd.exe`; agent not measured (no Windows ARM64 CLI; the IDE needs an AWS Builder ID account) | — |
+| GitHub Copilot | Not verified (no account) | — |
+| Amazon Q | Not verified (no account) | — |
+
+**Claude Code on Windows uses the PowerShell shell tool**, not Bash. The hook emitted by
+trackfw carries `matcher: "Bash|PowerShell"` so it fires on both macOS/Linux (where Claude
+Code names the tool `Bash`) and Windows (where it names it `PowerShell`). Run
+`trackfw update` to migrate existing configs that carry only `"Bash"` — it also handles the
+`.sh`-to-binary-hook migration.
+
+**Caveat — old trackfw binary in Git Bash's PATH:** Claude Code runs the hook command
+through Git Bash (login shell), whose login profile puts `~/bin` at the front of `PATH`.
+If an older trackfw binary (without the `guard` subcommand) lives in `~/bin`, the hook
+exits 1 ("unknown command") and fails open on most CLIs — remove or update that binary.
+Since v9.3.0, `trackfw validate` reports this condition.
+
+**The guard requires a `trackfw` binary with the `guard` subcommand in the PATH of the
+agent CLI's process.** `trackfw validate` now reports three new conditions:
+
+- **Old binary in PATH** (no `guard` subcommand — exits 1 with "unknown command"):
+  fail-open on 6 of 8 CLIs. Claude Code, Codex, Gemini, Cursor, Windsurf, and Amazon Q
+  treat exit 2 as the only blocking exit — exit 1 passes through. Kiro and Copilot
+  block any non-zero exit, so they block for the wrong reason (deny-all until updated).
+  `trackfw validate` reports a violation when the binary in PATH does not support
+  `guard`. **Caveat:** if Git Bash resolves a different binary (e.g. one installed in
+  `~/bin` that is absent from the Windows PATH), the probe does not see it — that
+  binary's version is not checked.
+- **npm channel under `ExecutionPolicy Restricted`**: the `.ps1` shim is blocked by
+  PowerShell; validate reports a violation and recommends
+  `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.
+- **`trackfw.exe`, `trackfw.cmd`, or `trackfw.bat` in the project root**: cmd.exe (used
+  by Kiro and Amazon Q) searches the current directory before PATH — validate reports a
+  violation for each file found.
 
 **If you are on Windows**, we want your report. The Windows defects fixed so far came
 from a user running the tool on real Windows 11 and measuring before reporting — open

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "9.2.0",
+  "version": "9.3.1",
   "description": "Governance CLI for AI-native software delivery and AI coding agents. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, Amazon Q, OpenCode, and Kiro.",
   "keywords": [
     "cli",
@@ -63,11 +63,11 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@trackfw-bin/darwin-arm64": "9.2.0",
-    "@trackfw-bin/darwin-x64": "9.2.0",
-    "@trackfw-bin/linux-arm64": "9.2.0",
-    "@trackfw-bin/linux-x64": "9.2.0",
-    "@trackfw-bin/win32-arm64": "9.2.0",
-    "@trackfw-bin/win32-x64": "9.2.0"
+    "@trackfw-bin/darwin-arm64": "9.3.1",
+    "@trackfw-bin/darwin-x64": "9.3.1",
+    "@trackfw-bin/linux-arm64": "9.3.1",
+    "@trackfw-bin/linux-x64": "9.3.1",
+    "@trackfw-bin/win32-arm64": "9.3.1",
+    "@trackfw-bin/win32-x64": "9.3.1"
   }
 }