trackfw 7.2.0 → 7.4.0

package/src/commands/update.js

@@ -7,6 +7,7 @@ const path = require('path');
 const identityStore = require('../identity');
 const projectConfig = require('../config');
 const { runFileTarget, validateTargets, buildDocument, humanReport, silenceConsole } = require('../lib/update-engine');
+const { homedir } = require('../homedir')
 
 // `trackfw update` is project-scoped only — see docs/cli-parity.md,
 // "`trackfw update` vs `trackfw update harness`". It must NEVER touch global
@@ -37,7 +38,7 @@ function loadUpdateConfig(rootDir) {
 // (line-based text splice, not a YAML parse+reserialize) to preserve 100% of
 // the user's existing trackfw.yaml content (comments, key order, formatting).
 function ensureGlobalAdrDirRegistered(cwd) {
-  const home = os.homedir();
+  const home = homedir();
   const globalDir = path.join(home, '.trackfw', 'adr');
   if (!fs.existsSync(globalDir)) return;
 
@@ -168,10 +169,74 @@ function codexProjectAgentsTarget(cwd, identityConfig, { dryRun, installMissing
   }
 }
 
+// discoverWorkflowPresent — reports whether
+// .github/workflows/trackfw-validate.yml (written by `trackfw discover
+// --init`, DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH in discover.js) already
+// exists under cwd AS A REGULAR FILE. Used both to decide whether
+// `ci-workflow` is declared (AC17(c), REQ-2026-08-28) and, inside its
+// apply(), to decide whether to refresh it — existence is checked against
+// the REAL cwd, never the --dry-run sandbox, mirroring how cfg itself is
+// read before the sandbox is built.
+//
+// Uses fs.lstatSync, NOT fs.existsSync: fs.existsSync follows symlinks, so a
+// symlink at this path — even a live one pointing outside the project —
+// would report "present" purely because its target resolves, pulling
+// `ci-workflow` into the declared target set on the strength of a link this
+// command does not own. Symlinks are therefore treated as NOT present here:
+// `update` will not declare/manage a target on their account, and
+// refreshDiscoverGitHubActionsWorkflowIfPresent below refuses to write
+// through them regardless.
+function discoverWorkflowPresent(cwd) {
+  const { DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH } = require('./discover')
+  const dest = path.join(cwd, DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH)
+  let info
+  try {
+    info = fs.lstatSync(dest)
+  } catch (e) {
+    return false
+  }
+  return !info.isSymbolicLink()
+}
+
+// refreshDiscoverGitHubActionsWorkflowIfPresent — refreshes
+// .github/workflows/trackfw-validate.yml ONLY when it already exists under
+// root as a REGULAR FILE — `update` never creates this file (AC17(b)):
+// ownership of the install decision belongs to `trackfw discover --init`,
+// not `update`. Writes the SAME builder scaffold doctor compares against
+// (buildDiscoverGitHubActionsWorkflowContent, discover.js) so what `update`
+// writes and what `doctor` expects can never drift apart by construction.
+//
+// Uses fs.lstatSync to decide presence, not fs.existsSync: this path is the
+// most sensitive one `update` can write to (it controls what runs in CI for
+// anyone who checks the project out), so if it is a symlink — live or
+// dangling — this function refuses to write through it. Refusing is loud
+// (stderr), never silent, so "update didn't refresh my workflow" stays
+// diagnosable instead of a silent no-op.
+function refreshDiscoverGitHubActionsWorkflowIfPresent(root) {
+  const { DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH, buildDiscoverGitHubActionsWorkflowContent } = require('./discover')
+  const dest = path.join(root, DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH)
+  let info
+  try {
+    info = fs.lstatSync(dest)
+  } catch (e) {
+    return // not installed — update never creates it (AC17(b))
+  }
+  if (info.isSymbolicLink()) {
+    console.error(`aviso: ${DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH} é um symlink; trackfw update não escreve através de symlinks — arquivo não foi tocado`)
+    return
+  }
+  fs.writeFileSync(dest, buildDiscoverGitHubActionsWorkflowContent(), 'utf8')
+}
+
 // PROJECT_TARGET_IDS — the fixed declared order for `trackfw update`
 // targets. `ci-workflow` and `git-hooks` only appear when the project's
-// trackfw.yaml opted into a CI system / hook framework — see ambiguity
-// note in the ML-6C handoff report about config-conditional target lists.
+// trackfw.yaml opted into a CI system / hook framework, OR — for
+// `ci-workflow` only — when trackfw-validate.yml already exists on disk
+// (AC17(c)) — see ambiguity note in the ML-6C handoff report about
+// config-conditional target lists. This constant is the full declared
+// surface (used to validate --targets); the config/disk-conditional
+// inclusion itself lives in buildProjectTargets' `include('ci-workflow')`
+// call below.
 const PROJECT_TARGET_IDS = [
   'agent-rules',
   'agent-hooks',
@@ -189,7 +254,6 @@ const PROJECT_TARGET_IDS = [
 // filtering afterwards would still have written every unrequested target.
 function buildProjectTargets(cwd, cfg, identityConfig, { dryRun, installMissing }, wanted) {
   const generators = require('../generators/init');
-  const discover = require('./discover');
   const hooksGen = require('../generators/hooks');
   const include = (id) => !wanted || wanted.includes(id);
 
@@ -200,6 +264,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 +275,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 +288,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);
@@ -255,16 +338,70 @@ function buildProjectTargets(cwd, cfg, identityConfig, { dryRun, installMissing
     installMissing,
   }));
 
-  if (include('ci-workflow') && (cfg.ci === 'github-actions' || cfg.ci === 'github_actions')) {
+  // ci-workflow mirrors Go's internal/generators/update.go:1925 target: it manages
+  // the SAME pair of files Go manages — .github/workflows/trackfw-gate.yml (the
+  // generated, version-pinned governance gate, ADR-2026-08-28) and
+  // .gitlab-ci-trackfw.yml — AND, since ML-2G (AC17), ALSO
+  // .github/workflows/trackfw-validate.yml, the different file written by
+  // discover.js (own template, `go install …@latest`, version-pinned to the
+  // generating binary). That third file is refreshed-only-if-present
+  // (AC17(a)/(b)): `update` never installs it, it only keeps an
+  // already-discover-installed copy in sync with what the current binary
+  // would generate, using discover.js's own builder so `update` and `doctor`
+  // can never drift apart by construction.
+  // Writing directly with the byte-identical builders (instead of calling
+  // generateCIWorkflow/generateGitHubActionsWorkflow from generators/init.js) is
+  // deliberate: those functions hardcode paths relative to process.cwd() with no
+  // root parameter, which would silently escape the dry-run tmp sandbox that
+  // runFileTarget builds for every other target here.
+  //
+  // AC17(c): the target is included when cfg.ci opts into github-actions/
+  // gitlab-ci (as before) OR when trackfw-validate.yml already exists on
+  // disk — otherwise a `ci: none` project that ran `discover` would have
+  // that file outside any command's management.
+  const ciWorkflowConfigOptIn = cfg.ci === 'github-actions' || cfg.ci === 'github_actions' || cfg.ci === 'gitlab-ci';
+  if (include('ci-workflow') && (ciWorkflowConfigOptIn || discoverWorkflowPresent(cwd))) {
+    const isGitLab = cfg.ci === 'gitlab-ci';
+    const { DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH } = require('./discover');
     targets.push(runFileTarget({
       id: 'ci-workflow',
-      path: '.github/workflows/trackfw-validate.yml',
+      path: `.github/workflows/trackfw-gate.yml, .gitlab-ci-trackfw.yml, ${DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH}`,
       root: cwd,
-      relPaths: ['.github/workflows/trackfw-validate.yml'],
-      apply: (root) => discover.writeCIWorkflowForce(root),
+      relPaths: ['.github/workflows/trackfw-gate.yml', '.gitlab-ci-trackfw.yml', DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH],
+      apply: (root) => {
+        if (isGitLab) {
+          fs.writeFileSync(path.join(root, '.gitlab-ci-trackfw.yml'), generators.buildGitLabCIWorkflowContent(cfg), 'utf8');
+        } else if (cfg.ci === 'github-actions' || cfg.ci === 'github_actions') {
+          fs.mkdirSync(path.join(root, '.github/workflows'), { recursive: true });
+          fs.writeFileSync(path.join(root, '.github/workflows/trackfw-gate.yml'), generators.buildGitHubActionsWorkflowContent(cfg), 'utf8');
+        }
+        refreshDiscoverGitHubActionsWorkflowIfPresent(root);
+      },
       dryRun,
       installMissing,
     }));
+  } else if (include('ci-workflow')) {
+    // ML-3E (audit of ML-3D): the branch above is skipped exactly when
+    // `ci-workflow` isn't config-opted-in AND discoverWorkflowPresent(cwd)
+    // is false — which is also true when the file at
+    // DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH is a symlink (live or dangling),
+    // since discoverWorkflowPresent() deliberately treats symlinks as NOT
+    // present (AC17(c) comment above). Without this call, a `ci: none`
+    // project with a discover-installed symlink went completely silent:
+    // no target declared, no write, no warning — the exact failure mode
+    // this REQ exists to close (ML-3D's own stderr warning only fired from
+    // inside the branch above, i.e. only in cases where it was already not
+    // needed). refreshDiscoverGitHubActionsWorkflowIfPresent(cwd) re-checks
+    // the real cwd independently: it is a no-op when the file is absent
+    // (AC17(b) — update never creates it) and prints the SAME stderr
+    // warning Go/Python emit — byte-identical, see
+    // internal/generators/update.go:1899 and
+    // pypi/trackfw/commands/update.py:221-225 — when it is a symlink. No
+    // regular file ever reaches this branch (that case is always declared
+    // above via discoverWorkflowPresent(cwd) === true), so this can never
+    // duplicate the write/warning already performed by the branch above,
+    // and never writes through a symlink itself.
+    refreshDiscoverGitHubActionsWorkflowIfPresent(cwd);
   }
 
   if (include('git-hooks') && (cfg.hooks === 'husky' || cfg.hooks === 'lefthook')) {
@@ -340,7 +477,7 @@ cmd.action((mode, options) => {
   // A identidade é carregada uma única vez, fora de qualquer try/catch —
   // um identity.json corrompido deve abortar o comando inteiro, nunca cair
   // silenciosamente para os nomes neutros default.
-  const identityConfig = identityStore.load(os.homedir());
+  const identityConfig = identityStore.load(homedir());
 
   // With --json, stdout must carry only the result document — apply()
   // functions log human progress lines as a side effect; silence them so a

package/src/config/index.js

@@ -4,14 +4,15 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { parseDocument, isScalar, isAlias, isSeq, isMap } = require('yaml');
+const { homedir } = require('../homedir')
 
 function expandPath(filePath) {
   if (!filePath || typeof filePath !== 'string') return filePath;
   if (filePath === '~') {
-    return os.homedir();
+    return homedir();
   }
   if (filePath.startsWith('~/') || filePath.startsWith('~\\')) {
-    return path.join(os.homedir(), filePath.slice(2));
+    return path.join(homedir(), filePath.slice(2));
   }
   return filePath;
 }
@@ -86,6 +87,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 +356,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 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 +425,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

@@ -3,6 +3,7 @@
 const fs = require('fs')
 const path = require('path')
 const os = require('os')
+const { homedir } = require('../homedir')
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -143,8 +144,8 @@ if command -v jq &>/dev/null; then
   TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
   MSG=$(echo "$INPUT" | jq -r '(.tool_input.question // .tool_input.command // "Agent is executing: \\(.tool_name // "unknown")") | .[0:300]')
 else
-  TOOL=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_name',''))" 2>/dev/null || echo "")
-  MSG=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); ti=d.get('tool_input',{}); print((ti.get('question') or ti.get('command') or 'Agent is executing: '+d.get('tool_name','unknown'))[:300])" 2>/dev/null || echo "Agent needs attention")
+  TOOL=$(echo "$INPUT" | PYTHONIOENCODING=utf-8 python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_name',''))" 2>/dev/null || echo "")
+  MSG=$(echo "$INPUT" | PYTHONIOENCODING=utf-8 python3 -c "import sys,json; d=json.load(sys.stdin); ti=d.get('tool_input',{}); print((ti.get('question') or ti.get('command') or 'Agent is executing: '+d.get('tool_name','unknown'))[:300])" 2>/dev/null || echo "Agent needs attention")
 fi
 
 ROADMAP_DIR=$(grep '^roadmap_dir:' trackfw.yaml 2>/dev/null | head -1 | sed 's/^roadmap_dir:[[:space:]]*//; s/[[:space:]]*#.*$//' | tr -d '"' | tr -d "'" || true)
@@ -1047,6 +1048,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 +1087,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')
 }
@@ -1253,14 +1258,14 @@ const GBG_CMD_WINDSURF = 'bash scripts/trackfw-git-branch-guard.sh'
 
 /** Mirrors Go's globalCredentialGuardScriptPath. */
 function globalCredentialGuardScriptPath() {
-  const home = os.homedir()
+  const home = homedir()
   if (!home) return null
   return path.join(home, '.trackfw', 'scripts', 'trackfw-credential-guard.sh')
 }
 
 /** Reads+parses JSON at $HOME/<...relParts>; returns null on any failure (fail-open). */
 function readGlobalHookJSON(...relParts) {
-  const home = os.homedir()
+  const home = homedir()
   if (!home) return null
   try {
     const raw = fs.readFileSync(path.join(home, ...relParts), 'utf8')
@@ -1286,9 +1291,121 @@ function readGlobalHookJSON(...relParts) {
  * (normalizeGuardPath) and pypi/trackfw/generators/hooks.py
  * (_normalize_guard_path). Never call with anything other than a script
  * path -- it is not a general string normalizer.
+ *
+ * ROADMAP-2026-09-03 ML-7B -- Windows separator canonicalization, gated on
+ * anchoring, NOT a blanket "\\" -> "/" translate. On POSIX "\\" is a legal
+ * filename byte, so translating it unconditionally would make two
+ * genuinely different paths (one with a literal backslash in a segment
+ * name, one with an extra path separator there) compare equal -- the exact
+ * dangerous loosening this function's own doc comment warns against, and
+ * the risk this ML was told to treat explicitly. The decision, per input
+ * shape (mirrors the UNC/drive-letter arms of
+ * internal/validator/pathIsAnchoredForHookConfig (Go) / index.js's
+ * pathIsAnchoredForHookConfig, reimplemented locally -- not imported,
+ * different question, and this module must not import the validator):
+ *
+ *   - "C:\Users\x\guard.sh" / "C:/Users/x/guard.sh" (ASCII drive letter,
+ *     ":", then "\" or "/") -- CANONICALIZED: every "\" is translated to
+ *     "/" before the collapse below runs, so both forms land on the same
+ *     "C:/Users/x/guard.sh". This is the case ML-7A measured as the actual
+ *     trigger (a path.join-computed Windows path vs. a hand-concatenated
+ *     one).
+ *   - "\\servidor\share\guard.sh" (valid UNC: non-empty SERVER not "." or
+ *     "..", followed by a non-empty SHARE not itself starting with "\") --
+ *     UNCHANGED, byte-for-byte, including its backslashes. Translating it
+ *     would collapse "\\server\share" into "//server/share" and then this
+ *     function's own "//" -> "/" collapse would eat the second slash,
+ *     producing "/server/share/..." -- indistinguishable from a
+ *     single-leading-backslash, drive-root-relative path
+ *     ("\server\share\..." means something else on Windows) or from a
+ *     same-named POSIX path. That collision is precisely a false "already
+ *     installed": a network-share guard would dedup-match a local one.
+ *     Left untouched, a UNC command never cross-matches a non-UNC one -- no
+ *     new equality is introduced.
+ *   - "//servidor/share/guard.sh" (the POSIX-typed equivalent of UNC) --
+ *     UNCHANGED behavior from before this ML: it does not start with "\",
+ *     so it never enters the new branch above; it still collapses via the
+ *     existing "//" -> "/" rule below, same as any other POSIX path. Not
+ *     unified with the "\\servidor\share\..." form above (pre-existing
+ *     asymmetry, out of scope for this ML).
+ *   - "\\" and "\\x" alone (no SHARE segment) -- NOT valid UNC by the
+ *     predicate above, so they fall through unchanged: no drive letter, no
+ *     valid UNC, no translation.
+ *   - "C:foo" (drive-relative, no separator after ":") and homoglyph/
+ *     zero-width-prefixed strings (e.g. "\uFF43:\...", "\u200bC:\...") --
+ *     do NOT match the ASCII-only, position-0 drive-letter check, so no
+ *     translation happens. Same anti-spoofing posture as the validator's
+ *     drive-letter check.
+ *
+ * Known residual, documented not fixed (hades-tf ML-7B barrier review,
+ * 2026-09-05 parecer): three real Windows-with-"\" shapes have no drive
+ * letter at position 0, so hasWindowsDriveLetterPrefix's gate leaves them
+ * uncanonicalized -- the same pre-ML-7A defect survives for them. Direction
+ * is always TIGHTENS (possible duplicate hook entry), never loosens (the
+ * guard is never silently skipped) -- same safe direction as every other
+ * case above:
+ *
+ *   - "\\?\C:\Users\x\guard.sh" (the Win32 long-path prefix; a real form
+ *     Windows/long-path APIs produce automatically, not a hypothetical).
+ *   - A relative path containing "\" (e.g. "guard\scripts\hook.sh"). Low
+ *     practical risk: today both sides of the real comparison always come
+ *     from path.join with an absolute home, so a relative command should
+ *     not reach this function -- but nothing in the comparator itself
+ *     prevents it.
+ *   - A home resolved via a network-profile UNC path (e.g.
+ *     "\\fileserver\homes\kg\.trackfw\scripts\..."). It never enters the
+ *     drive-letter branch and is intentionally left untouched (see the UNC
+ *     bullet above), so the original defect persists for both UNC
+ *     spellings, not just between UNC and drive-letter forms.
+ *
+ * Not fixed here on purpose: closing any of the three would touch the
+ * drive-letter gate this barrier just approved as conservative, trading a
+ * duplicate-entry nuisance for the more expensive failure mode (collapsing
+ * genuinely different paths into a false "already installed"). Do not treat
+ * rediscovering these three as a new finding.
+ */
+/**
+ * Reports whether p begins with a Windows UNC prefix ("\\server\share...")
+ * with a non-empty SERVER segment (not "." or "..") followed by a non-empty
+ * SHARE segment that does not itself start with another backslash. Mirrors
+ * the UNC arm of index.js's pathIsAnchoredForHookConfig -- reimplemented
+ * here (not imported: different question, and this module must not import
+ * the validator). "\\", "\\x" (no share segment) and "\\.\x" / "\\..\evil"
+ * (server "." or "..") are NOT valid UNC. Currently unused by
+ * normalizeGuardPath itself (a valid-UNC string never has a drive-letter
+ * prefix, so the two checks are already mutually exclusive by construction)
+ * -- kept as a named, tested predicate so the "UNC stays untouched"
+ * decision above is verifiable by name, not just by absence of a call, same
+ * as Go's hasValidUNCPrefix (internal/generators/agentfiles.go) and
+ * Python's _has_valid_unc_prefix (pypi/trackfw/generators/hooks.py).
+ * EXPORTED (unlike Go's package-private equivalent) only because
+ * npm/tests/guard_path_normalize.test.js reaches it via
+ * require('../src/generators/hooks') destructuring -- there is no
+ * production caller. Do not build new logic against this export assuming
+ * UNC gets active handling; it does not (see the doc comment above).
  */
+function hasValidUNCPrefix(p) {
+  if (p.length < 2 || p[0] !== '\\' || p[1] !== '\\') return false
+  const rest = p.slice(2)
+  const cut = rest.indexOf('\\')
+  if (cut === -1) return false
+  const server = rest.slice(0, cut)
+  const share = rest.slice(cut + 1)
+  return server !== '' && server !== '.' && server !== '..' && share !== '' && share[0] !== '\\'
+}
+
+function hasWindowsDriveLetterPrefix(p) {
+  if (p.length < 3) return false
+  const c = p.charCodeAt(0)
+  const isASCIILetter = (c >= 97 && c <= 122) || (c >= 65 && c <= 90)
+  return isASCIILetter && p[1] === ':' && (p[2] === '\\' || p[2] === '/')
+}
+
 function normalizeGuardPath(p) {
   if (!p) return p
+  if (hasWindowsDriveLetterPrefix(p)) {
+    p = p.split('\\').join('/')
+  }
   let out = ''
   let prevSlash = false
   for (const ch of p) {
@@ -1406,7 +1523,7 @@ function globalCredentialGuardInstalledCopilot() {
  * explicit instruction for Kiro.
  */
 function globalCredentialGuardInstalledKiro() {
-  const home = os.homedir()
+  const home = homedir()
   if (!home) return false
   try {
     const stat = fs.statSync(path.join(home, '.kiro', 'hooks', 'trackfw-credential-guard.json'))
@@ -1433,7 +1550,7 @@ function globalCredentialGuardInstalledKiro() {
 
 /** Mirrors Go's globalGitBranchGuardScriptPath. */
 function globalGitBranchGuardScriptPath() {
-  const home = os.homedir()
+  const home = homedir()
   if (!home) return null
   return path.join(home, '.trackfw', 'scripts', 'trackfw-git-branch-guard.sh')
 }
@@ -1489,9 +1606,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 +2377,15 @@ module.exports = {
   mergeCopilotHookArray,
   normalizeGuardPath,
   samePathCommand,
+  hasValidUNCPrefix,
+  hasWindowsDriveLetterPrefix,
+  // 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,
 }