trackfw 7.2.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/doctor.js

@@ -2,16 +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}`, '')
   }
@@ -22,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({ agentModels: projectConfig.load().agentModels || {} })
+  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

@@ -57,6 +57,7 @@ function createProgram() {
   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

@@ -221,7 +221,9 @@ function createLifecycleCommand(kind) {
         }
       }
 
-      options.agentModels = configModule.load().agentModels || {}
+      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))
     })
@@ -250,7 +252,22 @@ function createAgentModelsCommand() {
   const cmd = new Command('models')
     .description('Show the resolved model each agent uses per target')
   cmd.action(() => {
-    const agentModels = configModule.load().agentModels || {}
+    // 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)

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

@@ -758,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, agentModels: projectConfig.load().agentModels || {} })
+    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

@@ -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);

package/src/config/index.js

@@ -86,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
@@ -340,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';
 
@@ -350,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

@@ -1047,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')
 }
@@ -1084,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')
 }
@@ -1489,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')
@@ -2255,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,
 }