Metadata-Version: 2.1
Name: trackfw
Version: 11.2.5
Summary: Governance CLI for AI-native software delivery
Home-page: https://github.com/kgsaran/trackfw
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# trackfw

> AI governance CLI for software delivery teams — ADR → REQ → ROADMAP → backlog / wip / blocked / done / abandoned

[![Release](https://img.shields.io/github/v/release/kgsaran/trackfw)](https://github.com/kgsaran/trackfw/releases/latest)
[![Go](https://img.shields.io/badge/go-1.25+-00ADD8?logo=go)](go.mod)
[![npm](https://img.shields.io/npm/v/trackfw?logo=npm&color=CB3837)](https://www.npmjs.com/package/trackfw)
[![PyPI](https://img.shields.io/pypi/v/trackfw?logo=python&color=3776AB)](https://pypi.org/project/trackfw/)
[![License](https://img.shields.io/github/license/kgsaran/trackfw)](LICENSE)

**trackfw** is an open-source governance CLI for AI-native software delivery. It enforces a traceable chain from architectural decision to shipped code — without SaaS, accounts, or databases. Markdown files are state.

It is designed for teams looking for an ADR / REQ / ROADMAP governance framework with native support for AI coding assistants such as Codex, Claude Code, Gemini CLI, Antigravity, OpenCode, Cursor, GitHub Copilot, Windsurf, Amazon Q, and Kiro.

```
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 binary installs 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. Guard and attention
> (`trackfw guard <name>`, `trackfw attention signal|cleanup`) are Go subcommands — no
> POSIX shell, `jq`, or `python3` required; native attention is available since v10.1.0.
> **Caveat:** Claude Code on Windows executes hooks through Git Bash (if installed) or
> PowerShell, locating bash at the hardcoded path `C:\Program Files\Git\bin\bash.exe`
> (overridable via `CLAUDE_CODE_GIT_BASH_PATH`). Git Bash path: measured on ARM64 VM
> (`docs/portabilidade/2026-10-04-trackfw-no-path-dos-shells-do-windows-por-canal.md:810`;
> `docs/portabilidade/2026-10-20-jornadas-agentes-windows.md` A7). PowerShell fallback:
> vendor docs only (`docs/portabilidade/2026-09-05-contrato-de-execucao-de-hook-por-cli-de-agente-no-windows.md`);
> a machine without Git installed has not been measured. **Measured 2026-10-21 (Windows ARM64, Claude Code
> 2.1.304):** guard allowed and denied by real PreToolUse events on Bash and PowerShell
> tools; attention appeared with the question and cleared after the response in an
> interactive session — only Claude Code was measured end-to-end in this round. Windows
> CI still reports known test failures. There are limits worth knowing; **read
> [Windows support (partial)](#windows-support-partial) before adopting on Windows.**

---

## The problem

Most teams accumulate technical debt not because they lack tools, but because they lack **governance traceability**. Decisions are made in Slack. Requirements live in someone's head. Roadmaps drift from what was actually shipped.

- **ADR tools** manage decision records, but don't connect them to delivery.
- **Kanban tools** track tasks, but don't enforce that tasks are backed by a decision.
- **CI tools** validate code, but don't validate governance.
- **AI coding assistants** generate code at unprecedented speed, but without traceability: who decided what? Why? Which requirement authorized this roadmap?

trackfw adds the governance layer that makes AI-assisted delivery auditable.

trackfw closes the loop — connective tissue between *why*, *what*, and *when*.

---

## Demo

![trackfw demo](docs/demo.gif)

```bash
$ trackfw req new "Login screen"

  ? Describe what you want to build  Login screen for the application
  ? Motivation                       Users need to authenticate to access the system

  Detected domains: authentication, ui

  ? How will users authenticate?
  > Local login (email + password)
    SSO (Google, Azure AD, Okta...)
    Not decided yet  ← generates ADR draft

  ? Is there an existing UI framework or design system?
    Yes, already chosen
  > No, need to choose a UI framework  ← generates ADR draft

ADR drafts created:
  → ADR-2026-06-12-authentication-strategy.md
  → ADR-2026-06-12-ui-framework.md

Resolve these ADRs (set Status: Accepted) before creating a roadmap.
created docs/req/REQ-2026-06-12-login-screen.md
```

---

## Installation

### macOS / Linux — curl

```bash
curl -sSfL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
```

### Homebrew

```bash
brew install kgsaran/trackfw/trackfw
```

### npm

```bash
npm install -g trackfw
```

From v8.0.0, the npm package is a ~80-line JavaScript shim that resolves
`@trackfw-bin/<platform>` at require() time (execution, not postinstall) and executes
the Go binary. **It is no longer pure Node.js — it contains a compiled binary.** The binary arrives through
the `npm` channel rather than as a separate download, so organisations whose policy
allows `npm install` but blocks direct executable downloads remain served.

If your policy forbids compiled binaries in any form regardless of channel, this
version is a breaking change for you. See [Changelog](CHANGELOG.md) for the full
declaration.

Shared behavior follows the [command contract](docs/cli-parity.md).

> **The npm package delivers the same Go binary, and guard and attention hooks run it from
> `PATH`.** Since v9.3.0, guard hooks call `trackfw guard <name>` directly; since v10.1.0,
> attention hooks call `trackfw attention signal|cleanup` — no POSIX shell, `jq`, or
> `python3` required. 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. 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
are than let you find them after adoption.

#### Installing on Windows

**npm:**

```bash
cmd /c npm install -g trackfw
```

In PowerShell with `ExecutionPolicy Restricted`, the `.ps1` shim is blocked by the
policy. Use `trackfw.cmd` instead, or run from `cmd.exe`.

**pip:**

```bash
pip install trackfw
```

**PowerShell installer (from the next release after v11.1.0):**

> **Note:** `install.ps1` is published as a release asset starting from the release
> after v11.1.0. It is not present in the v11.1.0 release.

```powershell
irm https://github.com/kgsaran/trackfw/releases/latest/download/install.ps1 | iex
```

Or download, read, then execute (recommended):

```powershell
Invoke-WebRequest -Uri https://github.com/kgsaran/trackfw/releases/latest/download/install.ps1 -OutFile install.ps1
# Review the script before running:
# notepad install.ps1
powershell -ExecutionPolicy Bypass -File install.ps1
```

The installer verifies the SHA-256 checksum before extracting, installs to
`%LOCALAPPDATA%\Programs\trackfw`, and adds that directory to the user `PATH` (preserving
`REG_EXPAND_SZ` entries). Environment variables honored before invoking:

| Variable | Default | Description |
|---|---|---|
| `TRACKFW_VERSION` | latest | Pin a version, e.g. `v11.1.0`. Must match `v?MAJOR.MINOR.PATCH[-rcN]`. |
| `TRACKFW_ARCH` | auto-detected | Override arch: `amd64` or `arm64` (case-sensitive). |
| `TRACKFW_INSTALL_DIR` | `%LOCALAPPDATA%\Programs\trackfw` | Absolute path (drive-qualified or UNC). |
| `TRACKFW_NO_MODIFY_PATH` | unset | Set to `1` to skip PATH modification. |

To reverse the PATH addition: open **System Properties → Environment Variables**, find
the user `PATH`, and remove the `trackfw` entry. (No uninstaller script is provided.)

**Git Bash / MSYS2 / Cygwin (shell installer):**

```bash
curl -fsSL https://github.com/kgsaran/trackfw/releases/latest/download/install.sh | sh
```

This installs the binary to `$HOME/bin`. Inside Git Bash (and MSYS2/Cygwin), `~/bin` is
on `PATH` automatically. In PowerShell and `cmd.exe` it is not — add `%USERPROFILE%\bin`
to your user `PATH` if you want to call `trackfw` from those shells.

The `install.sh` script also honours these environment variables:

| Variable | Default | Description |
|---|---|---|
| `TRACKFW_VERSION` | latest | Pin a version, e.g. `v11.1.0`. |
| `TRACKFW_ARCH` | auto-detected | Override arch: `amd64` or `arm64`. |
| `TRACKFW_INSTALL_DIR` | `$HOME/bin` (user) or `/usr/local/bin` (root) | Override install directory. |

**Tarball (manual):**

Download `trackfw_<version>_windows_amd64.tar.gz` or `windows_arm64.tar.gz` from the
[releases page](https://github.com/kgsaran/trackfw/releases). Extract `trackfw.exe`,
move it to a folder of your choice, and add that folder to your user `PATH`.

**Pitfall: more than one `trackfw` on `PATH`**

Measured during the 2026-10-21 Windows journey: Claude Code hooks run through Git Bash,
and the Git Bash login profile (`/etc/profile`) prepends `~/bin` (`%USERPROFILE%\bin`)
to `PATH` before other entries. If an older `trackfw` binary — one without the `guard`
subcommand — lives in `~/bin`, the hook finds it first, exits with "unknown command", and
causes every Bash tool call to be denied (fail-closed by construction). Check with:

```bash
where.exe trackfw          # in PowerShell or cmd.exe — shows Windows-registered PATH
type -a trackfw            # in Git Bash — also shows ~/bin entries
```

Keep a single copy. Since v10.1.0, `install.sh` lists every other `trackfw` binary it
finds on `PATH` after installing (it never executes them). On Git Bash, `~/bin` is
prepended to `PATH` by the login profile — this copy responds to hooks before any other
entry, even if you installed via npm or pip. See
[Pitfall: `~/bin` before PATH](#pitfall-more-than-one-trackfw-on-path) above.

**What we know works**

- All installation channels deliver the same Go binary: `npm install -g trackfw`,
  `pip install trackfw`, `curl … | sh` via `scripts/install.sh` on Git Bash / MSYS2 /
  Cygwin, the published `trackfw_<version>_windows_amd64.tar.gz` / `windows_arm64.tar.gz`,
  and `install.ps1` (from the release after v11.1.0). No separate Node.js or Python
  implementation since v8.0.0.
- Core governance commands — `req new`, `roadmap new`, `roadmap move`, `status`,
  `validate` — run, and artifacts are written with LF endings.
- **ARM64:** `windows_arm64` is published for npm (`@trackfw-bin/win32-arm64`), PyPI
  (`win_arm64` wheel), and the release tarball. Both npm and PyPI were executed on a
  Windows 11 ARM64 VM (2026-09-16, v8.0.0-rc2 artefacts). The guard and attention
  end-to-end journey on 2026-10-21 (Claude Code 2.1.304) also ran on Windows ARM64.
  Windows CI runs on x64 only — ARM64 is not covered by the CI matrix.

**What we know does not work yet**

- Our Windows CI still reports **known test failures**. They are mapped by root cause,
  not unknown — but they are not zero. Current list:
  `TestChecksum_StableAndMatchesSHA256Sum`, `TestFilenameUniqueness_DiretorioNaoLegivel_P2`,
  `TestFolderStatus_DiretorioNaoLegivel_P2`, `TestShip_Integration_GracefulDegradation_RealBinary`,
  `TestStaleWIPReportsWIPWalkError` (tracked in `.github/windows-known-failures.json`).
- `sh` is required for the `barrier` command — not available in PowerShell or cmd.exe without
  Git for Windows.
- File permissions set to `0600` via `os.Chmod` are accepted by Windows but have no enforcement.
- The PS/POSIX hook line run from `cmd.exe` exits 1 instead of 2 (passes through on 6 of 8
  CLIs) — documented as limitation; see [guard hooks](#guard-hooks-on-windows--measured-state-since-v930).
- `~/bin` in Git Bash's PATH precedes other PATH entries — an older binary there intercepts
  hooks before the one you installed. `install.ps1` warns when `%USERPROFILE%\bin\trackfw.exe`
  exists (without executing it); `install.sh` has warned since v11.1.0. See [Pitfall: more than one `trackfw` on `PATH`](#pitfall-more-than-one-trackfw-on-path).

**Support matrix — measured state (2026-10-29)**

Each cell: ✅ measured | ⚠️ not verified | — not applicable.

| Installation route | x64 | ARM64 | Source |
|---|---|---|---|
| `npm install -g trackfw` | ⚠️ | ✅ | x64: tested on `windows-latest` runner with local tarballs only (`windows-probe.yml`); registry install on a real x64 machine not verified. ARM64: `npm install --prefix … trackfw@11.1.0` from the registry, `trackfw.cmd version` → 11.1.0 on Windows 11 ARM64 VM (`docs/portabilidade/2026-10-28-install-ps1-vm-arm64.md`, 2026-10-29); earlier 9.2.0 global install (`docs/portabilidade/2026-10-04-trackfw-no-path-dos-shells-do-windows-por-canal.md`) |
| `pip install trackfw` | ⚠️ | ✅ | x64: not verified. ARM64: `pip install trackfw==11.1.0` in a venv from the registry, `trackfw.exe version` → 11.1.0 (`docs/portabilidade/2026-10-28-install-ps1-vm-arm64.md`, 2026-10-29); earlier 9.2.0 (`docs/portabilidade/2026-10-04-trackfw-no-path-dos-shells-do-windows-por-canal.md`) |
| `install.sh` (Git Bash) | ⚠️ | ✅ | ARM64: `TRACKFW_VERSION=v11.1.0`, checksum verified, binary PE machine `0xAA64`, `version` → 11.1.0 (`docs/portabilidade/2026-10-28-install-ps1-vm-arm64.md`, 2026-10-29). x64 is simulated only (`check-install-version-pin.sh`, scenario `mingw64-x64-sim`). MSYS2/Cygwin: not measured. |
| `install.ps1` | ✅ | ✅ | x64: PR #627, run 40846363727, job `windows-install-ps1`, 30 scenarios each under `powershell` (Edition Desktop, 5.1) and `pwsh` (Edition Core, 7), local fixture (asset ships from next release). ARM64: Windows PowerShell 5.1 on a Windows 11 ARM64 VM against the real v11.1.0 release — ARM64 detected, binary PE machine `0xAA64`, user PATH type preserved, idempotent re-run, `TRACKFW_NO_MODIFY_PATH=1` honoured, documented reversal checked (`docs/portabilidade/2026-10-28-install-ps1-vm-arm64.md`, 2026-10-29). |
| Tarball (manual) | ⚠️ | ✅ | ARM64: `trackfw_9.2.0_windows_arm64.tar.gz` extracted and binary executed on ARM64 VM (`docs/portabilidade/2026-10-04-trackfw-no-path-dos-shells-do-windows-por-canal.md`, 2026-10-04). x64: not verified. |

| Shell | Core commands | Guard hooks | Source |
|---|---|---|---|
| Git Bash | ✅ | ✅ | Core: `trackfw init` on ARM64 VM (`docs/portabilidade/2026-10-12-medicao-vm-windows-9.5.0.md`). Guard (current D12 form): ARM64 VM 2026-10-21, allow=0 deny=2 err=2 absent=2 (`docs/portabilidade/2026-10-21-guard-zsh-candidato-windows.md`); Claude Code 2.1.304 end-to-end (`docs/portabilidade/2026-10-20-jornadas-agentes-windows.md`). All ARM64. |
| PowerShell 5.1 | ✅ | ✅ | Core: `trackfw --version` and `trackfw attention signal/cleanup` measured on ARM64 VM (`docs/portabilidade/2026-10-04-trackfw-no-path-dos-shells-do-windows-por-canal.md`, `docs/portabilidade/2026-10-20-jornadas-agentes-windows.md`). Guard: ARM64 VM 2026-10-21 (`docs/portabilidade/2026-10-21-guard-zsh-candidato-windows.md`); also x64 CI run 40882950230 job `windows-full-suites`, `TestGuardLineShellMatrix/.../powershell/{RC0-allow,RC2-deny,RC1-deny-normalizado,absent}` 4 forms. |
| PowerShell 7 (`pwsh`) | ⚠️ | ✅ | Core: not verified. Guard: x64 CI run 40882950230 job `windows-full-suites`, `TestGuardLineShellMatrix/.../pwsh/{RC0-allow,RC2-deny,RC1-deny-normalizado,absent}` 4 forms; `pwsh` not installed on the ARM64 test VM. |
| cmd.exe | ✅ | ✅ | Core: `trackfw --version` via `cmd /c` and `trackfw attention signal/cleanup` on ARM64 VM (`docs/portabilidade/2026-10-04-trackfw-no-path-dos-shells-do-windows-por-canal.md`, `docs/portabilidade/2026-10-20-jornadas-agentes-windows.md`). Guard: cmd.exe form (`trackfw guard git-branch \|\| exit 2`) measured on ARM64 VM, exit 0/2/2/2/2 (`docs/portabilidade/2026-10-07-linha-de-hook-fail-closed-sem-trackfw.md:682-689`); same form generalizes to other hook names. PS/POSIX form exits 1 in cmd.exe (fail-open; same doc). x64 cmd.exe not measured. |

Windows CI matrix: **x64 only**. ARM64 CI is not currently run.

**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 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 | Hook line emitted (D12, v10.1.0) | Basis |
|---|---|---|---|
| Claude Code | Git Bash (if installed), else PowerShell | PS/POSIX form (see below) | Git Bash half: measured ARM64 VM (`docs/portabilidade/2026-10-04-trackfw-no-path-dos-shells-do-windows-por-canal.md:810`; hardcoded path `C:\Program Files\Git\bin\bash.exe` and env var override confirmed in `docs/portabilidade/2026-10-20-jornadas-agentes-windows.md` A7). PowerShell fallback: vendor docs only (`docs/portabilidade/2026-09-05-contrato-de-execucao-de-hook-por-cli-de-agente-no-windows.md`). |
| Codex CLI | PowerShell (prefers `pwsh` when installed) | PS/POSIX form | vendor source (2026-10-04) |
| Gemini CLI | PowerShell (prefers `pwsh` when installed) | PS/POSIX form | vendor source (2026-10-04) |
| Cursor | PowerShell | PS/POSIX form | vendor bundle (2026-09-06) |
| Windsurf | PowerShell | PS/POSIX form | vendor docs (2026-10-04) |
| GitHub Copilot | PowerShell / cross-platform `command` field | PS/POSIX form | vendor docs (2026-10-04) |
| Kiro | cmd.exe | cmd.exe form | vendor docs (2026-10-04) |
| Amazon Q | cmd.exe | cmd.exe form | vendor source (2026-10-04) |

The exact hook lines emitted by `trackfw init` and `trackfw update` since v10.1.0 (D12).
Copy these verbatim or run `trackfw init`/`trackfw update` — do not reconstruct them:

**PS/POSIX form** (Claude Code, Codex, Gemini, Cursor, Windsurf, Copilot — credential guard):

```
emulate -R sh 2>${null-/dev/null}; $LASTEXITCODE=2 2>${null-/dev/null}; trackfw guard credential; LASTEXITCODE=$((2*!!$?)); $LASTEXITCODE=2*!!$LASTEXITCODE 2>${null-/dev/null}; exit $LASTEXITCODE
```

**PS/POSIX form** (git-branch guard):

```
emulate -R sh 2>${null-/dev/null}; $LASTEXITCODE=2 2>${null-/dev/null}; trackfw guard git-branch; LASTEXITCODE=$((2*!!$?)); $LASTEXITCODE=2*!!$LASTEXITCODE 2>${null-/dev/null}; exit $LASTEXITCODE
```

**cmd.exe form** (Kiro, Amazon Q):

```
trackfw guard credential || exit 2
trackfw guard git-branch || exit 2
```

The D12 line (v10.1.0, issue #595) is **fail-closed** for both POSIX shells and PowerShell.
The leading `emulate -R sh 2>${null-/dev/null}` instructs zsh to run as POSIX sh — without
it, zsh's EQUALS/NOMATCH expansions abort the assignment `$LASTEXITCODE=2` with an error,
leaving the seed unset and allowing all exits. The seed `$LASTEXITCODE=2` is a PowerShell
assignment; in sh/bash the `=2: command not found` error is silently discarded. `LASTEXITCODE=$((2*!!$?))` normalizes any non-zero exit to 2 in sh/bash. The 4th segment
`$LASTEXITCODE=2*!!$LASTEXITCODE 2>${null-/dev/null}` provides the same normalization in
PowerShell, and is inert (CommandNotFound, stderr suppressed) in sh/bash. For cmd.exe:
`|| exit 2` is the native short-circuit.

**Under PowerShell**, a `deny` exit also emits two `CommandNotFound` error blocks to stderr
(one for `emulate`, one for the `$LASTEXITCODE=2*...` segment) alongside the guard's own
deny reason. The deny reason is preserved — it is the last line of stderr. Measure 2026-10-29
(CI run 40882950230, job `windows-full-suites`, `TestGuardLineShellMatrix`).

**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 Git Bash (if installed) as its shell tool**, falling back to
PowerShell when Git Bash is absent (Git Bash path measured on ARM64 VM:
`docs/portabilidade/2026-10-04-trackfw-no-path-dos-shells-do-windows-por-canal.md:810`
and `docs/portabilidade/2026-10-20-jornadas-agentes-windows.md` A7;
PowerShell fallback: vendor docs only,
`docs/portabilidade/2026-09-05-contrato-de-execucao-de-hook-por-cli-de-agente-no-windows.md`). The hook emitted by trackfw carries
`matcher: "Bash|PowerShell"` so it fires in both cases — on macOS/Linux (where the tool is
named `Bash`) and on Windows Git Bash and PowerShell alike. 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:** when Claude Code runs the hook through
Git Bash (login shell), the Git Bash login profile (`/etc/profile`) prepends `~/bin`
(`%USERPROFILE%\bin`) to `PATH`. If an older trackfw binary (without the `guard` subcommand)
lives in `~/bin`, the hook finds it first, 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
an issue with what you measured.

**Guard global directory when `HOME` ≠ `USERPROFILE`** (measured 2026-10-14): when Git Bash
sets `HOME` to a different directory than `USERPROFILE`, trackfw writes and audits the Claude
Code guard and global agents/skills under `USERPROFILE` — the directory Claude Code reads
(measured on Windows ARM64, Claude Code 2.1.299). If `CLAUDE_CONFIG_DIR` is set, trackfw uses
that directory instead (cross-platform). `trackfw validate` warns when the two paths diverge
(rule `home_divergence_windows`, informative only). Other CLIs (Codex, Gemini, Cursor,
Copilot, Kiro) continue under `HOME` until measured; Windsurf is not yet measured and is
flagged in the warning.

### pip

```bash
pip install trackfw
```

From v8.0.0, the pip package is a binary wheel in `gh-bin` format — **it contains
no Python files and no source**. The Go binary is installed into the PATH by pip.
`python -m trackfw` no longer works; use the `trackfw` executable directly.

Platforms not covered by the published wheels now fail at resolution time with
"no matching distribution found" — a clean failure instead of silently installing
the wrong thing. Eight wheels are published: `manylinux_2_17_x86_64`, `musllinux_1_2_x86_64`,
`manylinux_2_17_aarch64`, `musllinux_1_2_aarch64`, `macosx_10_9_x86_64`,
`macosx_11_0_arm64`, `win_amd64`, `win_arm64`. Linux publishes two wheels per
architecture (manylinux + musllinux), so Alpine and similar musl-based distributions
are covered.

Shared behavior follows the [command contract](docs/cli-parity.md).

---

## Quick start

```bash
# 1. Set up governance in your project (interactive wizard)
trackfw init

# 2. Document an architectural decision
trackfw adr new "Use PostgreSQL as primary database"

# 3. Create a requirement with linked roadmap — wizard detects domains and proposes ADR drafts
trackfw req new "User authentication"

# 4. Move the roadmap to work-in-progress
trackfw roadmap move user-authentication wip

# 5. Check governance health
trackfw validate

# 6. See what is in flight
trackfw status

# 7. Governed commit + push + open PR/MR (feat/fix/refactor branches only)
git add -p                        # stage your changes explicitly
trackfw ship -m "feat(auth): add login flow"
```

---

## Commands

| Command | Description |
|---|---|
| `trackfw init` | Interactive wizard — scaffolds governance + AI integrations |
| `trackfw update` | Update trackfw-managed artifacts (hooks, agents, skills) in the current project |
| `trackfw configure` | Interactive wizard to create/recreate `trackfw.yaml` |
| `trackfw adr new "title"` | Create a new Architecture Decision Record |
| `trackfw adr list` | List all ADRs with status |
| `trackfw req new "title"` | Create a REQ with guided ADR discovery |
| `trackfw req list` | List all REQs with status, discovered across flat, per-state, and by_agent layouts |
| `trackfw req move <name> <status>` | Update a REQ's status; physically relocates the file when it already lives in a recognized state subfolder (see [Multi-agent namespacing](#multi-agent-namespacing)) |
| `trackfw roadmap new "title"` | Create a roadmap in `backlog/` |
| `trackfw roadmap show <name>` | Print a roadmap with its current state |
| `trackfw roadmap move <name> <state>` | Move roadmap between states |
| `trackfw roadmap list` | List all roadmaps grouped by state |
| `trackfw validate` | Check governance consistency (use as CI gate) |
| `trackfw baseline` | Snapshot current violations to `.trackfw-baseline.json`; validate compares against it |
| `trackfw barrier <roadmap> --wave <n>` | Deterministic wave-release gate — stack-agnostic, checks MLs, acceptance evidence, project-declared gates, and governance |
| `trackfw branch new <type>/<slug>` | Create a governed feature branch — feat/fix/refactor require a matching REQ + roadmap already in `wip/` |
| `trackfw commit -m "msg"` | Commit staged changes, gated on governance for feat/fix/refactor branches |
| `trackfw push` | Governed `git push` for commits already created |
| `trackfw ship -m "msg"` | Governed `git commit + push + open PR/MR` — enforces branch pattern and governance gate; resolves forge (GitHub/GitLab/Bitbucket/Azure) automatically or via `--forge`; falls back to a browser URL when the forge CLI is absent |
| `trackfw release tag` | Create and publish an annotated release tag |
| `trackfw changelog [--since v<n>]` | Show entries from `CHANGELOG.md` |
| `trackfw context` | Print a structured summary of the project's governance state (REQs, Roadmaps, ADRs with counts and statuses) |
| `trackfw serve` | Start a local governance dashboard (no cloud, no accounts) |
| `trackfw status` | Show wip, blocked, REQs waiting on ADRs |
| `trackfw log [--tail N]` | Show roadmap state transition history |
| `trackfw metrics` | Delivery metrics derived from governance artifacts |
| `trackfw discover` | Scan the project and report governance artifacts not yet tracked |
| `trackfw sync` | Sync Open REQs to a project management tool |
| `trackfw note new "title"` | Create a knowledge note in `vault/notes/` |
| `trackfw doctor` | Detect artifacts on disk missing from the manifest |
| `trackfw audit-surface <ref>` | Report the executable surface of a git ref without checking it out |
| `trackfw guard credential` | Hook guard — blocks credential patterns in tool payloads |
| `trackfw guard git-branch` | Hook guard — blocks raw `git branch/commit/push` operations |
| `trackfw guard write-scope` | Hook guard — blocks writes to frozen paths |
| `trackfw attention` | Signal or clear a board attention banner (`trackfw serve`) |
| `trackfw agents list` | List available agents and deployment state across AI CLIs |
| `trackfw agents install` | Install selected specialist agents |
| `trackfw agents update` | Safely update managed agents |
| `trackfw agents uninstall` | Remove selected owned agent deployments |
| `trackfw skills list` | List available governance skills and deployment state |
| `trackfw skills install/update/uninstall` | Manage selected governance skills |
| `trackfw version` | Print version |
| `trackfw completion <shell>` | Generate shell completion script (bash, zsh, fish, powershell) |

The same lifecycle contract is available from the Go/Homebrew, npm, and PyPI
distributions.

---

## Governance chain

| Layer | Artifact | Purpose |
|---|---|---|
| Decide | `ADR` | Document the *why* behind a technical decision |
| Specify | `REQ` | Define *what* needs to be delivered, linked to an ADR |
| Plan | `ROADMAP` | Break the requirement into microbatches with acceptance criteria |
| Execute | `backlog → wip → done` | Folder position is the source of truth |

### Roadmap states

```
docs/roadmaps/
├── backlog/     queued, not started
├── wip/         actively being worked on (one at a time)
├── blocked/     waiting on a dependency or decision
├── done/        completed and validated
└── abandoned/   discontinued — reason required in file
```

Moving a file between folders **is** the state transition. No database, no API.

---

## AI-native governance

trackfw includes features designed for teams where AI agents are first-class contributors.

### Multi-agent namespacing

```yaml
# trackfw.yaml
roadmap_namespacing: by_agent
agents: [claude, gemini, copilot]
```

Artifacts are organized by agent: `docs/roadmaps/claude/wip/`, `docs/req/gemini/done/`. `trackfw validate` and `trackfw context` are fully by_agent-aware — no false positives.

REQs reuse this same `roadmap_namespacing` setting — there is no separate `req_namespacing` key. When
`by_agent` is configured, REQs may live under `req_dir/<agent>/<state>/` just like roadmaps do.

`trackfw req list` and `trackfw req move` discover REQs across three layouts at once (each is a fixed,
non-recursive glob — a REQ nested deeper than these patterns is not found), with no extra flag required:

- **Flat (legacy):** `req_dir/*.md` — REQs loose directly in the REQ directory.
- **Per-state:** `req_dir/<state>/*.md` — organized by state, without an agent segment.
- **By agent:** `req_dir/<agent>/<state>/*.md` — used when `roadmap_namespacing: by_agent` is set.

`trackfw req move <name> <status>` behaves conditionally depending on where the REQ currently lives:

- If the REQ already sits inside a recognized state subfolder (per-state or by_agent layout above), the
  move **physically relocates the file** to the target state's folder, mirroring `trackfw roadmap move` —
  the folder is the source of truth for state. In this mode `<status>` must be one of the six governance
  states (`backlog`, `analyzing`, `wip`, `blocked`, `done`, `abandoned`) — any other value is rejected
  with `invalid state`.
- If the REQ is loose in `req_dir/` (flat legacy layout), the move rewrites the `status:` frontmatter
  field **in place** and does not move or create any folder. `<status>` is written verbatim in this
  mode — it accepts the free-form values existing REQs already use (`Open`, `Done`, ...), not just the
  six governance state names. Existing flat REQs are never migrated automatically — you are not forced
  to reorganize a project's existing REQs to adopt this behavior.

### Bidirectional traceability (`trace_id_field`)

```yaml
# trackfw.yaml
trace_id_field: req_id
```

Automatically verifies the REQ↔ROADMAP link in both directions. Reports 5 check types:
- `traceid_orphan_req` — REQ with no matching ROADMAP
- `traceid_orphan_roadmap` — ROADMAP with no matching REQ
- `traceid_state_mismatch` — REQ and ROADMAP in different states
- `traceid_duplicate_req` / `traceid_duplicate_roadmap` — duplicate trace IDs

### Configurable rules

Every governance rule has configurable severity:

```yaml
# trackfw.yaml
rules:
  req_has_adr:      "error"    # default
  req_has_roadmap:  "warning"  # relax for tactical REQs
  blocked_has_req:  "error"
  wip_limit:        "warning"
  stale_wip:        "warning"
  adr_orphan:       "off"      # silence during migration
```

15+ rules available. Adopt progressively — start with `warning`, tighten to `error` as your team builds the habit.

### Governance gate

```yaml
# trackfw.yaml
governance_mode: strict   # CI fails on any violation
# governance_mode: lenient # CI passes with warnings only
```

### `update` and `sync` configuration fields

`trackfw update` and `trackfw sync` read the following keys, flat at the root of `trackfw.yaml`, through
the same loader used by every other command. All default to an empty string when absent.

```yaml
# trackfw.yaml — consumed by `trackfw update`
hooks: husky          # husky | lefthook | native | "" (no hooks regenerated)
ci: github             # github | gitlab | "" (no CI workflow regenerated)
backend: node          # backend stack — informs CLAUDE.md/agent stack sections and hook commands
frontend: react         # frontend stack — same as backend
pkg_manager: npm        # npm | yarn | pnpm | ... — composes build/test commands in generated hooks

# trackfw.yaml — consumed by `trackfw sync` (checked before the matching env var, same order in all 3 CLIs)
linear_api_key: ""
linear_team_id: ""
jira_base_url: ""
jira_email: ""
jira_token: ""
jira_project: ""
```

Full contract, including per-field consumers and the intentional exception for generated Git hooks
(which read `roadmap_dir` with their own `grep`/`sed`, since they run without the `trackfw` binary
present): `docs/cli-parity.md` → `## trackfw update vs trackfw update harness`.

---

## REQ-driven ADR discovery

When you run `trackfw req new`, the wizard analyzes your intent and asks targeted questions for each detected domain — authentication, UI, persistence, API, deploy, events. Unanswered architectural decisions become ADR drafts automatically.

```
trackfw req new "checkout flow with payment integration"
```

Detected domains: **persistence**, **api**, **events**

Questions asked:
- Which database engine will be used? → *Not decided yet* → `ADR: database-engine (Draft)`
- Which API protocol will be used? → *REST (already decided)* → no ADR
- Which event broker will be used? → *Not decided yet* → `ADR: event-broker (Draft)`

The REQ is linked to its blocking ADRs. `trackfw validate` enforces that no roadmap is created until every linked ADR reaches `Accepted` status.

This is the difference between experienced architects (who know which decisions to make) and everyone else — trackfw brings the architectural checklist to the requirement.

---

## `trackfw validate` — governance gate

```bash
$ trackfw validate

✗ REQ-2026-06-12-login-screen.md is blocked by Draft ADR: ADR-authentication-strategy.md
✗ roadmap/wip/auth-service.md has no linked REQ
⚠  2 roadmaps in wip/ (recommended: 1)

2 violation(s) found
```

Designed to run as a **pre-commit hook** and a **CI quality gate**. `trackfw init` wires both automatically for your stack.

### JSON output for CI integration

```bash
trackfw validate --json
```

```json
{
  "summary": { "violations": 2, "warnings": 1, "mode": "strict", "exit_code": 1 },
  "violations": [
    { "rule": "wip_has_req", "file": "roadmaps/wip/auth-service.md" }
  ],
  "warnings": [
    { "rule": "stale_wip", "file": "roadmaps/wip/auth-service.md" }
  ]
}
```

Use `--json` for programmatic CI parsing, Slack notifications, or custom reporting.

---

## `trackfw status` — current state at a glance

```bash
$ trackfw status

── trackfw status ──────────────────────

🔄 WIP (1)
   roadmap-auth-service.md

❌ Blocked (0)

⏳ REQs blocked by Draft ADRs (1)
   REQ-2026-06-12-login-screen.md
     → ADR-2026-06-12-authentication-strategy.md (Draft)

✅ Done (last 5)
   roadmap-user-profile.md
   roadmap-db-setup.md
```

---

## `trackfw barrier` — deterministic wave-release gate

```bash
trackfw barrier <roadmap> --wave <n> [--json]
```

`trackfw barrier` is the stack-agnostic core of the wave-release gate: it never assumes a build
tool, a test runner, or a parity rule. Every check either comes from the roadmap itself (the wave's
declared gates) or from `trackfw validate` run in-process. Point it at a roadmap basename (with or
without `.md`, resolved against `wip/` then `done/`) and a wave number, and it tells you whether
that wave is ready to release.

A wave passes only when **all four** built-in checks are green:

| Check | Passes when |
|---|---|
| `mls_complete` | The wave has at least one ML and every ML is marked `**Status:** ✅` |
| `acceptance_evidence` | Every ML has a non-empty `**Critérios de aceite:**` block with no unchecked `- [ ]` line |
| `gates` | Every command declared under the wave's `**Gates da wave:**` fenced block exits 0 — a wave with no such block declares zero gates, and the barrier never invents one. 🔴 Each non-empty, non-comment line runs as a **separate `sh -c`** — there is no shared state between lines; see rule 5 in `docs/cli-parity.md`. |
| `validate` | `trackfw validate --json` reports `violations: 0` |

### Exit codes

| Exit | Meaning |
|---|---|
| `0` | `status: "passed"` — every check is green, the wave may release |
| `1` | `status: "blocked"` — at least one check failed; the JSON/text report says which |
| `2` | Usage/resolution error — the roadmap or the wave number could not be resolved. This is **not** `blocked`: a barrier that could not run is distinct from one that ran and failed |

### Correcting a blocked wave

```bash
$ trackfw barrier ROADMAP-example --wave 2
✗ mls_complete: ML-2C: not complete (status: 🔄)
✗ acceptance_evidence: ML-2C: 2 unmet acceptance criteria
wave 2: blocked
```

Fix the roadmap (mark the ML `✅`, check off the remaining criteria) and rerun the exact same
command — the barrier is not a one-shot denial; a corrected wave passes on the next invocation:

```bash
$ trackfw barrier ROADMAP-example --wave 2
✓ mls_complete
✓ acceptance_evidence
✓ gates
✓ validate
wave 2: passed
```

### JSON output

```bash
trackfw barrier ROADMAP-example --wave 2 --json
```

```json
{
  "roadmap": "ROADMAP-example.md",
  "wave": 2,
  "status": "blocked",
  "started_at": "2026-07-29T10:30:00Z",
  "finished_at": "2026-07-29T10:30:04Z",
  "checks": [
    { "name": "mls_complete", "status": "passed", "evidence": ["ML-2A: ✅"], "failures": [] },
    { "name": "acceptance_evidence", "status": "blocked", "evidence": [], "failures": ["ML-2C: 2 unmet acceptance criteria"] },
    { "name": "gates", "status": "passed", "commands": ["make quality"], "evidence": ["make quality: exit 0"], "failures": [] },
    { "name": "validate", "status": "passed", "evidence": ["0 violations, 0 warnings"], "failures": [] }
  ],
  "failures": ["acceptance_evidence: ML-2C: 2 unmet acceptance criteria"]
}
```

### `trackfw barrier` vs. `/trackfw:barrier`

`trackfw barrier` is the deterministic, reproducible CLI — it never invokes agents and never
performs Git operations. The `/trackfw:barrier` slash command wraps it with the parts a binary
cannot evaluate: dispatching `code-quality`/`security` reviews, auditing the diff against scope,
and — only for `trackfw_architect`, the sole Git authority in this workflow — committing and
pushing once every check and review is green. A green CLI barrier is necessary but not sufficient
to release a wave. Full contract: `docs/cli-parity.md` → `## trackfw barrier`.

---

## AI assistant integration

`trackfw init` can install initial AI integrations. The `agents` and `skills`
command families provide the complete lifecycle in every distribution.

| Target | Native/fallback representation |
|---|---|
| Claude Code | Subagent Markdown and Agent Skills |
| Codex | Custom-agent TOML and Agent Skills |
| Gemini CLI | Agent Markdown and skills |
| Antigravity | Agent/skill directories; explicit `legacy-cli` surface available |
| Cursor | Agent Markdown and skills |
| GitHub Copilot | Custom agents and Agent Skills |
| Windsurf | Specialist-skill fallback for agents and native skills |
| Amazon Q | CLI agent JSON and workflow-rule fallback |
| Kiro | Native IDE/CLI agents and Agent Skills |

```bash
# Inspect every deployment, including legacy surfaces
trackfw agents list --json

# Install selected items in the repository
trackfw agents install --targets codex,claude --items architect,backend --scope project
trackfw skills install --targets codex,antigravity --items governance,implement --scope project

# Select an alternate surface explicitly
trackfw agents install --targets kiro --surface kiro=cli
trackfw agents list --targets antigravity --surface antigravity=legacy-cli
```

Without `--targets`, mutations open a numbered/checkbox selector in a TTY and
fail with an actionable error in CI. The lifecycle reports `not-installed`,
`current`, `outdated`, or `modified`. A manifest under `.trackfw/` records
scope-specific ownership, version, SHA-256, and shared claims. Modified files
are never replaced or removed unless `--force` is explicit, and unmanaged files
are never removed. Known historical templates are adopted without overwriting;
unknown unmanaged content cannot be adopted by `update`, even with `--force`.

Without `--scope`, `install`/`update` default to `global` (`~/.claude/...`)
when stdin is not a TTY, and otherwise prompt interactively with `global`
pre-selected — the resolved destination paths are printed before anything is
written. `uninstall` is the one exception: without `--scope` and without a
TTY it fails instead of guessing, since silently defaulting a destructive
operation could delete artifacts from the user's home directory. `list` never
prompts and always assumes `global` unless `--scope` is given, so it reports
the same destinations `install` actually wrote to.

The **12 roles** installed for each tool: **architect · backend · frontend · qa · infra · security · code-quality · dba · ux · data · iac · tooling**

The **17 skills** cover governance process (governance, implement, plan, release, review) and technical specialties (architecture-skill, backend-skill, code-quality-skill, data-skill, dba-skill, frontend-skill, iac-skill, infra-skill, qa-skill, security-skill, tooling-skill, ux-skill).

---

## Agent identity — give your agents a name

By default the agents are functional and impersonal: `trackfw-architect`,
`trackfw-backend`, … Agent identity lets you name all twelve, pick how they
address you, and call them by name.

```bash
# Non-interactive: pick a themed preset
trackfw init --identity-preset greek

# Or answer the wizard, which also offers "name them one by one"
trackfw init
```

`--identity-preset` accepts ten themed presets plus two opt-outs:

`greek` · `norse` · `potter` · `thrones` · `chaves` · `pioneers` · `starwars` · `tolkien` · `turma` · `egyptian` · `neutral` · `none`

`neutral` and `none` write nothing and keep the current behavior.

Sample mapping (three of the ten presets):

| Agent | `greek` | `pioneers` | `tolkien` |
|---|---|---|---|
| architect | Zeus | Turing | Gandalf |
| backend | Apolo | Ritchie | Aragorn |
| frontend | Afrodite | Berners-Lee | Arwen |
| qa | Ártemis | Hamilton | Legolas |
| infra | Ares | Torvalds | Gimli |
| security | Hades | Diffie | Boromir |
| dba | Poseidon | Codd | Elrond |
| ux | Atena | Norman | Galadriel |
| code-quality | Hefesto | Knuth | Faramir |
| data | Métis | Hopper | Bilbo |
| iac | Dédalo | Hashimoto | Aulë |
| tooling | Prometeu | McCarthy | Celebrimbor |

The remaining presets are `norse` (Odin, Thor, Freya…), `potter` (Dumbledore,
Snape, Luna…), `thrones` (Tyrion, Jon, Arya…), `chaves` (Girafales, Madruga,
Chiquinha…), `starwars` (Yoda, Han, Leia…), `turma` (Franjinha, Cebolinha,
Magali…), and `egyptian` (Thoth, Rá, Ísis…).

### Custom mode and your nickname

The interactive wizard also offers **name them one by one**: you type all twelve
display names yourself. Each entry is validated as you go — an invalid name is
rejected with an inline error, never silently corrected, and two names that
resolve to the same identifier are rejected too.

The wizard then asks for an optional **nickname for you**, which is how the
agents will address you.

### `agents install` also runs the wizard

`trackfw init` is not the only entry point: `trackfw agents install`, the
natural path in a project that is already governed, offers the same wizard.
The rule is identical across all CLIs — it appears **only** when
**all** of the following hold:

- the command is `agents` (never `skills`: skills have no identity);
- stdin is a TTY (a non-interactive run never blocks on a prompt);
- and either no `~/.trackfw/identity.json` exists yet, or `--identity` was
  passed to force reconfiguration.

With an identity already configured and no `--identity`, the command asks
nothing — it prints `identity: N custom agent(s)` and installs directly.

```bash
# First run on this machine: offers the wizard, then installs
trackfw agents install --targets claude

# Identity already configured: no prompt, installs directly
trackfw agents install --targets claude

# Force reconfiguration
trackfw agents install --targets claude --identity

# Non-interactive, same semantics as init --identity-preset
trackfw agents install --targets claude --identity-preset chaves
```

Two new flags exist only on `agents install` (`skills install` never
registers them): `--identity` (bool, forces reconfiguration even if a file
already exists) and `--identity-preset <preset>` (same ten themed presets
plus `neutral` and `none`; an invalid value errors out listing the valid
ones).

In **name them one by one** mode, each field is now labeled by the agent's
specialty, taken from the catalog, never by its technical id:

```
Architect — Architecture, ADRs and governed coordination
> _
```

Before anything is written to disk — for a themed preset **or** for custom
names — a confirmation screen lists all twelve `specialty → name` pairs plus
your nickname:

```
── Confirmation ──────────────────────────────
  Architecture, ADRs and governed coordination   →  Girafales
  Backend APIs, domain logic and integrations    →  Madruga
  ...
  What we'll call you:                              chefe

? Confirm?
```

Answering no returns to preset selection; nothing is written until you
confirm.

Everything is stored in a single global file — the same binary in all channels reads it:

```json
// ~/.trackfw/identity.json
{
  "schema_version": 1,
  "user_nickname": "Kleber",
  "agents": {
    "architect": { "display_name": "Zeus", "slug": "zeus" }
  }
}
```

The generated artifact — still installed at the unchanged path
`~/.claude/agents/trackfw-architect.md`:

```markdown
---
name: zeus-tf
description: Zeus — Principal software architect for system design, ADRs and governed multi-agent coordination.
model: opus
---

Você é Zeus. Trate o usuário como Kleber.

# Architect
...
```

### Why the `-tf` suffix

The `name` always ends in `-tf`. Two agents sharing the same `name` in the same
directory make Claude Code load *"only one of them, chosen by filesystem read
order rather than a documented precedence"* — a silent, non-deterministic
shadowing that the user cannot detect. If you already keep a personal `zeus.md`
agent, `zeus-tf` guarantees both survive.

The suffix belongs to the technical identifier only. It never appears in how
the agent presents itself: the `description` and the body both say **Zeus**.

### How to invoke it

| You type | What happens |
|---|---|
| `@agent-zeus-tf` | Works — explicit mention resolves against `name` |
| "chame o Zeus" / "ask Zeus to…" | Works — natural-language routing reads `description` |
| "quem é você?" | Answers "Sou Zeus" — the body is loaded after selection |

### Cost and non-regression

The agent **never reads the configuration at runtime**. Identity is
materialized into the artifact at install time, so the per-interaction cost is
essentially zero: the `description` is substituted rather than extended, and
the body grows by tens of tokens that are loaded only after the agent has
already been selected. No tool call, no file read, no permanent instruction.

Without `~/.trackfw/identity.json`, the generated artifacts are **byte for byte
identical** to the current ones. The feature is opt-in and regresses nothing.

---

## `trackfw init` — stack-aware scaffolding

```
? Project type?          Full-stack / Frontend / Backend / Governance only
? Frontend stack?        React / Vue / Angular
? Backend stack?         Go / Java / Node / Python
? Package manager?       npm / pnpm / yarn / bun
? Git hooks?             husky / lefthook / none
? CI system?             GitHub Actions / GitLab CI / none
? Which AI assistants?   Claude / Codex / Gemini / Antigravity / Cursor / Copilot / Windsurf / Amazon Q / Kiro
? Agent identity?        Greek / Norse / Potter / Thrones / Chaves / Pioneers / Star Wars / Tolkien / Turma / Egyptian / Name them one by one / Neutral
```

The governance structure (`docs/adr/`, `docs/req/`, `docs/roadmaps/`) is always identical — stack-agnostic. The generated hooks, workflows, and AI integrations adapt to your answers.

The Codex integration is repository-scoped: `AGENTS.md` carries persistent instructions, `.agents/skills/` provides governance workflows, `.codex/agents/` provides specialist subagents, and `.codex/hooks.json` signals permission requests to the local dashboard.

---

## Design principles

1. **Files are state** — folder position is the source of truth. No database, no lock-in.
2. **Traceability is mandatory** — `validate` is a gate, not a suggestion.
3. **Framework-agnostic, integration-aware** — governance never changes; generated artifacts adapt to your stack.
4. **One active roadmap at a time** — parallel work without traceability is the root of most delivery chaos.
5. **Human-readable, machine-parseable** — every artifact is a Markdown file with a predictable structure.
6. **Guided, not prescriptive** — the wizard surfaces decisions you might not know to ask; it never blocks work unnecessarily.
7. **Configurable by design** — every governance rule has a severity (`off`/`warning`/`error`). Start permissive, tighten as your team builds the habit.
8. **AI-agent aware** — `roadmap_namespacing: by_agent` and `trace_id_field` make AI-generated work traceable and auditable by default.

---

## Credential guard: detection, not prevention

trackfw can generate **guard hooks** that block agents from materializing real credentials,
creating raw git branches, or writing to frozen paths. Since v9.3.0, guard hooks call the
trackfw binary directly (`trackfw guard credential`, `trackfw guard git-branch`,
`trackfw guard write-scope`) — no `.sh` script is required.

`trackfw validate` reports when a guard looks compromised (`credential_guard_hook_resolvable`,
`git_branch_guard_hook_resolvable`):

- the hook **command no longer contains the canonical `trackfw guard <name>` form** — it may
  have been replaced, neutralized (e.g. `echo trackfw guard credential`), or mutated;
- **legacy `.sh`-based hook** detected — `.sh` scripts do not run on Windows; run
  `trackfw update` to migrate to the binary form;
- `credential_guard.mode` was **downgraded** from `block` on disk relative to your last commit
  (`credential_guard_mode_downgrade`).

`credential_guard_script_integrity` fires **only when `scripts/trackfw-credential-guard.sh`
exists** — it compares the file against the template this binary would generate. If the script
is absent (the default after `trackfw update`), the rule is silent: absence is not a violation.

A global variant (`trackfw guard credential --global`) is installed in your AI CLI's global
hooks directory and covers projects that do not run `trackfw init`.

**Read this before relying on it.**

These checks are **detection, not prevention.** trackfw *tells you* something diverged — it does
**not** stop it from happening. This is not an implementation gap: it was measured that no technical
prevention is possible, within trackfw's scope, against an agent that has unrestricted write access
to your workspace. An agent that can edit your files can delete the guard script, overwrite it with
a no-op, or relax the mode — and on most agent CLIs, a hook that fails to run simply lets the tool
call proceed.

What these checks are **not** able to see:

- **changes the adversary also commits** — once it is in your `HEAD`, there is nothing to diverge
  from. What remains is the audit trail: the change shows up in your diff and in review.
- **anything with no commit to compare against** — a repository with no commits, or a file that was
  never versioned. The check stays silent rather than guessing.
- **the difference between tampering and you being out of date.** The script carries no version
  marker, so a divergence may simply mean you have not run `trackfw update` since upgrading. That is
  why the message is worded neutrally and the rule defaults to a **warning**, which does **not**
  change `validate`'s exit code. If you want CI to fail on it:

```yaml
# trackfw.yaml
rules:
  credential_guard_script_integrity: error
```

- **the check can be switched off by the same edit it is meant to catch.** Rule severity is read
  from `rules:` in the `trackfw.yaml` **on disk** — so an edit that both downgrades
  `credential_guard.mode` *and* sets `credential_guard_mode_downgrade: off` silences the report,
  with nothing committed. Anchoring `rules:` to your last commit is a known open item.

### If `trackfw update` suddenly reports something it used to ignore

Since the version that introduced anchoring, the credential-guard checks are resolved against **your
last commit**, not only against the file on disk — and they can **no longer be suppressed** via
`.trackfw-baseline.json`. This is deliberate: a check that can be switched off by the same
uncommitted edit it is meant to catch is not a check.

If one of them starts reporting after an upgrade, you have two legitimate ways out, and both leave a
trail:

```yaml
# trackfw.yaml — commit this change
rules:
  credential_guard_hook_resolvable: off
```

...or fix the underlying cause (usually `trackfw update`, to regenerate the guard script and wiring).

One caveat worth knowing: `governance_mode: lenient` still turns **every** finding into a warning,
including these. Closing that is tracked separately.

The strongest protection remains the ordinary one: the guard script and `trackfw.yaml` are
**versioned files**. Review their diffs like you review any other code. Every limitation above has
the same escape hatch: the change is *visible* in `git diff`.

## What trackfw is not

- Not a project management SaaS — no accounts, no cloud sync, no data leaving your repository. A local dashboard is available via `trackfw serve`.
- Not a replacement for Git history — it complements, not duplicates
- Not a task tracker — use GitHub Issues, Linear, or Jira for tasks; trackfw governs the *why*
- Not opinionated about how you write code — only about how you document decisions

---

## Compared to alternatives

| Tool | What it does | What's missing |
|---|---|---|
| **adr-tools** | Creates ADR files | No link to requirements or roadmaps |
| **madr** | ADR template format | No enforcement, no delivery tracking |
| **Linear / Jira** | Task tracking | No traceability to architectural decisions |
| **Kosli** | SDLC compliance for regulated industries | SaaS, accounts, cost — not for every team |
| **trackfw** | Enforces the full chain: decision → requirement → roadmap → delivery | — |

trackfw is the only open-source CLI that links ADRs to requirements, requirements to roadmaps, and enforces the chain as a pre-commit and CI gate — with native support for AI coding assistants.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request (the guide is in Portuguese).

```bash
git clone https://github.com/kgsaran/trackfw
cd trackfw
make build   # compiles to bin/trackfw
make test    # go test ./...
make lint    # go vet ./...
```

Generators are the stack-specific components — you can add support for a new stack without touching core logic. See `internal/generators/` for examples.

Issues and pull requests welcome at [github.com/kgsaran/trackfw](https://github.com/kgsaran/trackfw).

---

## License

MIT — see [LICENSE](LICENSE)
