trackfw 7.1.0 → 7.3.0

package/src/commands/barrier.js

@@ -48,17 +48,20 @@ function resolveRoadmapFile(cfg, roadmapArg) {
 // recognised as a wave heading (neither valid nor malformed).
 const WAVE_SCAN_RE = /^## Wave (\S+) /
 
-// Grammar: <integer>[-<suffix>] where integer >= 1 and suffix is [a-z0-9]+ (lowercase).
-// Valid: 1, 2, 2-bis, 2-hotfix, 10-a2.
-// Invalid: X, 2-BIS, -bis, 2-, 2-bis-ter, 0.
+// Grammar: <integer>[-<suffix>] where integer >= 0 and suffix is [a-z0-9]+ (lowercase).
+// Valid: 0, 1, 2, 2-bis, 2-hotfix, 10-a2. 0 is the Wave 0 threat-model convention
+// (docs/cli-parity.md § "Wave label grammar").
+// Invalid: X, 2-BIS, -bis, 2-, 2-bis-ter.
 const WAVE_LABEL_RE = /^(\d+)(?:-([a-z0-9]+))?$/
 
 // isValidWaveLabel returns true iff token matches the grammar above.
 // Exported so unit tests can assert the full table of valid/invalid examples.
+// Shared by both guard points (the --wave flag validation and the heading
+// pre-pass in findWave) — a single function, unlike Go's two duplicated checks.
 function isValidWaveLabel(token) {
   const m = WAVE_LABEL_RE.exec(String(token))
   if (!m) return false
-  return parseInt(m[1], 10) >= 1
+  return parseInt(m[1], 10) >= 0
 }
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -224,7 +227,96 @@ function evalAcceptanceEvidence(mls) {
   return { name: 'acceptance_evidence', status, evidence, failures }
 }
 
-function evalGates(commands, cwd) {
+// ────────────────────────────────────────────────────────────────────────────
+// Roadmap trust check (AC11, AC12 — docs/cli-parity.md § Trust and --trust-local-gates)
+// ────────────────────────────────────────────────────────────────────────────
+
+// roadmapTrustForGates determines whether the gates declared in a roadmap can
+// be trusted for execution without --trust-local-gates.
+//
+// Decision (AC4, AC11): the discriminant is git — a roadmap whose content
+// differs from origin/main, or that is absent from origin/main, is untrusted.
+//
+// Returns { trusted: true } or { trusted: false, failureMsg: '...' }.
+// Fail-open when not in a git repo, origin/main not resolvable, or any git
+// error other than "path absent from origin/main". See docs/cli-parity.md.
+function roadmapTrustForGates(roadmapPath) {
+  const roadmapDir = path.dirname(roadmapPath)
+
+  // Step 1: check if we are inside a git repository.
+  const revParse = spawnSync('git', ['rev-parse', '--git-dir'], {
+    cwd: roadmapDir,
+    encoding: 'utf8',
+    stdio: 'pipe',
+  })
+  if (revParse.status !== 0) {
+    // Not a git repo → fail-open.
+    return { trusted: true }
+  }
+
+  // Step 2: get the repository toplevel.
+  const topLevel = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    cwd: roadmapDir,
+    encoding: 'utf8',
+    stdio: 'pipe',
+  })
+  if (topLevel.status !== 0) {
+    return { trusted: true }
+  }
+  const repoRoot = topLevel.stdout.trim()
+
+  // Step 3: compute repo-relative path (always forward slashes for git).
+  const absRoadmap = path.resolve(roadmapPath)
+  const relPath = path.relative(repoRoot, absRoadmap).split(path.sep).join('/')
+
+  // Step 4: retrieve the file at origin/main.
+  const show = spawnSync('git', ['show', `origin/main:${relPath}`], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    stdio: 'pipe',
+  })
+  if (show.status !== 0) {
+    // If the path specifically does not exist in origin/main → untrusted.
+    const stderr = show.stderr || ''
+    if (stderr.includes('does not exist in') || stderr.includes('exists on disk, but not in')) {
+      return {
+        trusted: false,
+        failureMsg: 'gates not evaluated: roadmap is not committed in origin/main — pass --trust-local-gates to evaluate local gates',
+      }
+    }
+    // Other failures (no remote, not fetched) → fail-open.
+    return { trusted: true }
+  }
+
+  // Step 5: compare content byte-for-byte.
+  let localContent
+  try {
+    localContent = fs.readFileSync(roadmapPath, 'utf8')
+  } catch (_) {
+    return { trusted: true }
+  }
+  if (show.stdout !== localContent) {
+    return {
+      trusted: false,
+      failureMsg: 'gates not evaluated: roadmap content differs from origin/main — pass --trust-local-gates to evaluate local gates',
+    }
+  }
+  return { trusted: true }
+}
+
+function evalGates(commands, cwd, trustResult = { trusted: true }) {
+  // trustResult: { trusted: true } | { trusted: false, failureMsg: string }
+  if (!trustResult.trusted) {
+    // Roadmap is not trusted: do not execute gates (AC3, AC14).
+    // Report as not_evaluated — distinct from passed and blocked (AC6).
+    return {
+      name: 'gates',
+      status: 'not_evaluated',
+      commands,
+      evidence: [],
+      failures: [trustResult.failureMsg],
+    }
+  }
   const evidence = []
   const failures = []
   for (const command of commands) {
@@ -303,7 +395,7 @@ function printTextReport(doc) {
 // Command
 // ────────────────────────────────────────────────────────────────────────────
 
-async function runBarrier(roadmapArg, waveOption, jsonOutput) {
+async function runBarrier(roadmapArg, waveOption, jsonOutput, trustLocalGates) {
   if (waveOption === undefined || waveOption === null || String(waveOption).trim() === '') {
     throw new UsageError('--wave is required')
   }
@@ -322,10 +414,15 @@ async function runBarrier(roadmapArg, waveOption, jsonOutput) {
   const mls = findMLs(lines, wave.startLine, wave.endLine)
   const gates = parseGates(lines, wave.startLine, wave.endLine)
 
+  // Determine trust for gate execution (AC11, AC12).
+  const trustResult = trustLocalGates
+    ? { trusted: true }
+    : roadmapTrustForGates(resolved.path)
+
   const checks = []
   checks.push(evalMlsComplete(mls, waveLabel))
   checks.push(evalAcceptanceEvidence(mls))
-  checks.push(evalGates(gates.commands, process.cwd()))
+  checks.push(evalGates(gates.commands, process.cwd(), trustResult))
   checks.push(await evalValidate())
   const finishedAt = new Date()
 
@@ -351,9 +448,10 @@ function createBarrierCommand() {
     .argument('<roadmap>', 'Roadmap basename, with or without .md')
     .option('--wave <label>', 'Wave label to evaluate (e.g. 1, 2-bis, 2-hotfix)')
     .option('--json', 'Emit the result document as JSON instead of a text report')
+    .option('--trust-local-gates', 'Trust the local roadmap content for gate execution without comparing to origin/main (used by the /trackfw:barrier slash command for WIP roadmaps)')
     .action(async (roadmapArg, options) => {
       try {
-        const exitCode = await runBarrier(roadmapArg, options.wave, !!options.json)
+        const exitCode = await runBarrier(roadmapArg, options.wave, !!options.json, !!options.trustLocalGates)
         process.exit(exitCode)
       } catch (err) {
         if (err instanceof UsageError) {
@@ -378,6 +476,7 @@ module.exports.findMLs = findMLs
 module.exports.mlCompletionStatus = mlCompletionStatus
 module.exports.mlAcceptanceEvidence = mlAcceptanceEvidence
 module.exports.parseGates = parseGates
+module.exports.roadmapTrustForGates = roadmapTrustForGates
 module.exports.evalMlsComplete = evalMlsComplete
 module.exports.evalAcceptanceEvidence = evalAcceptanceEvidence
 module.exports.evalGates = evalGates

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,15 +2,23 @@
 
 const { Command } = require('commander')
 const { runDoctor, UNREGISTERED_WRITE, HAND_MODIFIED, UNKNOWN_CONTENT } = require('../integrations/doctor')
+const { runScaffoldDoctor, SCAFFOLD_DIVERGENT, SCAFFOLD_MISSING, SCAFFOLD_WRONG_MODE } = require('../integrations/scaffold_doctor')
+const projectConfig = require('../config')
 
 function printReport(findings) {
   if (findings.length === 0) {
-    return 'trackfw doctor: no mismatches found -- disk matches the manifest for every catalog-managed artifact.'
+    return 'trackfw doctor: no mismatches found -- disk matches the manifest for every catalog-managed artifact and all scaffold templates.'
   }
   const unregistered = findings.filter(finding => finding.finding === UNREGISTERED_WRITE).length
   const handModified = findings.filter(finding => finding.finding === HAND_MODIFIED).length
   const unknownContent = findings.filter(finding => finding.finding === UNKNOWN_CONTENT).length
-  const lines = [`trackfw doctor: ${findings.length} finding(s) -- ${unregistered} unregistered-write, ${handModified} hand-modified, ${unknownContent} unknown-content`, '']
+  const scaffoldDivergent = findings.filter(finding => finding.finding === SCAFFOLD_DIVERGENT).length
+  const scaffoldMissing = findings.filter(finding => finding.finding === SCAFFOLD_MISSING).length
+  const scaffoldWrongMode = findings.filter(finding => finding.finding === SCAFFOLD_WRONG_MODE).length
+  const lines = [
+    `trackfw doctor: ${findings.length} finding(s) -- ${unregistered} unregistered-write, ${handModified} hand-modified, ${unknownContent} unknown-content, ${scaffoldDivergent} scaffold-divergent, ${scaffoldMissing} scaffold-missing, ${scaffoldWrongMode} scaffold-wrong-mode`,
+    '',
+  ]
   for (const finding of findings) {
     lines.push(`[${finding.finding}] ${finding.destination}`, `  remedy: ${finding.remedy}`, '')
   }
@@ -21,7 +29,13 @@ 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 projectRoot = process.cwd()
+  const catalogFindings = runDoctor({ agentModels: projectConfig.load().agentModels || {} })
+  // Scaffold coverage (ADR-2026-08-27): compare scaffold artifacts on disk against
+  // the templates the current binary would generate, using the project's own
+  // trackfw.yaml. No manifest entry is written or read (AC3).
+  const scaffoldFindings = runScaffoldDoctor(projectRoot)
+  const findings = [...catalogFindings, ...scaffoldFindings]
   if (options.json) {
     process.stdout.write(`${JSON.stringify(findings, null, 2)}\n`)
     return

package/src/commands/index.js

@@ -51,10 +51,13 @@ 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'))
+  program.addCommand(require('./audit-surface'))
 
   const { createServeCommand } = require('./serve')
   program.addCommand(createServeCommand())

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,9 @@ function createLifecycleCommand(kind) {
         }
       }
 
+      const { models: resolvedModels, warning: modelsWarning } = configModule.resolveAgentModels(options.scope, os.homedir(), process.cwd())
+      if (modelsWarning) process.stderr.write(modelsWarning + '\n')
+      options.agentModels = resolvedModels
       const output = execute(kind, operation, options)
       console.log(options.json ? JSON.stringify(output) : human(output))
     })
@@ -222,4 +232,73 @@ 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(() => {
+    // AC5 + AC11: read agent_models from the global config (~/.trackfw/trackfw.yaml),
+    // not from the cwd singleton. Show origin before the table.
+    const { models: agentModels, source: modelsSource } = configModule.loadGlobalAgentModels(os.homedir(), process.cwd())
+
+    // Source line (AC5): show origin before the table; advisory to stderr when not resolved.
+    const sourceLines = {
+      global: 'source: ~/.trackfw/trackfw.yaml',
+      none: 'source: não configurado',
+      project_only: 'source: trackfw.yaml do projeto (não vale para escopo global)',
+      global_malformed: 'source: arquivo global malformado',
+    }
+    const sourceLine = sourceLines[modelsSource] || sourceLines['none']
+    process.stdout.write(sourceLine + '\n')
+    if (modelsSource === 'none') process.stderr.write(configModule.GLOBAL_AGENT_MODELS_NONE_MESSAGE + '\n')
+    else if (modelsSource === 'project_only') process.stderr.write(configModule.GLOBAL_AGENT_MODELS_PROJECT_ONLY_MESSAGE + '\n')
+    else if (modelsSource === 'global_malformed') process.stderr.write(configModule.MALFORMED_GLOBAL_CONFIG_MESSAGE + '\n')
+
+    // 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/thirdparty.js

@@ -6,8 +6,11 @@
 // `trackfw skills third-party` (D1). See:
 // docs/adr/ADR-2026-08-15-gate-de-duas-fases-para-artefatos-de-terceiro-quarentena-parecer-vinculado-por-checksum-e-deteccao-por-proveniencia-versionada.md
 
+const os = require('os')
+
 const { Command } = require('commander')
 
+const configModule = require('../config')
 const identityStore = require('../identity')
 const { items: catalogItems } = require('../integrations/catalog')
 const { buildPlans, IntegrationManager } = require('../integrations')
@@ -186,13 +189,15 @@ async function executeThirdPartyInstall(kind, options) {
   // write happens (including the skill file below) — failing everything up
   // front avoids leaving a partial state (skill file written, no reference
   // injected) on a precondition failure.
+  const { models: resolvedAgentModels, warning: agentModelsWarning } = configModule.resolveAgentModels(scope, os.homedir(), projectRoot)
+  if (agentModelsWarning) process.stderr.write(agentModelsWarning + '\n')
   let identityConfig
   if (options.applyTo && options.applyTo.length) {
     identityConfig = identityStore.load(manager.roots.global)
     for (const agentID of options.applyTo) {
       if (!catalogItems('agents').some(item => item.id === agentID)) throw new Error(`unknown agent item "${agentID}"`)
       for (const rt of resolvedTargets) {
-        const agentPlans = buildPlans('agents', { targets: [rt.targetID], items: [agentID], scope, identity: identityConfig, projectRoot })
+        const agentPlans = buildPlans('agents', { targets: [rt.targetID], items: [agentID], scope, identity: identityConfig, projectRoot, agentModels: resolvedAgentModels })
         if (!agentPlans.length) throw new Error(`target ${rt.targetID} has no supported agents surface for item "${agentID}"`)
         const inspection = manager.inspect([agentPlans[0]])[0]
         // ADR imprecision found and resolved here (reported, not silently
@@ -333,7 +338,7 @@ async function executeThirdPartyInstall(kind, options) {
         // immediately — not only on the next `agents update`. buildPlans
         // picks up the registry entry just written via
         // applyThirdPartyReferences (../integrations/index.js).
-        const agentPlans = buildPlans('agents', { targets: [rt.targetID], items: [agentID], scope, identity: identityConfig, projectRoot })
+        const agentPlans = buildPlans('agents', { targets: [rt.targetID], items: [agentID], scope, identity: identityConfig, projectRoot, agentModels: resolvedAgentModels })
         manager.update(agentPlans, {})
       }
     }

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,9 @@ 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 { models: harnessAgentModels, warning: harnessWarnMsg } = projectConfig.resolveAgentModels('global', homeRoot, process.cwd())
+    if (harnessWarnMsg) process.stderr.write(harnessWarnMsg + '\n')
+    const plans = buildPlans(kind, { targets: [toolId], scope: 'global', identity: identityConfig, agentModels: harnessAgentModels })
     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;
@@ -200,6 +200,10 @@ function buildProjectTargets(cwd, cfg, identityConfig, { dryRun, installMissing
     path: 'CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .windsurfrules, .amazonq/developer/guidelines.md, .cursor/rules/trackfw.mdc',
     root: cwd,
     relPaths: ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md', '.github/copilot-instructions.md', '.windsurfrules', '.amazonq/developer/guidelines.md', '.cursor/rules/trackfw.mdc'],
+    // Gap E: injectRulesDetected → readAgentConventions reads trackfw.yaml from root;
+    // without it in the dry-run sandbox, agent_conventions is silently omitted from
+    // CLAUDE.md, producing a hash that diverges from the real run.
+    seeds: ['trackfw.yaml'],
     apply: (root) => generators.injectRulesDetected(root),
     dryRun,
     installMissing,
@@ -207,7 +211,7 @@ function buildProjectTargets(cwd, cfg, identityConfig, { dryRun, installMissing
 
   if (include('agent-hooks')) targets.push(runFileTarget({
     id: 'agent-hooks',
-    path: '.claude/settings.json, .codex/hooks.json, .gemini/settings.json, .kiro/hooks/trackfw-attention.json, .github/hooks/trackfw-attention.json, .cursor/hooks.json, scripts/trackfw-attention-*.sh, scripts/trackfw-credential-guard.sh, scripts/trackfw-git-branch-guard.sh',
+    path: '.claude/settings.json, .codex/hooks.json, .gemini/settings.json, .kiro/hooks/trackfw-attention.json, .github/hooks/trackfw-attention.json, .cursor/hooks.json, scripts/trackfw-attention-*.sh, scripts/trackfw-credential-guard.sh, scripts/trackfw-git-branch-guard.sh, .windsurf/hooks.json, .amazonq/cli-agents/q_cli_default.json',
     root: cwd,
     relPaths: [
       '.claude/settings.json',
@@ -220,6 +224,21 @@ function buildProjectTargets(cwd, cfg, identityConfig, { dryRun, installMissing
       'scripts/trackfw-attention-cleanup.sh',
       'scripts/trackfw-credential-guard.sh',
       'scripts/trackfw-git-branch-guard.sh',
+      '.windsurf/hooks.json',                   // Gap A: injectWindsurfHooks writes this
+      '.amazonq/cli-agents/q_cli_default.json', // Gap B: injectAmazonQHooks writes this
+    ],
+    // Gap C: injectHooksDetected checks these files to decide which hooks to
+    // inject. Without them in the dry-run sandbox, hooks for installed agents
+    // (windsurf, copilot, etc.) are silently omitted — dry-run lies by omission.
+    // Gap E: trackfw.yaml may be read by hooks generators for config.
+    seeds: [
+      'trackfw.yaml',
+      'CLAUDE.md',
+      'AGENTS.md',
+      'GEMINI.md',
+      '.github/copilot-instructions.md',
+      '.windsurfrules',
+      '.amazonq/developer/guidelines.md',
     ],
     apply: (root) => {
       hooksGen.injectHooksDetected(root);