trackfw 7.1.0 → 7.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "description": "Governance CLI for AI-native software delivery and AI coding agents. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, Amazon Q, OpenCode, and Kiro.",
   "keywords": [
     "cli",

package/src/commands/commit.js

@@ -12,9 +12,13 @@ function createCommitCommand() {
   const cmd = new Command('commit')
   cmd
     .description(
-      "trackfw commit is the missing intermediate step between raw 'git commit' and\n" +
-      "'trackfw ship': it commits staged changes directly, but blocks the commit before it happens\n" +
-      'when governance is missing, instead of letting it land and only catching it later:\n\n' +
+      "trackfw commit commits staged changes directly, but blocks the commit before it\n" +
+      'happens when governance is missing, instead of letting it land and only catching it later.\n\n' +
+      'Compositional vocabulary:\n' +
+      '  trackfw commit -m "..."   commits\n' +
+      '  trackfw push              pushes\n' +
+      '  trackfw ship -m "..."     commit + push + PR (composition)\n\n' +
+      'Behavioral steps:\n\n' +
       "  1. On 'main'/'master': always blocked — commit directly on the default branch is never\n" +
       '     permitted.\n' +
       '  2. On a feat/fix/refactor branch: requires a roadmap matching the branch slug already in\n' +

package/src/commands/doctor.js

@@ -2,6 +2,7 @@
 
 const { Command } = require('commander')
 const { runDoctor, UNREGISTERED_WRITE, HAND_MODIFIED, UNKNOWN_CONTENT } = require('../integrations/doctor')
+const projectConfig = require('../config')
 
 function printReport(findings) {
   if (findings.length === 0) {
@@ -21,7 +22,7 @@ const cmd = new Command('doctor')
 cmd.description('Detect artifacts on disk missing from the manifest, distinguishing hand-modified artifacts from unknown content')
 cmd.option('--json', 'Emit findings as a JSON array instead of the text report')
 cmd.action(async options => {
-  const findings = runDoctor({})
+  const findings = runDoctor({ agentModels: projectConfig.load().agentModels || {} })
   if (options.json) {
     process.stdout.write(`${JSON.stringify(findings, null, 2)}\n`)
     return

package/src/commands/index.js

@@ -51,9 +51,11 @@ function createProgram() {
   program.addCommand(require('./skills'))
   program.addCommand(require('./note'))
   program.addCommand(require('./ship'))
+  program.addCommand(require('./release'))
   program.addCommand(require('./barrier'))
   program.addCommand(require('./branch'))
   program.addCommand(require('./commit'))
+  program.addCommand(require('./push'))
   program.addCommand(require('./doctor'))
 
   const { createServeCommand } = require('./serve')

package/src/commands/integrations.js

@@ -3,10 +3,13 @@
 const os = require('node:os')
 const { Command } = require('commander')
 const { catalog, execute, parseSurfaces, buildPlans } = require('../integrations')
+const { surfaceFor, readAsset } = require('../integrations/catalog')
+const { markdownParts, resolveAgentModel, looksLikeSuspectModelValue } = require('../integrations/render')
 const identityStore = require('../identity')
 const identityWizard = require('./identity-wizard')
 const { t } = require('../i18n')
 const { createThirdPartyCommand } = require('./thirdparty')
+const configModule = require('../config')
 
 const csv = value => String(value).split(',').map(entry => entry.trim()).filter(Boolean)
 const collect = (value, previous) => previous.concat(value)
@@ -124,6 +127,10 @@ function createLifecycleCommand(kind) {
   // internal/commands/integrations_flags.go registering `third-party` in
   // newIntegrationsLifecycleCmd.
   root.addCommand(createThirdPartyCommand(kind))
+  // "models" is agents-only: skills have no model field, and surfacing this
+  // under `trackfw skills models` would mislead users. Mirrors the identity
+  // flag gate and the Go/Python implementations.
+  if (kind === 'agents') root.addCommand(createAgentModelsCommand())
   for (const operation of ['list', 'install', 'uninstall', 'update']) {
     const mutation = operation !== 'list'
     const command = new Command(operation)
@@ -214,6 +221,7 @@ function createLifecycleCommand(kind) {
         }
       }
 
+      options.agentModels = configModule.load().agentModels || {}
       const output = execute(kind, operation, options)
       console.log(options.json ? JSON.stringify(output) : human(output))
     })
@@ -222,4 +230,58 @@ function createLifecycleCommand(kind) {
   return root
 }
 
-module.exports = { createLifecycleCommand, csv, human, promptSelection, promptAmbiguousSurfaces, resolveScope }
+// createAgentModelsCommand returns the "models" subcommand of "trackfw agents".
+// Lists, for each catalog agent × target pair, the model identifier that
+// install/update would write to the generated artifact. Mirrors
+// internal/commands/agents_models.go:newAgentModelsCmd and
+// pypi/trackfw/integrations/command.py:_run_models.
+//
+// Column widths must match Go and Python for byte-identical output.
+const MODELS_AGENT_WIDTH = 14
+const MODELS_TIER_WIDTH = 8
+const MODELS_TARGET_WIDTH = 12
+const MODELS_NA = '—'
+
+function pad(s, width) {
+  return String(s).padEnd(width)
+}
+
+function createAgentModelsCommand() {
+  const cmd = new Command('models')
+    .description('Show the resolved model each agent uses per target')
+  cmd.action(() => {
+    const agentModels = configModule.load().agentModels || {}
+
+    // Warnings: emit once per suspect tier, sorted, to stderr.
+    const suspectTiers = Object.keys(agentModels)
+      .filter(tier => looksLikeSuspectModelValue(agentModels[tier]))
+      .sort()
+    for (const tier of suspectTiers) {
+      process.stderr.write(
+        `WARN: agent_models.${tier} = ${JSON.stringify(agentModels[tier])} — not a version string and not a claude- model ID; will be written literally and may produce an invalid model identifier\n`
+      )
+    }
+
+    const lines = []
+    lines.push(`${pad('AGENT', MODELS_AGENT_WIDTH)} ${pad('TIER', MODELS_TIER_WIDTH)} ${pad('TARGET', MODELS_TARGET_WIDTH)} RESOLVED`)
+
+    for (const agent of catalog.agents) {
+      const source = readAsset(agent)
+      const parts = markdownParts(source)
+      const tier = parts.model || 'sonnet'
+
+      for (const target of catalog.targets) {
+        const surface = surfaceFor(target, null, 'agents')
+        const representation = surface.capabilities.agents.representation
+        const { resolved, present } = resolveAgentModel(tier, representation, target.id, agentModels)
+        const display = present ? resolved : MODELS_NA
+        lines.push(`${pad(agent.id, MODELS_AGENT_WIDTH)} ${pad(tier, MODELS_TIER_WIDTH)} ${pad(target.id, MODELS_TARGET_WIDTH)} ${display}`)
+      }
+    }
+
+    console.log(lines.join('\n'))
+  })
+  return cmd
+}
+
+module.exports = { createLifecycleCommand, createAgentModelsCommand, csv, human, promptSelection, promptAmbiguousSurfaces, resolveScope }

package/src/commands/push.js

@@ -0,0 +1,51 @@
+'use strict'
+
+const { Command } = require('commander')
+const { runPush } = require('../push/runner')
+const config = require('../config')
+
+function createPushCommand() {
+  const cmd = new Command('push')
+  cmd
+    .description(
+      'trackfw push pushes already-created commits without committing and without opening a PR/MR.\n\n' +
+      '  1. Validates branch name — must match feat|fix|refactor|chore|docs/<slug>\n' +
+      '  2. Validates governance — REQ + roadmap in wip/ must exist for feat/fix/refactor branches\n' +
+      '     (hard gate: not affected by lenient mode or per-rule severity); chore/docs branches skip\n' +
+      '     this check, mirroring \'trackfw commit\'\n' +
+      '  3. Detects pending squash-merges in other branches (advisory only)\n' +
+      '  4. Pushes to origin (adds -u if no upstream is configured yet)\n\n' +
+      'push never commits and never opens a PR/MR.\n' +
+      'Does not accept -m. If you have not committed yet, run \'trackfw commit -m "..."\' first.\n\n' +
+      'Compositional vocabulary:\n' +
+      '  trackfw commit -m "..."   commits\n' +
+      '  trackfw push              pushes\n' +
+      '  trackfw ship -m "..."     commit + push + PR (composition)\n\n' +
+      "--force-with-lease pushes with 'git push --force-with-lease' instead of a plain push — for\n" +
+      'the post-rebase case, where a plain push is rejected. It only runs when the branch already\n' +
+      "has an open PR/MR (verified via the resolved forge CLI): the safe path is always to open the\n" +
+      'PR first.'
+    )
+    .option('--dry-run', 'Print what would be done without executing write commands', false)
+    .option('--force-with-lease', 'Governed force-push (git push --force-with-lease); requires an open PR/MR on this branch', false)
+    .action((options) => {
+      const cfg = config.load()
+      const exitCode = runPush(
+        {
+          dryRun: options.dryRun || false,
+          forceWithLease: options.forceWithLease || false,
+        },
+        {
+          configForge: cfg.forge || '',
+          repoDir: '.',
+        }
+      )
+      if (exitCode !== 0) {
+        process.exit(exitCode)
+      }
+    })
+
+  return cmd
+}
+
+module.exports = createPushCommand()

package/src/commands/release.js

@@ -0,0 +1,47 @@
+'use strict'
+
+const { Command } = require('commander')
+const { runReleaseTag } = require('../release/runner')
+const config = require('../config')
+
+function createReleaseCommand() {
+  const cmd = new Command('release')
+  cmd.description('Governed release operations')
+
+  const tagCmd = new Command('tag')
+  tagCmd
+    .description(
+      'Create and publish an annotated release tag.\n\n' +
+      "It exists because 'trackfw ship' only pushes branches — tag is not a branch operation,\n" +
+      "and ship's governance gate (\"REQ + roadmap in wip/\") does not apply to release. See\n" +
+      'ADR-2026-08-19-caminho-governado-para-push-forcado-e-tag-de-release.md.\n\n' +
+      'Every precondition below refuses with a message naming what to fix — this command\n' +
+      'never guesses:\n' +
+      '  1. Working tree must be clean.\n' +
+      '  2. The default branch (main/master), if checked out locally, must be up to date with origin.\n' +
+      '  3. The 4 version files must all match <version> exactly.\n' +
+      '  4. CHANGELOG.md must have a "## [<version>] - YYYY-MM-DD" section.\n' +
+      '  5. The tag must not already exist, locally or on origin.\n' +
+      '  6. The GitHub CLI (gh) must be available and authenticated — release tag currently\n' +
+      '     only supports GitHub; other forges are refused with instructions to push the tag\n' +
+      '     manually.\n\n' +
+      'On success, it publishes the tag via two GitHub API calls (POST git/tags then POST\n' +
+      'git/refs), preserving the annotation.'
+    )
+    .argument('<version>', 'Version to tag (with or without a leading "v")')
+    .action((version) => {
+      const cfg = config.load()
+      const exitCode = runReleaseTag(version, {
+        configForge: cfg.forge || '',
+        repoDir: '.',
+      })
+      if (exitCode !== 0) {
+        process.exit(exitCode)
+      }
+    })
+
+  cmd.addCommand(tagCmd)
+  return cmd
+}
+
+module.exports = createReleaseCommand()

package/src/commands/ship.js

@@ -15,16 +15,23 @@ function createShipCommand() {
       "     this check, mirroring 'trackfw commit'\n" +
       '  3. Detects pending squash-merges in other branches (advisory only)\n' +
       '  4. Reviews what is staged (git status --short + git diff --cached --stat)\n' +
-      '  5. Commits with Conventional Commits format (-m is required)\n' +
+      '  5. Commits with Conventional Commits format (-m is required, unless nothing is staged\n' +
+      '     and --force-with-lease is set — see below)\n' +
       '  6. Pushes to origin (adds -u if no upstream is configured yet)\n' +
       '  7. Opens PR/MR via the resolved forge CLI (or prints URL if CLI is absent)\n\n' +
       "Stage your files explicitly before running ship.\n" +
-      "This command never executes 'git add .' or 'git add -A'."
+      "This command never executes 'git add .' or 'git add -A'.\n\n" +
+      "--force-with-lease pushes with 'git push --force-with-lease' instead of a plain push —\n" +
+      "for the post-rebase case, where a plain push is rejected. It only runs when the branch\n" +
+      "already has an open PR/MR (verified via the resolved forge CLI): the safe path is\n" +
+      "always to open the PR first. When nothing is staged, it pushes existing commits\n" +
+      "without requiring -m."
     )
     .option('-m, --message <msg>', 'Commit message (Conventional Commits format required)')
     .option('--dry-run', 'Print what would be done without executing write commands', false)
     .option('--no-pr', 'Skip PR/MR creation after push')
     .option('--forge <forge>', 'Override forge detection (github, gitlab, bitbucket, azure)', '')
+    .option('--force-with-lease', 'Governed force-push (git push --force-with-lease); requires an open PR/MR on this branch', false)
     .action((options) => {
       const cfg = config.load()
       const exitCode = runShip(
@@ -33,6 +40,7 @@ function createShipCommand() {
           dryRun: options.dryRun || false,
           noPR: options.pr === false,
           forge: options.forge || '',
+          forceWithLease: options.forceWithLease || false,
         },
         {
           configForge: cfg.forge || '',

package/src/commands/update-harness.js

@@ -4,6 +4,7 @@ const fs = require('fs')
 const os = require('os')
 const path = require('path')
 const identityStore = require('../identity')
+const projectConfig = require('../config')
 const { catalog, buildPlans, IntegrationManager, globalGroupPath } = require('../integrations')
 const { tildeify, validateTargets, buildDocument, humanReport, silenceConsole } = require('../lib/update-engine')
 const { mergeClaudeHookArray, mergeSimpleCommandArray, mergeCopilotHookArray, generateGlobalCredentialGuardScript, generateGlobalGitBranchGuardScript } = require('../generators/hooks')
@@ -757,7 +758,7 @@ function catalogBundleTarget(toolId, kind, homeRoot, identityConfig, { dryRun, i
   let displayPath = `~/.${toolId}`
   try {
     displayPath = globalGroupPath(toolId, kind)
-    const plans = buildPlans(kind, { targets: [toolId], scope: 'global', identity: identityConfig })
+    const plans = buildPlans(kind, { targets: [toolId], scope: 'global', identity: identityConfig, agentModels: projectConfig.load().agentModels || {} })
     if (!plans.length) return { id, state: 'missing', path: displayPath }
 
     const manager = new IntegrationManager({ homeRoot })

package/src/commands/update.js

@@ -151,7 +151,7 @@ function codexProjectAgentsTarget(cwd, identityConfig, { dryRun, installMissing
     const manager = new IntegrationManager({ projectRoot: cwd });
     let wroteAny = false;
     for (const kind of ['agents', 'skills']) {
-      const plans = buildPlans(kind, { targets: ['codex'], scope: 'project', identity: identityConfig });
+      const plans = buildPlans(kind, { targets: ['codex'], scope: 'project', identity: identityConfig, agentModels: projectConfig.load(cwd).agentModels || {} });
       const statuses = manager.inspect(plans);
       const toWrite = plans.filter((_, index) => {
         const state = statuses[index].state;

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',
@@ -278,6 +282,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 +313,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 +331,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 (_) {

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
@@ -1965,7 +2124,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 +2151,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

package/src/generators/init.js

@@ -723,6 +723,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')
 }

package/src/integrations/assets/agents/architect.md

@@ -44,4 +44,16 @@ Before releasing the next wave, verify each acceptance criterion yourself: read
 ## Mission
 Map the existing architecture and traceability chain before proposing changes. Record material decisions as ADRs, produce decision-complete plans, and delegate implementation to the appropriate specialist. Do not implement product code.
 
+## Response length
+
+Default: what changed · what I decided · what I need from you. Three to five lines.
+
+Scale up only on these three triggers, and only on them: a **blocker** that stops the next wave; a **pending user decision** that cannot be inferred from context; an **error I made** that cannot be self-corrected.
+
+Never cut, even when short: measured evidence (command and result), barrier verdict, decision taken and why. A response that buries a blocker in paragraph seven produced the same effect as not reporting it.
+
+Cut: restating what an executor already reported, re-explaining reasoning already given, recapping state that has not changed, closing praise. Tables and code blocks only when they replace prose, never when they add to it.
+
+Depth is on demand from the user.
+
 — Architect, Principal Software Architect