trackfw 7.1.0 → 7.3.0

package/src/config/index.js

@@ -65,6 +65,10 @@ function defaults() {
     credentialGuard: {
       mode: 'warn',
     },
+    // agent_models field — see ADR-2026-08-21-versao-do-modelo-por-tier-com-composicao-por-alvo.md.
+    // Maps tier name (e.g. "opus", "sonnet") to version string (e.g. "5", "4.6").
+    // Absent or empty map → behavior identical to today (tier alias used verbatim).
+    agentModels: {},
     rules: {
       wip_has_req:          'error',
       wip_acceptance:       'error',
@@ -82,6 +86,21 @@ function defaults() {
 
 let _instance = null;
 
+// MALFORMED_GLOBAL_CONFIG_MESSAGE is written to stderr (non-fatal) when ~/.trackfw/trackfw.yaml
+// exists but fails to parse as valid YAML. Must be byte-identical to Go's MalformedGlobalConfigMessage
+// and Python's MALFORMED_GLOBAL_CONFIG_MESSAGE — ADR-2026-08-23.
+const MALFORMED_GLOBAL_CONFIG_MESSAGE = 'trackfw: aviso: "~/.trackfw/trackfw.yaml" tem YAML malformado — config global de modelo ignorada; usando tier canônico.';
+
+// GLOBAL_AGENT_MODELS_NONE_MESSAGE is emitted to stderr when agent_models is not configured
+// in the global config and not found in cwd's trackfw.yaml either.
+// Must be byte-identical to Go's GlobalAgentModelsNoneMessage and Python's equivalent.
+const GLOBAL_AGENT_MODELS_NONE_MESSAGE = 'trackfw: agents global: agent_models não configurado em ~/.trackfw/trackfw.yaml — usando tier canônico. Configure em ~/.trackfw/trackfw.yaml para pinar versões.';
+
+// GLOBAL_AGENT_MODELS_PROJECT_ONLY_MESSAGE is emitted when agent_models is found in the
+// project's trackfw.yaml but not in the global config (AC4/AC14). Value NOT applied.
+// Must be byte-identical to Go's GlobalAgentModelsProjectOnlyMessage and Python's equivalent.
+const GLOBAL_AGENT_MODELS_PROJECT_ONLY_MESSAGE = 'trackfw: agents global: agent_models configurado em trackfw.yaml do projeto mas não vale para escopo global. Mova a chave para ~/.trackfw/trackfw.yaml.';
+
 // MALFORMED_CONFIG_MESSAGE is written to stderr, verbatim, when trackfw.yaml exists but fails to
 // parse as YAML. Kept identical, character-for-character, to Go's MalformedConfigMessage and
 // Python's MALFORMED_CONFIG_MESSAGE — see the comment on parse() below for why the text is
@@ -278,6 +297,17 @@ function parse(content, cfg) {
     if (mode === 'warn' || mode === 'block') cfg.credentialGuard.mode = mode;
   }
 
+  // agent_models field — flat mapping from tier name to version string.
+  // See ADR-2026-08-21-versao-do-modelo-por-tier-com-composicao-por-alvo.md.
+  // An absent, malformed, or empty block leaves agentModels as the empty object from defaults(),
+  // preserving identical behavior to today. A key with an empty string value is stored as-is
+  // (the render layer treats empty string as "no pin" — fall back to tier alias).
+  if (m.agent_models !== undefined && typeof m.agent_models === 'object' && !Array.isArray(m.agent_models)) {
+    for (const [k, v] of Object.entries(m.agent_models)) {
+      if (typeof v === 'string') cfg.agentModels[k] = v;
+    }
+  }
+
   return false;
 }
 
@@ -298,7 +328,7 @@ function parseRulesFromContent(content) {
   // never creates them) — so this cannot be a bare { rules: {} } literal or parse() throws on any
   // content that sets one of those nested keys. rules starts empty (not seeded from defaults()),
   // deliberately: the caller wants exactly what `rules:` in content declares, nothing else.
-  const cfg = { rules: {}, credentialGuard: {}, update: {}, sync: {}, linkFields: {} };
+  const cfg = { rules: {}, credentialGuard: {}, update: {}, sync: {}, linkFields: {}, agentModels: {} };
   parse(content, cfg);
   return cfg.rules;
 }
@@ -316,7 +346,7 @@ function readAgentConventions(cwd) {
   } catch (_) {
     return '';
   }
-  const cfg = { rules: {}, credentialGuard: {}, update: { agentConventions: '' }, sync: {}, linkFields: {} };
+  const cfg = { rules: {}, credentialGuard: {}, update: { agentConventions: '' }, sync: {}, linkFields: {}, agentModels: {} };
   try {
     parse(content, cfg);
   } catch (_) {
@@ -325,6 +355,65 @@ function readAgentConventions(cwd) {
   return cfg.update.agentConventions || '';
 }
 
+// _cwdAgentModelsSource returns 'project_only' if cwd's trackfw.yaml has agent_models configured,
+// 'none' otherwise. Used for the AC14 diagnostic in loadGlobalAgentModels.
+function _cwdAgentModelsSource(cwd) {
+  if (!cwd) return 'none';
+  try {
+    const cwdContent = fs.readFileSync(path.join(cwd, 'trackfw.yaml'), 'utf8');
+    const cwdCfg = { rules: {}, credentialGuard: {}, update: {}, sync: {}, linkFields: {}, agentModels: {} };
+    parse(cwdContent, cwdCfg);
+    if (cwdCfg.agentModels && Object.keys(cwdCfg.agentModels).length > 0) return 'project_only';
+  } catch (_) {}
+  return 'none';
+}
+
+// loadGlobalAgentModels reads agent_models from ~/.trackfw/trackfw.yaml, bypassing the load()
+// singleton. homeDir is os.homedir(); cwd is process.cwd() (used only for AC14 diagnostic).
+// Returns { models: {}, source } where source is one of:
+//   'global'            — agent_models resolved from ~/.trackfw/trackfw.yaml
+//   'none'              — global config absent or has no agent_models; cwd also has none
+//   'project_only'      — agent_models in cwd's trackfw.yaml but not global (AC14 trigger)
+//   'global_malformed'  — ~/.trackfw/trackfw.yaml exists but has invalid YAML (AC12 trigger)
+// Never calls process.exit. Pattern mirrors readAgentConventions above.
+function loadGlobalAgentModels(homeDir, cwd) {
+  const globalPath = path.join(homeDir, '.trackfw', 'trackfw.yaml');
+  let data;
+  try {
+    data = fs.readFileSync(globalPath, 'utf8');
+  } catch (_) {
+    return { models: {}, source: _cwdAgentModelsSource(cwd) };
+  }
+  // Validate YAML (non-fatal for global config, per AC12).
+  const globalCfg = { rules: {}, credentialGuard: {}, update: {}, sync: {}, linkFields: {}, agentModels: {} };
+  const malformed = parse(data, globalCfg);
+  if (malformed) {
+    return { models: {}, source: 'global_malformed' };
+  }
+  if (globalCfg.agentModels && Object.keys(globalCfg.agentModels).length > 0) {
+    return { models: globalCfg.agentModels, source: 'global' };
+  }
+  // Global file exists but has no agent_models → check cwd (AC14).
+  return { models: {}, source: _cwdAgentModelsSource(cwd) };
+}
+
+// resolveAgentModels returns { models, warning } for the given scope.
+// For global scope, reads from ~/.trackfw/trackfw.yaml via loadGlobalAgentModels.
+// For project scope, reads from the cwd's trackfw.yaml via load().
+// warning is a non-empty string when the caller should emit an advisory to stderr.
+// resolveAgentModels never writes to stderr itself.
+function resolveAgentModels(scope, homeDir, cwd) {
+  if (scope !== 'global') {
+    return { models: load().agentModels || {}, warning: '' };
+  }
+  const { models, source } = loadGlobalAgentModels(homeDir, cwd);
+  let warning = '';
+  if (source === 'none') warning = GLOBAL_AGENT_MODELS_NONE_MESSAGE;
+  else if (source === 'project_only') warning = GLOBAL_AGENT_MODELS_PROJECT_ONLY_MESSAGE;
+  else if (source === 'global_malformed') warning = MALFORMED_GLOBAL_CONFIG_MESSAGE;
+  return { models, warning };
+}
+
 const NAMESPACING_FLAT = 'flat';
 const NAMESPACING_BY_AGENT = 'by_agent';
 
@@ -335,7 +424,12 @@ module.exports = {
   expandPath,
   parseRulesFromContent,
   readAgentConventions,
+  loadGlobalAgentModels,
+  resolveAgentModels,
   NAMESPACING_FLAT,
   NAMESPACING_BY_AGENT,
   MALFORMED_CONFIG_MESSAGE,
+  MALFORMED_GLOBAL_CONFIG_MESSAGE,
+  GLOBAL_AGENT_MODELS_NONE_MESSAGE,
+  GLOBAL_AGENT_MODELS_PROJECT_ONLY_MESSAGE,
 };

package/src/generators/hooks.js

@@ -769,6 +769,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
@@ -780,6 +798,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=,
@@ -835,8 +934,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
@@ -848,22 +983,46 @@ SUBCOMMAND=$(match_subcommand "$CMD_RAW") || exit 0
 
 case "$SUBCOMMAND" in
   checkout-b)
-    REASON="trackfw: git checkout -b bruto bloqueado. Use ` + GBG_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git checkout -b bruto bloqueado. Use ` + GBG_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_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_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git switch -c bruto bloqueado. Use ` + GBG_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_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_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git branch bruto bloqueado. Use ` + GBG_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_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_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git worktree add -b bruto bloqueado. Use ` + GBG_BACKTICK + `trackfw branch new <type>/<slug>` + GBG_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_BACKTICK + `trackfw commit -m '<mensagem>'` + GBG_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git commit bruto bloqueado. Use ` + GBG_BACKTICK + `trackfw commit -m '<mensagem>'` + GBG_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_BACKTICK + `trackfw ship` + GBG_BACKTICK + `. Ver CLAUDE.md §1."
+    REASON="trackfw: git push bruto bloqueado. Use ` + GBG_BACKTICK + `trackfw push` + GBG_BACKTICK + ` (para empurrar commits já criados), ` + GBG_BACKTICK + `trackfw ship` + GBG_BACKTICK + ` (para commit+push+PR em uma etapa) ou ` + GBG_BACKTICK + `trackfw release tag` + GBG_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_BACKTICK + `git stash list` + GBG_BACKTICK + `/` + GBG_BACKTICK + `git stash show` + GBG_BACKTICK + ` seguem liberados; para guardar trabalho em progresso, use uma branch própria via ` + GBG_BACKTICK + `trackfw branch new` + GBG_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_BACKTICK + `git reset --soft` + GBG_BACKTICK + `/` + GBG_BACKTICK + `--mixed` + GBG_BACKTICK + ` seguem liberados (ex.: ` + GBG_BACKTICK + `git reset --soft HEAD~1` + GBG_BACKTICK + ` é o caminho padrão; use ` + GBG_BACKTICK + `trackfw ship -m "..."` + GBG_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_BACKTICK + `git clean -n` + GBG_BACKTICK + `/` + GBG_BACKTICK + `--dry-run` + GBG_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_BACKTICK + `git restore --staged` + GBG_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_BACKTICK + `git checkout <branch>` + GBG_BACKTICK + `/` + GBG_BACKTICK + `git switch <branch>` + GBG_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_BACKTICK + `trackfw release tag` + GBG_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_BACKTICK + `git worktree remove` + GBG_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_BACKTICK + `git clean -f` + GBG_BACKTICK + `/` + GBG_BACKTICK + `git reset --hard` + GBG_BACKTICK + ` já bloqueados. Nada antes deste comando foi executado (comando composto é bloqueado por inteiro). Ver CLAUDE.md §1."
     ;;
   *)
     exit 0
@@ -888,6 +1047,8 @@ function generateGitBranchGuardScript(cwd) {
 
   const scriptPath = path.join(scriptsDir, 'trackfw-git-branch-guard.sh')
   fs.writeFileSync(scriptPath, GIT_BRANCH_GUARD_SCRIPT, { encoding: 'utf8', mode: 0o755 })
+  // AC9: chmodSync restores execute bit on existing files.
+  fs.chmodSync(scriptPath, 0o755)
 
   console.log('  ✓ scripts/trackfw-git-branch-guard.sh')
 }
@@ -925,6 +1086,8 @@ function generateCredentialGuardScript(cwd) {
 
   const scriptPath = path.join(scriptsDir, 'trackfw-credential-guard.sh')
   fs.writeFileSync(scriptPath, CREDENTIAL_GUARD_SCRIPT, { encoding: 'utf8', mode: 0o755 })
+  // AC9: chmodSync restores execute bit on existing files.
+  fs.chmodSync(scriptPath, 0o755)
 
   console.log('  ✓ scripts/trackfw-credential-guard.sh')
 }
@@ -1330,9 +1493,14 @@ function generateAttentionScripts(cfg, cwd) {
 
   const signalPath = path.join(scriptsDir, 'trackfw-attention-signal.sh')
   fs.writeFileSync(signalPath, SIGNAL_SCRIPT, { encoding: 'utf8', mode: 0o755 })
+  // AC9 (REQ-2026-08-28): chmodSync restores the execute bit on existing files
+  // where writeFileSync's {mode} option has no effect (applies only on O_CREAT).
+  fs.chmodSync(signalPath, 0o755)
 
   const cleanupPath = path.join(scriptsDir, 'trackfw-attention-cleanup.sh')
   fs.writeFileSync(cleanupPath, CLEANUP_SCRIPT, { encoding: 'utf8', mode: 0o755 })
+  // AC9: same rationale as signalPath above.
+  fs.chmodSync(cleanupPath, 0o755)
 
   console.log('  ✓ scripts/trackfw-attention-signal.sh')
   console.log('  ✓ scripts/trackfw-attention-cleanup.sh')
@@ -1965,7 +2133,17 @@ function injectWindsurfHooks(cwd) {
 // written on first creation so the default agent keeps today's unrestricted
 // tool access (this fix does not narrow what any agent can do, only where
 // the deny wiring lives). Mirrors Go's InjectAmazonQHooks
-// (internal/generators/agentfiles.go) field-for-field.
+// (internal/generators/agentfiles.go) field-for-field -- Go is the
+// canonical set (ROADMAP-2026-08-20, ML-1A-bis): only `name`, `description`
+// and `tools` are written on first creation. `prompt`/`mcpServers`/
+// `toolAliases`/`allowedTools`/`resources`/`useLegacyMcpJson` were written
+// here until ML-1A-bis and are now deliberately NOT written -- an extra
+// field the real schema doesn't expect risks failing validation, whereas an
+// absent optional field usually doesn't (asymmetry-of-risk decision, not a
+// verification against the live Amazon Q schema -- see docs/cli-parity.md
+// for the recorded limit). Pre-existing occurrences of the dropped fields
+// in a user's file are left untouched (never removed, only no longer
+// created).
 //
 // Native custom-agent toolset restriction (REQ acceptance criterion): still
 // NOT implemented here -- this ML only wires the guard/deny fields on the
@@ -1982,13 +2160,7 @@ function injectAmazonQHooks(cwd) {
   const defaults = {
     name: 'q_cli_default',
     description: 'trackfw-managed default agent — wires the git branch guard hook/denylist. See docs/cli-parity.md.',
-    prompt: null,
-    mcpServers: {},
     tools: ['*'],
-    toolAliases: {},
-    allowedTools: [],
-    resources: [],
-    useLegacyMcpJson: false,
   }
   for (const [k, v] of Object.entries(defaults)) {
     if (!Object.prototype.hasOwnProperty.call(data, k)) data[k] = v
@@ -2092,4 +2264,13 @@ module.exports = {
   mergeCopilotHookArray,
   normalizeGuardPath,
   samePathCommand,
+  // Template constants — exported for scaffold doctor (ADR-2026-08-27).
+  // These are the single source of truth for each script's content; the
+  // scaffold doctor compares on-disk files against these exact bytes, using
+  // the same constants the write path uses, so drift between the comparison
+  // and the generator is structurally impossible.
+  SIGNAL_SCRIPT,
+  CLEANUP_SCRIPT,
+  CREDENTIAL_GUARD_SCRIPT,
+  GIT_BRANCH_GUARD_SCRIPT,
 }

package/src/generators/init.js

@@ -123,6 +123,10 @@ function generateValidateScript(cfg, cwd) {
   const script = buildValidateScript(cfg)
   const scriptPath = path.join(root, 'scripts', 'trackfw-validate.sh')
   fs.writeFileSync(scriptPath, script, { encoding: 'utf8', mode: 0o755 })
+  // AC9 (REQ-2026-08-28): writeFileSync's {mode} option applies only on O_CREAT;
+  // for an existing file the mode is not changed. fs.chmodSync restores 0o755
+  // unconditionally, matching Python's os.chmod behavior (which was already correct).
+  fs.chmodSync(scriptPath, 0o755)
   console.log(`  ✓ ${path.join('scripts', 'trackfw-validate.sh')}`)
 }
 
@@ -201,10 +205,13 @@ function generateCIWorkflow(cfg) {
   }
 }
 
-function generateGitHubActionsWorkflow() {
-  fs.mkdirSync('.github/workflows', { recursive: true })
-
-  const content = `name: trackfw-gate
+// buildGitHubActionsWorkflowContent returns the byte-identical content the GitHub Actions
+// workflow generator would write. Exported for scaffold doctor (ADR-2026-08-27): the
+// comparison uses the same function the write path uses, so drift is structurally impossible.
+// The cfg parameter is accepted for API symmetry with Go's buildGitHubActionsWorkflowContent
+// (which also ignores cfg for now — the template is not cfg-dependent).
+function buildGitHubActionsWorkflowContent(_cfg) {
+  return `name: trackfw-gate
 on:
   pull_request:
     branches: [main]
@@ -222,14 +229,11 @@ jobs:
       - name: Governance gate
         run: trackfw validate
 `
-
-  const filePath = '.github/workflows/trackfw-gate.yml'
-  fs.writeFileSync(filePath, content, 'utf8')
-  console.log(`  ✓ ${filePath}`)
 }
 
-function generateGitLabCIWorkflow() {
-  const content = `# trackfw governance gate
+// buildGitLabCIWorkflowContent mirrors buildGitHubActionsWorkflowContent for GitLab CI.
+function buildGitLabCIWorkflowContent(_cfg) {
+  return `# trackfw governance gate
 trackfw-gate:
   stage: test
   image: alpine:latest
@@ -241,8 +245,17 @@ trackfw-gate:
   only:
     - merge_requests
 `
+}
 
-  fs.writeFileSync('.gitlab-ci-trackfw.yml', content, 'utf8')
+function generateGitHubActionsWorkflow() {
+  fs.mkdirSync('.github/workflows', { recursive: true })
+  const filePath = '.github/workflows/trackfw-gate.yml'
+  fs.writeFileSync(filePath, buildGitHubActionsWorkflowContent(null), 'utf8')
+  console.log(`  ✓ ${filePath}`)
+}
+
+function generateGitLabCIWorkflow() {
+  fs.writeFileSync('.gitlab-ci-trackfw.yml', buildGitLabCIWorkflowContent(null), 'utf8')
   console.log('  ✓ .gitlab-ci-trackfw.yml')
 }
 
@@ -452,7 +465,7 @@ Delete the file when resolved. Visible as a live banner in \`trackfw serve\`.
 - **Docker + .env from day 1:** containerize early; all config via env vars
 - **2-layer validation:** frontend (UX) + backend (security) — never only one
 - **API-first:** define OpenAPI contract before coding frontend/backend integration
-- **Security wave:** include a red-team review wave in every feature roadmap
+- **Threat model waves:** every feature roadmap opens with a Wave 0 threat model (before implementation) and closes with a red-team review wave (before release)
 - **Test coverage:** TDD for critical logic; min 60% (prototype) / 80% (production)
 - Use \`/trackfw:architect\` to define stack before the first REQ
 ` + conventionsSection + `
@@ -723,6 +736,18 @@ function generateClaudeMD(cfg) {
   content += 'Decide low-risk details autonomously following existing project conventions, '
   content += 'and record autonomous decisions in the commit message.\n'
 
+  content += '\n## Architect responses\n\n'
+  content += 'Default: what changed · what was decided · what is needed from you. Three to five lines.\n\n'
+  content += 'Scale up only on these three triggers, and only on them: a **blocker** that stops the next wave; '
+  content += 'a **pending user decision** that cannot be inferred from context; '
+  content += 'an **error the architect made** that cannot be self-corrected.\n\n'
+  content += 'Never cut, even when short: measured evidence (command and result), barrier verdict, decision taken and why. '
+  content += 'A response that buries a blocker in paragraph seven produced the same effect as not reporting it.\n\n'
+  content += 'Cut: restating what an executor already reported, re-explaining reasoning already given, '
+  content += 'recapping state that has not changed, closing praise. '
+  content += 'Tables and code blocks only when they replace prose, never when they add to it.\n\n'
+  content += 'Depth is on demand from the user.\n'
+
   injectOrUpdateRules('CLAUDE.md', content, '.')
   console.log('  ✓ CLAUDE.md')
 }
@@ -843,7 +868,7 @@ trackfw não está instalado. Instale com:
 3. **Gerar o roadmap**
    Com base no conteúdo da REQ, gere um roadmap seguindo **estritamente** este formato:
 
-   \`\`\`markdown
+   \`\`\`\`markdown
    ---
    status: backlog
    date: <YYYY-MM-DD>
@@ -858,6 +883,28 @@ trackfw não está instalado. Instale com:
    ## Diagnóstico / Contexto
    <resumo do problema, motivação e escopo extraídos da REQ>
 
+   ## Wave 0 — Threat Model
+   > Dependencies: none. Blocks all implementation.
+
+   ### ML-0A — Threat model for this roadmap
+   **Status:** pending
+   **Files affected:**
+   **Actions:**
+   1. Enumeration completeness — is the list of surfaces in this roadmap complete? Name what is missing, or show the list is closed. Do not limit the search to the files already named by the REQ — before declaring the list closed, search the repository for other places that emit the same artifact or the same pattern (for example, grep for the literal the final artifact contains).
+   2. Threat model — who empties this Wave 0 without breaking any written rule, and how?
+   3. Falsification targets in both directions — for each surface, what breaks when the behavior regresses, and what breaks when it regresses the opposite way?
+   4. Declared residual — what this design accepts not covering.
+   **Acceptance criteria:**
+   - [ ] The four sections above answered with evidence, not a one-line assertion
+   - [ ] No implementation line written for this ML
+
+   **Gates da wave:**
+   \`\`\`bash
+   # Wave 0 gate — replace this placeholder with a project-specific check before
+   # marking ML-0A done. Do not remove the gate; replace its command (AC13).
+   exit 1  # placeholder gate fails closed until ML-0A replaces it — see docs/cli-parity.md
+   \`\`\`
+
    ## Wave 1 — <nome descritivo> (<N> MLs em paralelo)
    > Dependências: Independente
 
@@ -878,7 +925,7 @@ trackfw não está instalado. Instale com:
    ## Wave 2 — <nome> (depende de Wave 1)
    > Dependências: Wave 1 completa
    ...
-   \`\`\`
+   \`\`\`\`
 
    **Princípios obrigatórios:**
    - MLs dentro da mesma Wave são **independentes** (arquivos distintos, sem conflito)
@@ -1020,9 +1067,19 @@ Próximo passo: abrir PR com gh pr create
 
 Execute primeiro:
 \`\`\`bash
-trackfw barrier <roadmap> --wave <n> --json
+trackfw barrier <roadmap> --wave <n> --trust-local-gates --json
 \`\`\`
 
+\`--trust-local-gates\` é obrigatório aqui: roadmaps WIP (modificados localmente, ainda não commitados em
+\`origin/main\`) são marcados como não confiáveis pela CLI direta por padrão, como proteção contra a
+execução de gates de roadmaps chegados por PR de terceiro. O slash command aplica esse flag porque
+ele representa o fluxo legítimo do arquiteto operando no próprio repositório — não porque os gates
+são inspecionados previamente (o diff ainda é responsabilidade do checklist abaixo).
+
+⚠️ **Não use \`--trust-local-gates\` ao revisar um roadmap chegado por PR de terceiro** — use a CLI
+direta sem o flag (\`trackfw barrier <roadmap> --wave <n> --json\`) para que os gates sejam marcados
+como \`not_evaluated\` e não executados.
+
 Este comando é **necessário mas não suficiente**. Ele verifica MLs concluídos, evidências e \`trackfw validate\`, mas não substitui as inspeções especializadas nem a auditoria de diff abaixo — nenhuma delas é avaliada pelo binário. Consulte a seção \`trackfw barrier\` em \`docs/cli-parity.md\` para o contrato completo (estados, exit codes, saída JSON).
 
 Se o comando retornar exit code não-zero (\`blocked\` ou erro de resolução): pare, reporte a falha ao usuário e não prossiga no checklist até que a wave passe.
@@ -1246,8 +1303,11 @@ async function installAmazonQ(cwd = process.cwd()) {
  */
 async function installIntegrationTarget(target, cwd = process.cwd(), scope = 'project', { onSkip } = {}) {
   const { execute, buildPlans } = require('../integrations')
+  const { resolveAgentModels } = require('../config')
+  const { models: agentModels, warning: agentModelsWarning } = resolveAgentModels(scope, os.homedir(), cwd)
+  if (agentModelsWarning) process.stderr.write(agentModelsWarning + '\n')
   const roots = { projectRoot: cwd }
-  const options = { targets: [target], scope, onSkip }
+  const options = { targets: [target], scope, onSkip, agentModels }
   // D5 — transparency: print resolved destinations before writing anything.
   // buildPlans has no side effects, so it is safe to call here purely to
   // enumerate destinations; the actual write happens below via execute().
@@ -1371,4 +1431,12 @@ module.exports = {
   injectHooksDetected,
   trackfwRulesBlock,
   printArchitectNextSteps,
+  // Template constants and builders — exported for scaffold doctor (ADR-2026-08-27).
+  // Same single-source-of-truth principle as hooks.js exports: comparing against the
+  // same object the write path uses makes drift structurally impossible.
+  CLAUDE_COMMANDS,
+  buildValidateScript,
+  // CI workflow content builders (inline content from generateGitHub/GitLabCIWorkflow)
+  buildGitHubActionsWorkflowContent,
+  buildGitLabCIWorkflowContent,
 }