trackfw 7.1.0 → 7.3.0

package/src/ship/runner.js

@@ -18,6 +18,68 @@ const { evaluateBranchIntegration, DECISION: BRANCH_PRUNE_DECISION } = require('
 // In --dry-run mode these are printed but not executed.
 const GIT_WRITE_COMMANDS = new Set(['commit', 'push', 'fetch'])
 
+// force-with-lease refusal messages. Named constants so the ML-1B parity gate has a single
+// place to compare byte-for-byte across the 3 CLIs. Byte-identical to Go's
+// forceLease*Msg/Fmt constants (internal/commands/ship.go) and Python's FORCE_LEASE_* below.
+// Never expose "--force" (raw) as a flag — see
+// ADR-2026-08-19-caminho-governado-para-push-forcado-e-tag-de-release.md.
+const FORCE_LEASE_NO_FORGE_CLI_MSG =
+  'trackfw ship --force-with-lease requires a forge CLI (gh, glab, or az) to confirm an open pull/merge request before rewriting remote history. No forge CLI is available for this repository — install and authenticate it, or push without --force-with-lease.'
+
+function forceLeaseNoPROpenMsg(branch) {
+  return `trackfw ship --force-with-lease refuses to run: branch "${branch}" has no open pull/merge request. Open the PR/MR first (trackfw ship without --force-with-lease, or your forge's web UI), then retry.`
+}
+
+function forceLeaseCannotVerifyMsg(branch, cliName, errMessage) {
+  return `trackfw ship --force-with-lease could not verify whether branch "${branch}" has an open pull/merge request (${cliName} CLI error: ${errMessage}). Refusing rather than risking a force push without a verified PR — check your ${cliName} CLI authentication and retry.`
+}
+
+/**
+ * defaultCheckPROpen queries the resolved forge CLI for an open PR/MR whose source branch is
+ * `branch`, using the same list-based query shape for every forge: empty result means "no PR"
+ * (exit 0), any non-zero exit or unparseable output means "cannot verify" (thrown — never
+ * conflated with "no PR"). bitbucket and "manual" never reach here: runShip only calls
+ * checkPROpen when adapter.available is true, and bitbucket's adapter is always available=false.
+ * @param {object} adapter
+ * @param {string} branch
+ * @returns {boolean}
+ */
+function defaultCheckPROpen(adapter, branch) {
+  let args
+  switch (adapter.forge) {
+    case 'github':
+      args = ['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number']
+      break
+    case 'gitlab':
+      // glab mr list: --source-branch filters by source branch, --state opened matches
+      // gh's "open" state, -F json requests machine-readable output (glab's own flag,
+      // not an external jq/GNU dependency).
+      args = ['mr', 'list', '--source-branch', branch, '--state', 'opened', '-F', 'json']
+      break
+    case 'azure':
+      // az defaults to --output json; passed explicitly here for clarity, not reliance
+      // on the ambient default.
+      args = ['repos', 'pr', 'list', '--source-branch', branch, '--status', 'active', '--output', 'json']
+      break
+    default:
+      throw new Error(`no PR/MR query defined for forge "${adapter.forge}"`)
+  }
+
+  const result = spawnSync(adapter.cliName, args, { encoding: 'utf8' })
+  if (result.status !== 0) {
+    const msg = (result.stderr || '').trim() || `${adapter.cliName} exited with ${result.status}`
+    throw new Error(msg)
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(result.stdout || '[]')
+  } catch (e) {
+    throw new Error(`could not parse ${adapter.cliName} output: ${e.message}`)
+  }
+  return Array.isArray(parsed) && parsed.length > 0
+}
+
 /**
  * isGitWriteCmd returns true when the first arg is a write-mode git subcommand.
  * @param {string[]} args
@@ -240,10 +302,17 @@ function allDocOnly(files) {
  */
 const COMMIT_MESSAGE_SEP = '\x1e'
 
+// GIT_SYMBOLIC_REF_ORIGIN_HEAD_PREFIX is the fixed prefix `git symbolic-ref
+// refs/remotes/origin/HEAD` always returns before the branch name, because "origin" is the
+// literal ref namespace queried — never derived from the output itself. Stripping this exact
+// prefix (instead of cutting at the last '/') is what makes defaultBaseBranch correct for a
+// default branch that itself contains a slash (e.g. "release/7.2"): lastIndexOf('/') used to
+// cut at "7.2", discarding "release/". Mirrors Go's ship.go gitSymbolicRefOriginHeadPrefix.
+const GIT_SYMBOLIC_REF_ORIGIN_HEAD_PREFIX = 'refs/remotes/origin/'
+
 /**
  * defaultBaseBranch resolves the repository's default branch for `git log <base>..HEAD`.
- * Tries `git symbolic-ref refs/remotes/origin/HEAD` (format "refs/remotes/origin/main" —
- * only the name after the last slash is kept) and falls back to "main" when that fails or
+ * Tries `git symbolic-ref refs/remotes/origin/HEAD` and falls back to "main" when that fails or
  * yields nothing.
  * @param {function} execGit
  * @returns {string}
@@ -252,9 +321,9 @@ function defaultBaseBranch(execGit) {
   const { stdout, error } = execGit(['symbolic-ref', 'refs/remotes/origin/HEAD'])
   if (error) return 'main'
   const out = (stdout || '').trim()
-  const idx = out.lastIndexOf('/')
-  if (idx < 0 || idx + 1 >= out.length) return 'main'
-  return out.slice(idx + 1)
+  if (!out.startsWith(GIT_SYMBOLIC_REF_ORIGIN_HEAD_PREFIX)) return 'main'
+  const name = out.slice(GIT_SYMBOLIC_REF_ORIGIN_HEAD_PREFIX.length)
+  return name === '' ? 'main' : name
 }
 
 /**
@@ -444,6 +513,59 @@ function runShip(opts, deps = {}) {
     writeln('Governance: OK')
   }
 
+  // ─── Step 2.5: force-with-lease gate ───────────────────────────────────────
+  // Runs before any write (commit/push) — a refusal here must never leave a local
+  // commit the caller cannot push. Read-only, so it runs in --dry-run too, same
+  // posture as the read-only calls in Step 0 / Step 7.
+  //
+  // forceLeaseAdapter/forceLeaseResolution are reused by Step 7 below to avoid a
+  // second forge resolution and a duplicate "Forge: ..." line, and because Step 7
+  // must skip PR/MR creation entirely once this gate has confirmed one is already
+  // open — creating a second one would be a spurious failure on every successful
+  // force push.
+  let forceLeaseAdapter = null
+  let forceLeaseResolution = null
+  if (opts.forceWithLease) {
+    const { stdout: gateRemoteURLRaw } = execGit(['remote', 'get-url', 'origin'])
+    const gateRemoteURL = (gateRemoteURLRaw || '').trim()
+
+    let resolution
+    try {
+      resolution = forgeResolve({
+        flagForge: opts.forge || '',
+        configForge: deps.configForge || '',
+        remoteURL: gateRemoteURL,
+        repoDir: deps.repoDir || '',
+      })
+    } catch (resErr) {
+      writeErr(resErr.message)
+      return 1
+    }
+
+    const adapter = forgeAdapter(resolution.forge, deps.availFn || undefined)
+    if (resolution.forge === 'manual' || !adapter.available) {
+      writeErr(FORCE_LEASE_NO_FORGE_CLI_MSG)
+      return 1
+    }
+
+    const checkPROpen = deps.checkPROpen || defaultCheckPROpen
+    let open
+    try {
+      open = checkPROpen(adapter, branch)
+    } catch (prErr) {
+      writeErr(forceLeaseCannotVerifyMsg(branch, adapter.cliName, prErr.message))
+      return 1
+    }
+    if (!open) {
+      writeErr(forceLeaseNoPROpenMsg(branch))
+      return 1
+    }
+
+    writeln(`force-with-lease: open ${adapter.noun} confirmed for "${branch}" (${resolution.forge}).`)
+    forceLeaseAdapter = adapter
+    forceLeaseResolution = resolution
+  }
+
   // ─── Step 3: Squash-merge detection ────────────────────────────────────────
   if (opts.dryRun) {
     writeln('[dry-run] git fetch origin --prune')
@@ -466,7 +588,14 @@ function runShip(opts, deps = {}) {
   writeln('────────────────────────────────────────────────────────\n')
 
   // Reuses stagedFiles read at the top of the function (Step 0) — never re-query git here.
-  if (stagedFiles.length === 0) {
+  //
+  // --force-with-lease push-only mode: a rebase that resolved conflicts already
+  // committed the result (the index is clean afterwards) — there is nothing left to
+  // stage or commit, only to push. Only --force-with-lease grants this exception;
+  // without it, "nothing staged" still aborts exactly as before (non-regression).
+  const pushOnly = opts.forceWithLease && stagedFiles.length === 0
+
+  if (stagedFiles.length === 0 && !opts.forceWithLease) {
     writeErr(
       'nothing is staged — stage your files explicitly before running ship:\n' +
       '  git add <file1> <file2> ...\n' +
@@ -476,26 +605,35 @@ function runShip(opts, deps = {}) {
   }
 
   // ─── Step 5: Commit ────────────────────────────────────────────────────────
-  if (!opts.message) {
-    writeErr(
-      'commit message is required — use -m:\n' +
-      '  trackfw ship -m "feat(<scope>): <description>"'
-    )
-    return 1
-  }
+  if (pushOnly) {
+    writeln('Nothing staged — --force-with-lease pushes existing commits only, no new commit.')
+  } else {
+    if (!opts.message) {
+      writeErr(
+        'commit message is required — use -m:\n' +
+        '  trackfw ship -m "feat(<scope>): <description>"'
+      )
+      return 1
+    }
 
-  const { error: commitErr } = git(['commit', '-m', opts.message])
-  if (commitErr) {
-    writeErr(`git commit failed: ${commitErr.message}`)
-    return 1
-  }
+    const { error: commitErr } = git(['commit', '-m', opts.message])
+    if (commitErr) {
+      writeErr(`git commit failed: ${commitErr.message}`)
+      return 1
+    }
 
-  if (!opts.dryRun) {
-    writeln(`Committed: ${opts.message}`)
+    if (!opts.dryRun) {
+      writeln(`Committed: ${opts.message}`)
+    }
   }
 
   // ─── Step 6: Push ──────────────────────────────────────────────────────────
-  const pushArgs = buildPushArgs(branch, execGit)
+  let pushArgs = buildPushArgs(branch, execGit)
+  if (opts.forceWithLease) {
+    // Fixed position: push --force-with-lease [-u] origin <branch> — identical
+    // across the 3 CLIs (ML-1B's parity gate compares this literally).
+    pushArgs = [pushArgs[0], '--force-with-lease', ...pushArgs.slice(1)]
+  }
   const { error: pushErr } = git(pushArgs)
   if (pushErr) {
     writeErr(`git push failed: ${pushErr.message}`)
@@ -507,6 +645,17 @@ function runShip(opts, deps = {}) {
   }
 
   // ─── Step 7: Open PR/MR ────────────────────────────────────────────────────
+  // --force-with-lease only ever reaches here after Step 2.5 confirmed a PR/MR is
+  // already open on this branch — creating another one would be a spurious failure
+  // on every successful force push. Reuses the adapter/resolution Step 2.5 already
+  // computed instead of resolving the forge a second time.
+  if (opts.forceWithLease) {
+    writeln(`Forge:     ${forceLeaseResolution.forge} (source: ${forceLeaseResolution.source})`)
+    writeln(`${forceLeaseAdapter.noun} already open — skipping creation (--force-with-lease).`)
+    writeln('\nship complete.')
+    return 0
+  }
+
   const { stdout: remoteURLRaw } = execGit(['remote', 'get-url', 'origin'])
   const remoteURL = (remoteURLRaw || '').trim()
 
@@ -615,4 +764,11 @@ module.exports = {
   buildPRBody,
   COMMIT_MESSAGE_SEP,
   detectPendingSquashMerges,
+  defaultCheckPROpen,
+  FORCE_LEASE_NO_FORGE_CLI_MSG,
+  forceLeaseNoPROpenMsg,
+  forceLeaseCannotVerifyMsg,
+  // Exported for reuse by push/runner.js (AC2 of REQ-2026-08-22-trackfw-push).
+  buildPushArgs,
+  defaultExecGit,
 }

package/src/validator/index.js

@@ -1174,13 +1174,21 @@ const GIT_BRANCH_GUARD_SCRIPT_MARKER = 'trackfw-git-branch-guard.sh'
 // sibling is a structurally malformed entry the CLI silently never executes (hades-tf ML-4A
 // barrier finding), not merely "absent". false only for Cursor, whose schema
 // ({"command":...}) never carries a "type" field at all.
+//
+// requiresVarOrShellPrefix (ROADMAP-2026-08-21 ML-1B, port of Go's
+// credentialGuardHookFile.requiresVarOrShellPrefix): true for Claude/Codex/Gemini — the
+// ADR-2026-08-11 requires these CLIs to anchor the hook path with $VAR/... or "$(git ...)/..."
+// because their hooks run from the agent's cwd, not necessarily the project root. A bare
+// relative path ("scripts/...") silently fails from any subdirectory (REQ-2026-08-17 root
+// cause). false for Cursor/Copilot/Kiro, where the bare relative path IS the correct form —
+// flagging them would be a false-positive (the dominant risk of this REQ).
 const CREDENTIAL_GUARD_HOOK_FILES = [
-  { relPath: '.claude/settings.json', cli: 'Claude Code', requiresCommandType: true },
-  { relPath: '.codex/hooks.json', cli: 'Codex CLI', requiresCommandType: true },
-  { relPath: '.gemini/settings.json', cli: 'Gemini CLI', requiresCommandType: true },
-  { relPath: '.cursor/hooks.json', cli: 'Cursor', requiresCommandType: false },
-  { relPath: '.github/hooks/trackfw-attention.json', cli: 'GitHub Copilot CLI', requiresCommandType: true },
-  { relPath: '.kiro/hooks/trackfw-attention.json', cli: 'Kiro', requiresCommandType: true },
+  { relPath: '.claude/settings.json', cli: 'Claude Code', requiresCommandType: true, requiresVarOrShellPrefix: true },
+  { relPath: '.codex/hooks.json', cli: 'Codex CLI', requiresCommandType: true, requiresVarOrShellPrefix: true },
+  { relPath: '.gemini/settings.json', cli: 'Gemini CLI', requiresCommandType: true, requiresVarOrShellPrefix: true },
+  { relPath: '.cursor/hooks.json', cli: 'Cursor', requiresCommandType: false, requiresVarOrShellPrefix: false },
+  { relPath: '.github/hooks/trackfw-attention.json', cli: 'GitHub Copilot CLI', requiresCommandType: true, requiresVarOrShellPrefix: false },
+  { relPath: '.kiro/hooks/trackfw-attention.json', cli: 'Kiro', requiresCommandType: true, requiresVarOrShellPrefix: false },
 ]
 
 // resolveCredentialGuardHookPath resolve o valor bruto de um comando de hook (string extraída do
@@ -1212,14 +1220,84 @@ function resolveCredentialGuardHookPath(raw, root) {
     const inner = raw.slice(codexPrefix.length, raw.length - 1)
     return path.join(root, inner)
   }
-  if (!raw.startsWith('$') && !raw.startsWith('"') && !path.isAbsolute(raw)) {
+  if (!raw.startsWith('$') && !raw.startsWith('"') && !path.isAbsolute(raw) && !raw.startsWith('~/')) {
     // Caminho relativo puro — Cursor (beforeShellExecution/preToolUse), GitHub Copilot CLI
     // (campo "bash"), Kiro (action.command).
+    // ~/… é excluído: é classe 1 (tilde expande para $HOME — ancorado) mas o validator não expande
+    // o til; ok=false (null) silencia sem acusar.
     return path.join(root, raw)
   }
   return null
 }
 
+// HOOK_ANCHORAGE_CLASS_* classifica a semântica de ancoragem de um valor de comando de hook.
+// Avaliada apenas para CLIs com requiresVarOrShellPrefix=true. Decisão: ADR-2026-08-22.
+const HOOK_ANCHORAGE_CLASS_ANCHORED      = 1
+const HOOK_ANCHORAGE_CLASS_CWD_DEPENDENT = 2
+const HOOK_ANCHORAGE_CLASS_UNDECIDABLE   = 3
+
+// stripOuterQuotesForClassify remove aspas duplas envolventes de raw, se presentes. Necessário
+// porque "$PWD/scripts/…" entre aspas (achado D.3) deve receber o mesmo veredito que $PWD/…
+// sem aspas: as aspas são sintaxe, não semântica de ancoragem.
+function stripOuterQuotesForClassify(raw) {
+  if (raw.length >= 2 && raw[0] === '"' && raw[raw.length - 1] === '"') {
+    return raw.slice(1, raw.length - 1)
+  }
+  return raw
+}
+
+// hookValueWasQuoted reporta se raw tinha aspas duplas externas que stripOuterQuotesForClassify
+// removeria. Usado para distinguir ~/… (tilde expande para $HOME — classe 1) de "~/…" (tilde
+// NÃO expande dentro de aspas duplas — classe 2).
+function hookValueWasQuoted(raw) {
+  return raw.length >= 2 && raw[0] === '"' && raw[raw.length - 1] === '"'
+}
+
+// classifyHookAnchorage retorna a classe de ancoragem de rawStripped (com aspas externas já
+// removidas). wasQuoted indica se o valor original tinha aspas externas (obtido com
+// hookValueWasQuoted antes de chamar stripOuterQuotesForClassify). Ver HOOK_ANCHORAGE_CLASS_*
+// e ADR-2026-08-22.
+function classifyHookAnchorage(rawStripped, wasQuoted) {
+  // Classe 1 — ancora na raiz do projeto.
+  if (
+    rawStripped.startsWith('$CLAUDE_PROJECT_DIR/') ||
+    rawStripped.startsWith('$GEMINI_PROJECT_DIR/') ||
+    rawStripped.startsWith('$(git rev-parse --show-toplevel)/') ||
+    path.isAbsolute(rawStripped)
+  ) {
+    return HOOK_ANCHORAGE_CLASS_ANCHORED
+  }
+  // ~/… sem aspas: tilde expande para $HOME em qualquer shell POSIX — semanticamente ancorado.
+  // "~/…" com aspas: tilde NÃO expande dentro de aspas duplas, logo a forma quebra — classe 2.
+  if (rawStripped.startsWith('~/') && !wasQuoted) {
+    return HOOK_ANCHORAGE_CLASS_ANCHORED
+  }
+  // Classe 2 — expande a partir do cwd.
+  // ${PWD}/… tem a mesma semântica de $PWD/… (PWD é mandado pelo POSIX, sempre o cwd).
+  if (
+    rawStripped.startsWith('$PWD/') ||
+    rawStripped.startsWith('${PWD}/') ||
+    rawStripped.startsWith('./') ||
+    rawStripped.startsWith('../') ||
+    (!rawStripped.startsWith('$') && !path.isAbsolute(rawStripped))
+  ) {
+    return HOOK_ANCHORAGE_CLASS_CWD_DEPENDENT
+  }
+  // Classe 3 — indecidível; silêncio declarado.
+  return HOOK_ANCHORAGE_CLASS_UNDECIDABLE
+}
+
+// cwdDependentReason retorna o sufixo de mensagem específico por forma para violações de
+// classe 2, iniciando em "with a …". Dois formatos: formas contendo $PWD ou ${PWD} (em qualquer
+// posição, inclusive em wrappers sh -c / env) recebem a mensagem do $PWD; demais recebem
+// "bare relative path". Usa includes (não startsWith) para cobrir sh -c "$PWD/…" e env FOO=x $PWD/….
+function cwdDependentReason(rawStripped) {
+  if (rawStripped.includes('$PWD') || rawStripped.includes('${PWD}')) {
+    return 'with a $PWD path — $PWD expands to the current working directory, not the project root; run `trackfw update` to fix it'
+  }
+  return "with a bare relative path — this command only resolves from the project root and will silently fail when the agent's cwd is a subdirectory; run `trackfw update` to fix it"
+}
+
 // collectCommandsWithMarker percorre recursivamente um valor JSON já decodificado e coleta todo
 // valor-string que contém marker, independentemente do nome do campo que o contém — junto com um
 // sinal estrutural (typeIsCommand) de que o objeto imediato que o contém também tem
@@ -1323,6 +1401,18 @@ function validateGuardHookResolvable(scriptMarker, cwd) {
       if (seen.has(seenKey)) continue
       seen.add(seenKey)
 
+      // ADR-2026-08-22: classificar por ancoragem ANTES de resolver. Aspas externas são
+      // sintaxe, não semântica — removê-las antes garante que "$PWD/…" receba o mesmo veredito.
+      // wasQuoted distingue ~/… (classe 1) de "~/…" (classe 2).
+      const wasQuoted = hookValueWasQuoted(m.raw)
+      const rawStripped = stripOuterQuotesForClassify(m.raw)
+      const anchorageClass = classifyHookAnchorage(rawStripped, wasQuoted)
+      if (hf.requiresVarOrShellPrefix && anchorageClass === HOOK_ANCHORAGE_CLASS_CWD_DEPENDENT) {
+        msgs.push(`${hf.relPath} (${hf.cli}) references ${scriptMarker} ${cwdDependentReason(rawStripped)}`)
+        continue
+      }
+
+      // Classe 1 (ancorado) e classe 3 (indecidível) prosseguem para a resolução existente.
       const resolved = resolveCredentialGuardHookPath(m.raw, root)
       if (resolved === null) continue
 
@@ -1901,6 +1991,24 @@ match_subcommand() {
               ;;
           esac
         done
+        # git checkout -- <path> | git checkout . descarta alterações não commitadas do
+        # caminho indicado, de forma irreversível, no worktree compartilhado — bloqueia
+        # quando '--' aparece em qualquer posição (forma explícita de pathspec) ou quando
+        # '.' aparece como token isolado. 'git checkout <branch>' sem nenhum dos dois
+        # segue liberado por decisão (distinguir branch de caminho sem '--' é ambíguo, e
+        # adivinhar produziria falso-positivo).
+        checkout_path=0
+        for tok2 in "$@"; do
+          case "$tok2" in
+            --|.)
+              checkout_path=1
+              ;;
+          esac
+        done
+        if [ "$checkout_path" = "1" ]; then
+          echo "checkout-path"
+          return 0
+        fi
         ;;
       switch)
         for tok2 in "$@"; do
@@ -1912,6 +2020,87 @@ match_subcommand() {
           esac
         done
         ;;
+      stash)
+        # git stash: liberado só para leitura (list/show) — bloqueia a forma bare
+        # (equivale a "push"), push, save, clear e drop. Decisão de KG: bloquear a
+        # classe inteira, não só os literais medidos (ver REQ). Repositório com um único
+        # worktree compartilhado entre subagentes paralelos — um stash de um agente
+        # remove as alterações não commitadas de todos os outros.
+        stash_sub="\${1:-}"
+        case "$stash_sub" in
+          list|show)
+            ;;
+          *)
+            echo "stash"
+            return 0
+            ;;
+        esac
+        ;;
+      reset)
+        # Só --hard bloqueia, em qualquer posição de token — --soft/--mixed (inclusive
+        # sem flag, que é --mixed implícito) seguem liberados: --soft é o contorno
+        # padrão para reempurrar trabalho staged via ` + "`" + `trackfw ship -m "..."` + "`" + ` (ainda falta commitar após --soft).
+        for tok2 in "$@"; do
+          case "$tok2" in
+            --hard)
+              echo "reset-hard"
+              return 0
+              ;;
+          esac
+        done
+        ;;
+      clean)
+        # Bloqueia qualquer forma com force (-f, -fd, -fx, --force) ou -x/-X, EXCETO
+        # quando -n/--dry-run também está presente (dry-run nunca apaga nada).
+        clean_dry=0
+        clean_force=0
+        for tok2 in "$@"; do
+          case "$tok2" in
+            -n|--dry-run)
+              clean_dry=1
+              ;;
+            -f*|--force|--force=*|-x|-X)
+              clean_force=1
+              ;;
+          esac
+        done
+        if [ "$clean_dry" != "1" ] && [ "$clean_force" = "1" ]; then
+          echo "clean-force"
+          return 0
+        fi
+        ;;
+      restore)
+        # git restore --staged SOZINHO nunca toca o working tree (mexe só no
+        # index), então segue liberado mesmo com path. Mas --worktree/-W (com ou
+        # sem --staged junto) SEMPRE afeta o working tree — inclusive
+        # "--staged --worktree", que restaura os dois — então bloqueia sempre que
+        # --worktree/-W aparecer, e também no caso padrão (sem --staged em
+        # nenhuma forma) com um argumento posicional (o path).
+        restore_staged=0
+        restore_worktree=0
+        restore_positional=0
+        for tok2 in "$@"; do
+          case "$tok2" in
+            --staged)
+              restore_staged=1
+              ;;
+            --worktree|-W)
+              restore_worktree=1
+              ;;
+            -*)
+              ;;
+            *)
+              restore_positional=1
+              ;;
+          esac
+        done
+        if [ "$restore_positional" = "1" ]; then
+          if [ "$restore_worktree" = "1" ] || [ "$restore_staged" != "1" ]; then
+            echo "restore-path"
+            return 0
+          fi
+        fi
+        ;;
       branch)
         # git branch é majoritariamente leitura (sem args, -a, -r, -l, --list, -v/-vv,
         # --show-current, --contains, --no-contains, --merged, --no-merged, --sort=,
@@ -1967,8 +2156,44 @@ match_subcommand() {
                 ;;
             esac
           done
+        elif [ "\${1:-}" = "remove" ]; then
+          # git worktree remove SEM -f/--force já recusa sozinho quando há alteração não
+          # commitada no worktree indicado — só a forma com force é irreversível o bastante
+          # para bloquear aqui.
+          shift
+          for tok2 in "$@"; do
+            case "$tok2" in
+              -f|--force)
+                echo "worktree-remove-force"
+                return 0
+                ;;
+            esac
+          done
         fi
         ;;
+      update-ref)
+        # git update-ref reescreve um ref (inclusive refs/remotes/origin/*) sem tocar o
+        # objeto apontado nem exigir push — foi o mecanismo que tornou alcançável o exploit
+        # descrito no ADR-2026-08-19-caminho-governado-para-push-forcado-e-tag-de-release.md
+        # (Emenda 1): forjar origin/<base> localmente para desviar o commit-alvo de trackfw
+        # release tag. Sem forma de leitura equivalente a bloquear seletivamente — a
+        # subcommand inteira é escrita — bloqueia sempre, sem exceção de token.
+        echo "update-ref"
+        return 0
+        ;;
+      rm)
+        # git rm -f/--force apaga do working tree e do index de forma irreversível, mesma
+        # classe de git clean -f/git reset --hard já bloqueados acima — sem exceção para
+        # --cached (destrancar do index sem -f já segue liberado por não precisar de force).
+        for tok2 in "$@"; do
+          case "$tok2" in
+            -f*|--force|--force=*)
+              echo "rm-force"
+              return 0
+              ;;
+          esac
+        done
+        ;;
     esac
   done <<EOF
 $normalized
@@ -1980,22 +2205,46 @@ SUBCOMMAND=$(match_subcommand "$CMD_RAW") || exit 0
 
 case "$SUBCOMMAND" in
   checkout-b)
-    REASON="trackfw: git checkout -b bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git checkout -b bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
     ;;
   switch-c)
-    REASON="trackfw: git switch -c bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git switch -c bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
     ;;
   branch-create)
-    REASON="trackfw: git branch bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git branch bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
     ;;
   worktree-add-b)
-    REASON="trackfw: git worktree add -b bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git worktree add -b bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_REF_BACKTICK + `. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
     ;;
   commit)
-    REASON="trackfw: git commit bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw commit -m '<mensagem>'` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git commit bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw commit -m '<mensagem>'` + GBG_REF_BACKTICK + `. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
     ;;
   push)
-    REASON="trackfw: git push bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw ship` + GBG_REF_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git push bruto bloqueado. Use ` + GBG_REF_BACKTICK + `trackfw push` + GBG_REF_BACKTICK + ` (para empurrar commits já criados), ` + GBG_REF_BACKTICK + `trackfw ship` + GBG_REF_BACKTICK + ` (para commit+push+PR em uma etapa) ou ` + GBG_REF_BACKTICK + `trackfw release tag` + GBG_REF_BACKTICK + ` (para publicar uma tag de release). Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  stash)
+    REASON="trackfw: git stash bruto bloqueado — worktree compartilhado entre subagentes, um stash remove as alterações não commitadas de todos os outros. ` + GBG_REF_BACKTICK + `git stash list` + GBG_REF_BACKTICK + `/` + GBG_REF_BACKTICK + `git stash show` + GBG_REF_BACKTICK + ` seguem liberados; para guardar trabalho em progresso, use uma branch própria via ` + GBG_REF_BACKTICK + `trackfw branch new` + GBG_REF_BACKTICK + ` e commit nela. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  reset-hard)
+    REASON="trackfw: git reset --hard bruto bloqueado — descarta de forma irreversível as alterações não commitadas de todo o worktree compartilhado. ` + GBG_REF_BACKTICK + `git reset --soft` + GBG_REF_BACKTICK + `/` + GBG_REF_BACKTICK + `--mixed` + GBG_REF_BACKTICK + ` seguem liberados (ex.: ` + GBG_REF_BACKTICK + `git reset --soft HEAD~1` + GBG_REF_BACKTICK + ` é o caminho padrão; use ` + GBG_REF_BACKTICK + `trackfw ship -m "..."` + GBG_REF_BACKTICK + ` para commitar e empurrar). Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  clean-force)
+    REASON="trackfw: git clean -f/-x bruto bloqueado — apaga arquivos não rastreados do worktree compartilhado, de forma irreversível. ` + GBG_REF_BACKTICK + `git clean -n` + GBG_REF_BACKTICK + `/` + GBG_REF_BACKTICK + `--dry-run` + GBG_REF_BACKTICK + ` segue liberado para revisar antes o que seria apagado. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  restore-path)
+    REASON="trackfw: git restore <path> bruto bloqueado — descarta de forma irreversível as alterações não commitadas do caminho indicado. ` + GBG_REF_BACKTICK + `git restore --staged` + GBG_REF_BACKTICK + ` (não toca o working tree) segue liberado; para descartar de fato, confirme antes com o usuário. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  checkout-path)
+    REASON="trackfw: git checkout -- <path>/git checkout . bruto bloqueado — descarta de forma irreversível as alterações não commitadas do caminho indicado. ` + GBG_REF_BACKTICK + `git checkout <branch>` + GBG_REF_BACKTICK + `/` + GBG_REF_BACKTICK + `git switch <branch>` + GBG_REF_BACKTICK + ` seguem liberados; para descartar de fato, confirme antes com o usuário. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  update-ref)
+    REASON="trackfw: git update-ref bruto bloqueado — reescreve um ref (inclusive refs/remotes/origin/*) sem tocar o objeto apontado nem exigir push, o que permite forjar o commit-alvo que ` + GBG_REF_BACKTICK + `trackfw release tag` + GBG_REF_BACKTICK + ` publicaria. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  worktree-remove-force)
+    REASON="trackfw: git worktree remove -f/--force bruto bloqueado — remove um worktree e descarta de forma irreversível qualquer alteração não commitada nele. ` + GBG_REF_BACKTICK + `git worktree remove` + GBG_REF_BACKTICK + ` sem force segue liberado (recusa sozinho quando há algo não commitado). Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
+    ;;
+  rm-force)
+    REASON="trackfw: git rm -f/--force bruto bloqueado — apaga arquivos do working tree e do index de forma irreversível, mesma classe de ` + GBG_REF_BACKTICK + `git clean -f` + GBG_REF_BACKTICK + `/` + GBG_REF_BACKTICK + `git reset --hard` + GBG_REF_BACKTICK + ` já bloqueados. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
     ;;
   *)
     exit 0
@@ -3021,6 +3270,14 @@ module.exports = {
   resolveAdrStatus,
   // ROADMAP-2026-08-12-mitigacao-do-fail-open-do-credential-guard, ML-1A
   resolveCredentialGuardHookPath,
+  // ADR-2026-08-22 (ML-1A): classificação por ancoragem
+  HOOK_ANCHORAGE_CLASS_ANCHORED,
+  HOOK_ANCHORAGE_CLASS_CWD_DEPENDENT,
+  HOOK_ANCHORAGE_CLASS_UNDECIDABLE,
+  stripOuterQuotesForClassify,
+  hookValueWasQuoted,
+  classifyHookAnchorage,
+  cwdDependentReason,
   collectCredentialGuardCommands,
   validateCredentialGuardHookResolvable,
   // ROADMAP-2026-08-12-deteccao-de-adulteracao-do-credential-guard-regra-de-validate, ML-1A