trackfw 7.0.0 → 7.2.0

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')
@@ -462,6 +463,288 @@ function credentialGuardTargetKiro(homeRoot, { dryRun, installMissing }) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// git-branch-guard global-scope wiring (ROADMAP-2026-08-17 Wave 2/ML-2A).
+// Mirrors the six credentialGuardTarget<Tool> functions above, entry-for-
+// entry — same 4-state contract, same displayPath per tool, same reuse of
+// mergeClaudeHookArray/mergeSimpleCommandArray/mergeCopilotHookArray (those
+// helpers only need a scriptPath, which here is trackfw-git-branch-guard.sh
+// instead of trackfw-credential-guard.sh). Mirrors
+// internal/generators/update.go:harnessGitBranchGuardTarget<Tool>.
+//
+// Kiro is the one structural exception: credentialGuardTargetKiro rewrites
+// ~/.kiro/hooks/trackfw-credential-guard.json WHOLESALE every run (never
+// merges), so sharing that file with a second wholesale writer would make
+// the two targets flap between each other's desired 2-entry document forever
+// (idempotency failure). gitBranchGuardTargetKiro therefore writes its OWN
+// dedicated file, ~/.kiro/hooks/trackfw-git-branch-guard.json, same
+// {"version":"v1","hooks":[pre,post]} schema, hook names
+// "trackfw-git-branch-guard-global-pre"/"-global-post".
+// ---------------------------------------------------------------------------
+
+function gitBranchGuardTargetClaude(homeRoot, { dryRun, installMissing }) {
+  const id = 'claude-git-branch-guard'
+  const filePath = path.join(homeRoot, '.claude', 'settings.json')
+  const displayPath = tildeify(homeRoot, filePath)
+  const scriptPath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-git-branch-guard.sh')
+
+  let root
+  let raw = null
+  try {
+    if (fs.existsSync(filePath)) {
+      raw = fs.readFileSync(filePath, 'utf8')
+      root = raw.length ? JSON.parse(raw) : {}
+    } else {
+      if (!installMissing) return { id, state: 'missing', path: displayPath }
+      if (dryRun) return { id, state: 'updated', path: displayPath }
+      root = {}
+      if (!root.hooks) root.hooks = {}
+      root.hooks.PreToolUse = mergeClaudeHookArray(root.hooks.PreToolUse, 'Bash', scriptPath)
+      root.hooks.PostToolUse = mergeClaudeHookArray(root.hooks.PostToolUse, 'Bash', scriptPath)
+      const desired = JSON.stringify(root, null, 2) + '\n'
+      fs.mkdirSync(path.dirname(filePath), { recursive: true })
+      fs.writeFileSync(filePath, desired, 'utf8')
+      return { id, state: 'updated', path: displayPath }
+    }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+
+  try {
+    if (!root.hooks) root.hooks = {}
+    root.hooks.PreToolUse = mergeClaudeHookArray(root.hooks.PreToolUse, 'Bash', scriptPath)
+    root.hooks.PostToolUse = mergeClaudeHookArray(root.hooks.PostToolUse, 'Bash', scriptPath)
+    const desired = JSON.stringify(root, null, 2) + '\n'
+    if (desired === raw) return { id, state: 'skipped', path: displayPath }
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+function gitBranchGuardTargetCodex(homeRoot, { dryRun, installMissing }) {
+  const id = 'codex-git-branch-guard'
+  const filePath = path.join(homeRoot, '.codex', 'hooks.json')
+  const displayPath = tildeify(homeRoot, filePath)
+  const scriptPath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-git-branch-guard.sh')
+
+  let root
+  let raw = null
+  try {
+    if (fs.existsSync(filePath)) {
+      raw = fs.readFileSync(filePath, 'utf8')
+      root = raw.length ? JSON.parse(raw) : {}
+    } else {
+      if (!installMissing) return { id, state: 'missing', path: displayPath }
+      if (dryRun) return { id, state: 'updated', path: displayPath }
+      root = {}
+      if (!root.hooks) root.hooks = {}
+      root.hooks.PreToolUse = mergeClaudeHookArray(root.hooks.PreToolUse, 'Bash', scriptPath)
+      root.hooks.PostToolUse = mergeClaudeHookArray(root.hooks.PostToolUse, 'Bash', scriptPath)
+      const desired = JSON.stringify(root, null, 2) + '\n'
+      fs.mkdirSync(path.dirname(filePath), { recursive: true })
+      fs.writeFileSync(filePath, desired, 'utf8')
+      return { id, state: 'updated', path: displayPath }
+    }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+
+  try {
+    if (!root.hooks) root.hooks = {}
+    root.hooks.PreToolUse = mergeClaudeHookArray(root.hooks.PreToolUse, 'Bash', scriptPath)
+    root.hooks.PostToolUse = mergeClaudeHookArray(root.hooks.PostToolUse, 'Bash', scriptPath)
+    const desired = JSON.stringify(root, null, 2) + '\n'
+    if (desired === raw) return { id, state: 'skipped', path: displayPath }
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+function gitBranchGuardTargetGemini(homeRoot, { dryRun, installMissing }) {
+  const id = 'gemini-git-branch-guard'
+  const filePath = path.join(homeRoot, '.gemini', 'settings.json')
+  const displayPath = tildeify(homeRoot, filePath)
+  const scriptPath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-git-branch-guard.sh')
+
+  let root
+  let raw = null
+  try {
+    if (fs.existsSync(filePath)) {
+      raw = fs.readFileSync(filePath, 'utf8')
+      root = raw.length ? JSON.parse(raw) : {}
+    } else {
+      if (!installMissing) return { id, state: 'missing', path: displayPath }
+      if (dryRun) return { id, state: 'updated', path: displayPath }
+      root = {}
+      if (!root.hooks) root.hooks = {}
+      root.hooks.BeforeTool = mergeClaudeHookArray(root.hooks.BeforeTool, 'run_shell_command', scriptPath)
+      root.hooks.AfterTool = mergeClaudeHookArray(root.hooks.AfterTool, 'run_shell_command', scriptPath)
+      const desired = JSON.stringify(root, null, 2) + '\n'
+      fs.mkdirSync(path.dirname(filePath), { recursive: true })
+      fs.writeFileSync(filePath, desired, 'utf8')
+      return { id, state: 'updated', path: displayPath }
+    }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+
+  try {
+    if (!root.hooks) root.hooks = {}
+    root.hooks.BeforeTool = mergeClaudeHookArray(root.hooks.BeforeTool, 'run_shell_command', scriptPath)
+    root.hooks.AfterTool = mergeClaudeHookArray(root.hooks.AfterTool, 'run_shell_command', scriptPath)
+    const desired = JSON.stringify(root, null, 2) + '\n'
+    if (desired === raw) return { id, state: 'skipped', path: displayPath }
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+function gitBranchGuardTargetCursor(homeRoot, { dryRun, installMissing }) {
+  const id = 'cursor-git-branch-guard'
+  const filePath = path.join(homeRoot, '.cursor', 'hooks.json')
+  const displayPath = tildeify(homeRoot, filePath)
+  const scriptPath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-git-branch-guard.sh')
+
+  let root
+  let raw = null
+  try {
+    if (fs.existsSync(filePath)) {
+      raw = fs.readFileSync(filePath, 'utf8')
+      root = raw.length ? JSON.parse(raw) : {}
+    } else {
+      if (!installMissing) return { id, state: 'missing', path: displayPath }
+      if (dryRun) return { id, state: 'updated', path: displayPath }
+      root = {}
+      if (typeof root.version === 'undefined') root.version = 1
+      if (!root.hooks) root.hooks = {}
+      root.hooks.beforeShellExecution = mergeSimpleCommandArray(root.hooks.beforeShellExecution, scriptPath)
+      root.hooks.afterShellExecution = mergeSimpleCommandArray(root.hooks.afterShellExecution, scriptPath)
+      const desired = JSON.stringify(root, null, 2) + '\n'
+      fs.mkdirSync(path.dirname(filePath), { recursive: true })
+      fs.writeFileSync(filePath, desired, 'utf8')
+      return { id, state: 'updated', path: displayPath }
+    }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+
+  try {
+    if (typeof root.version === 'undefined') root.version = 1
+    if (!root.hooks) root.hooks = {}
+    root.hooks.beforeShellExecution = mergeSimpleCommandArray(root.hooks.beforeShellExecution, scriptPath)
+    root.hooks.afterShellExecution = mergeSimpleCommandArray(root.hooks.afterShellExecution, scriptPath)
+    const desired = JSON.stringify(root, null, 2) + '\n'
+    if (desired === raw) return { id, state: 'skipped', path: displayPath }
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+function gitBranchGuardTargetCopilot(homeRoot, { dryRun, installMissing }) {
+  const id = 'copilot-git-branch-guard'
+  const filePath = path.join(homeRoot, '.copilot', 'settings.json')
+  const displayPath = tildeify(homeRoot, filePath)
+  const scriptPath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-git-branch-guard.sh')
+
+  let root
+  let raw = null
+  try {
+    if (fs.existsSync(filePath)) {
+      raw = fs.readFileSync(filePath, 'utf8')
+      root = raw.length ? JSON.parse(raw) : {}
+    } else {
+      if (!installMissing) return { id, state: 'missing', path: displayPath }
+      if (dryRun) return { id, state: 'updated', path: displayPath }
+      root = {}
+      if (!root.hooks) root.hooks = {}
+      root.hooks.preToolUse = mergeCopilotHookArray(root.hooks.preToolUse, scriptPath)
+      root.hooks.postToolUse = mergeCopilotHookArray(root.hooks.postToolUse, scriptPath)
+      const desired = JSON.stringify(root, null, 2) + '\n'
+      fs.mkdirSync(path.dirname(filePath), { recursive: true })
+      fs.writeFileSync(filePath, desired, 'utf8')
+      return { id, state: 'updated', path: displayPath }
+    }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+
+  try {
+    if (!root.hooks) root.hooks = {}
+    root.hooks.preToolUse = mergeCopilotHookArray(root.hooks.preToolUse, scriptPath)
+    root.hooks.postToolUse = mergeCopilotHookArray(root.hooks.postToolUse, scriptPath)
+    const desired = JSON.stringify(root, null, 2) + '\n'
+    if (desired === raw) return { id, state: 'skipped', path: displayPath }
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
+// gitBranchGuardTargetKiro writes a DEDICATED file,
+// ~/.kiro/hooks/trackfw-git-branch-guard.json — deliberately NOT
+// credentialGuardTargetKiro's file. See this section's header comment for
+// why sharing would break idempotency.
+function gitBranchGuardTargetKiro(homeRoot, { dryRun, installMissing }) {
+  const id = 'kiro-git-branch-guard'
+  const filePath = path.join(homeRoot, '.kiro', 'hooks', 'trackfw-git-branch-guard.json')
+  const displayPath = tildeify(homeRoot, filePath)
+  const scriptPath = path.join(homeRoot, '.trackfw', 'scripts', 'trackfw-git-branch-guard.sh')
+
+  const desired = JSON.stringify(
+    {
+      version: 'v1',
+      hooks: [
+        {
+          name: 'trackfw-git-branch-guard-global-pre',
+          description: 'Blocks branch-creation git subcommands issued outside trackfw branch new (global, all trackfw projects)',
+          trigger: 'PreToolUse',
+          matcher: 'shell',
+          action: { type: 'command', command: scriptPath },
+        },
+        {
+          name: 'trackfw-git-branch-guard-global-post',
+          description: 'Warns on branch-creation git subcommands issued outside trackfw branch new (global, all trackfw projects)',
+          trigger: 'PostToolUse',
+          matcher: 'shell',
+          action: { type: 'command', command: scriptPath },
+        },
+      ],
+    },
+    null,
+    2
+  ) + '\n'
+
+  try {
+    const exists = fs.existsSync(filePath)
+    const actual = exists ? fs.readFileSync(filePath, 'utf8') : null
+
+    if (!exists && !installMissing) return { id, state: 'missing', path: displayPath }
+    if (exists && actual === desired) return { id, state: 'skipped', path: displayPath }
+
+    if (dryRun) return { id, state: 'updated', path: displayPath }
+
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, desired, 'utf8')
+    return { id, state: 'updated', path: displayPath }
+  } catch (e) {
+    return { id, state: 'failed', path: displayPath, message: e.message }
+  }
+}
+
 // catalogBundleTarget — one target per (tool, kind) pair at global scope.
 // Uses IntegrationManager.inspect (read-only) to classify every catalog
 // item under that pair, then only calls manager.update() for the subset
@@ -475,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 })
@@ -506,18 +789,20 @@ function catalogBundleTarget(toolId, kind, homeRoot, identityConfig, { dryRun, i
 }
 
 // HARNESS_TARGET_IDS — mirrors internal/generators/update.go:HarnessTargetIDs.
-// "codex-credential-guard"/"gemini-credential-guard" are each inserted
-// immediately BEFORE their tool's "-agents"/"-skills" pair (same relative
-// position as claude-credential-guard, which precedes claude-agents/
-// claude-skills) — see buildHarnessTargetIDs's comment in update.go for the
-// full rationale.
-const HARNESS_TARGET_IDS = ['claude-skill', 'claude-credential-guard']
+// "codex-credential-guard"/"codex-git-branch-guard",
+// "gemini-credential-guard"/"gemini-git-branch-guard", etc. are each
+// inserted immediately BEFORE their tool's "-agents"/"-skills" pair (same
+// relative position as claude-credential-guard/claude-git-branch-guard,
+// which precede claude-agents/claude-skills), with credential-guard always
+// preceding git-branch-guard within a tool — see buildHarnessTargetIDs's
+// comment in update.go for the full rationale.
+const HARNESS_TARGET_IDS = ['claude-skill', 'claude-credential-guard', 'claude-git-branch-guard']
 for (const target of catalog.targets) {
-  if (target.id === 'codex') HARNESS_TARGET_IDS.push('codex-credential-guard')
-  if (target.id === 'gemini') HARNESS_TARGET_IDS.push('gemini-credential-guard')
-  if (target.id === 'cursor') HARNESS_TARGET_IDS.push('cursor-credential-guard')
-  if (target.id === 'copilot') HARNESS_TARGET_IDS.push('copilot-credential-guard')
-  if (target.id === 'kiro') HARNESS_TARGET_IDS.push('kiro-credential-guard')
+  if (target.id === 'codex') HARNESS_TARGET_IDS.push('codex-credential-guard', 'codex-git-branch-guard')
+  if (target.id === 'gemini') HARNESS_TARGET_IDS.push('gemini-credential-guard', 'gemini-git-branch-guard')
+  if (target.id === 'cursor') HARNESS_TARGET_IDS.push('cursor-credential-guard', 'cursor-git-branch-guard')
+  if (target.id === 'copilot') HARNESS_TARGET_IDS.push('copilot-credential-guard', 'copilot-git-branch-guard')
+  if (target.id === 'kiro') HARNESS_TARGET_IDS.push('kiro-credential-guard', 'kiro-git-branch-guard')
   HARNESS_TARGET_IDS.push(`${target.id}-agents`, `${target.id}-skills`)
 }
 
@@ -531,22 +816,38 @@ function buildHarnessTargets(homeRoot, identityConfig, { dryRun, installMissing
   const targets = []
   if (include('claude-skill')) targets.push(claudeSkillTarget(homeRoot, { dryRun, installMissing }))
   if (include('claude-credential-guard')) targets.push(credentialGuardTargetClaude(homeRoot, { dryRun, installMissing }))
+  if (include('claude-git-branch-guard')) targets.push(gitBranchGuardTargetClaude(homeRoot, { dryRun, installMissing }))
   for (const target of catalog.targets) {
     if (target.id === 'codex' && include('codex-credential-guard')) {
       targets.push(credentialGuardTargetCodex(homeRoot, { dryRun, installMissing }))
     }
+    if (target.id === 'codex' && include('codex-git-branch-guard')) {
+      targets.push(gitBranchGuardTargetCodex(homeRoot, { dryRun, installMissing }))
+    }
     if (target.id === 'gemini' && include('gemini-credential-guard')) {
       targets.push(credentialGuardTargetGemini(homeRoot, { dryRun, installMissing }))
     }
+    if (target.id === 'gemini' && include('gemini-git-branch-guard')) {
+      targets.push(gitBranchGuardTargetGemini(homeRoot, { dryRun, installMissing }))
+    }
     if (target.id === 'cursor' && include('cursor-credential-guard')) {
       targets.push(credentialGuardTargetCursor(homeRoot, { dryRun, installMissing }))
     }
+    if (target.id === 'cursor' && include('cursor-git-branch-guard')) {
+      targets.push(gitBranchGuardTargetCursor(homeRoot, { dryRun, installMissing }))
+    }
     if (target.id === 'copilot' && include('copilot-credential-guard')) {
       targets.push(credentialGuardTargetCopilot(homeRoot, { dryRun, installMissing }))
     }
+    if (target.id === 'copilot' && include('copilot-git-branch-guard')) {
+      targets.push(gitBranchGuardTargetCopilot(homeRoot, { dryRun, installMissing }))
+    }
     if (target.id === 'kiro' && include('kiro-credential-guard')) {
       targets.push(credentialGuardTargetKiro(homeRoot, { dryRun, installMissing }))
     }
+    if (target.id === 'kiro' && include('kiro-git-branch-guard')) {
+      targets.push(gitBranchGuardTargetKiro(homeRoot, { dryRun, installMissing }))
+    }
     const agentsId = `${target.id}-agents`
     const skillsId = `${target.id}-skills`
     if (include(agentsId)) targets.push(catalogBundleTarget(target.id, 'agents', homeRoot, identityConfig, { dryRun, installMissing }))
@@ -627,4 +928,10 @@ module.exports = {
   credentialGuardTargetCursor,
   credentialGuardTargetCopilot,
   credentialGuardTargetKiro,
+  gitBranchGuardTargetClaude,
+  gitBranchGuardTargetCodex,
+  gitBranchGuardTargetGemini,
+  gitBranchGuardTargetCursor,
+  gitBranchGuardTargetCopilot,
+  gitBranchGuardTargetKiro,
 }

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 (_) {