trackfw 7.3.0 → 7.4.0

package/src/commands/discover.js

@@ -302,24 +302,72 @@ function installLefthook(rootDir) {
   }
 }
 
-function writeCIWorkflow(rootDir) {
-  const workflowsDir = path.join(rootDir, '.github', 'workflows');
-  if (!isDir(workflowsDir)) fs.mkdirSync(workflowsDir, { recursive: true });
-  const dest = path.join(workflowsDir, 'trackfw-validate.yml');
-  if (isFile(dest)) return; // idempotente
-  const content = `name: trackfw validate
+// DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH is the canonical relative path of the second,
+// independent CI workflow trackfw writes — the one `trackfw discover --init` generates
+// via installGates, distinct from GITHUB_ACTIONS_WORKFLOW_PATH (trackfw-gate.yml,
+// written by init/update). Both files can coexist in the same project
+// (ADR-2026-08-28). Exported so scaffold_doctor.js can compare against it by path.
+const DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH = '.github/workflows/trackfw-validate.yml';
+
+// buildDiscoverGitHubActionsWorkflowContent returns the template content trackfw writes
+// to DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH. Mirrors
+// generators.BuildDiscoverGitHubActionsWorkflowContent in
+// internal/generators/scaffold_doctor.go (Go, canonical source of truth) byte-for-byte
+// for the same version.
+//
+// NOT version-independent (ADR-2026-08-28, REQ-2026-08-28 AC6/AC7): the `go install
+// .../cmd/trackfw@vX.Y.Z` step pins the second install mechanism (`go install ...@latest`)
+// to the version of npm/package.json — the version of the CLI that generated/updated the
+// project — mirroring the install.sh pin already applied to
+// buildGitHubActionsWorkflowContent (trackfw-gate.yml) in generators/init.js. Never
+// hardcoded: read lazily to avoid a circular require at module load time.
+//
+// Job id is `governance-go-install` (ML-1A, ROADMAP-2026-09-01) — was `governance`,
+// colliding with buildGitHubActionsWorkflowContent's job id (trackfw-gate.yml,
+// generators/init.js). See that function's doc comment for the full rationale; named
+// after the install mechanism (`go install`), not the workflow file.
+function buildDiscoverGitHubActionsWorkflowContent() {
+  const { version } = require('../../package.json');
+  return `name: trackfw validate
 on: [push, pull_request]
 jobs:
-  governance:
+  governance-go-install:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with:
           go-version: "1.22"
-      - run: go install github.com/kgsaran/trackfw/cmd/trackfw@latest
+      - run: go install github.com/kgsaran/trackfw/cmd/trackfw@v${version}
       - run: trackfw validate
 `;
+}
+
+function writeCIWorkflow(rootDir) {
+  const workflowsDir = path.join(rootDir, '.github', 'workflows');
+  if (!isDir(workflowsDir)) fs.mkdirSync(workflowsDir, { recursive: true });
+  const dest = path.join(workflowsDir, 'trackfw-validate.yml');
+  // Uses fs.lstatSync directly, NOT the isFile helper (fs.statSync, follows
+  // symlinks): a DANGLING symlink at dest resolves to "does not exist" under
+  // fs.statSync, so the idempotency guard below would not fire, and
+  // fs.writeFileSync would then follow the link and CREATE the workflow
+  // template at whatever path outside the project the symlink points to. A
+  // symlink here — live or dangling — is treated as "already present" so
+  // this function never writes through it; it refuses loudly instead of
+  // silently creating a file somewhere the caller never asked for.
+  let info
+  try {
+    info = fs.lstatSync(dest)
+  } catch (e) {
+    info = null
+  }
+  if (info) {
+    if (info.isSymbolicLink()) {
+      console.error(`aviso: ${DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH} é um symlink; trackfw discover não escreve através de symlinks — arquivo não foi tocado`)
+    }
+    return; // idempotente — não sobrescreve (nem segue o link)
+  }
+  const content = buildDiscoverGitHubActionsWorkflowContent();
   fs.writeFileSync(dest, content, 'utf8');
 }
 
@@ -551,19 +599,20 @@ function writeCIWorkflowForce(rootDir) {
   const workflowsDir = path.join(rootDir, '.github', 'workflows');
   if (!isDir(workflowsDir)) fs.mkdirSync(workflowsDir, { recursive: true });
   const dest = path.join(workflowsDir, 'trackfw-validate.yml');
-  const content = `name: trackfw validate
-on: [push, pull_request]
-jobs:
-  governance:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
-        with:
-          go-version: "1.22"
-      - run: go install github.com/kgsaran/trackfw/cmd/trackfw@latest
-      - run: trackfw validate
-`;
+  // Same symlink guard as writeCIWorkflow above: "force" means "overwrite
+  // an existing REGULAR file unconditionally", not "follow whatever this
+  // path resolves to". A symlink here — live or dangling — is refused, not
+  // followed.
+  try {
+    const info = fs.lstatSync(dest)
+    if (info.isSymbolicLink()) {
+      console.error(`aviso: ${DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH} é um symlink; trackfw discover não escreve através de symlinks — arquivo não foi tocado`)
+      return;
+    }
+  } catch (e) {
+    // does not exist — fine, this is the "force create" case
+  }
+  const content = buildDiscoverGitHubActionsWorkflowContent();
   fs.writeFileSync(dest, content, 'utf8');
 }
 
@@ -575,3 +624,5 @@ module.exports.writeValidateScript = writeValidateScript;
 module.exports.writeCIWorkflow = writeCIWorkflow;
 module.exports.writeCIWorkflowForce = writeCIWorkflowForce;
 module.exports.detectTestFramework = detectTestFramework;
+module.exports.buildDiscoverGitHubActionsWorkflowContent = buildDiscoverGitHubActionsWorkflowContent;
+module.exports.DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH = DISCOVER_GITHUB_ACTIONS_WORKFLOW_PATH;

package/src/commands/doctor.js

@@ -1,8 +1,18 @@
 'use strict'
 
 const { Command } = require('commander')
-const { runDoctor, UNREGISTERED_WRITE, HAND_MODIFIED, UNKNOWN_CONTENT } = require('../integrations/doctor')
+const {
+  runDoctor,
+  UNREGISTERED_WRITE,
+  HAND_MODIFIED,
+  UNKNOWN_CONTENT,
+  REQUIRED_STATUS_CHECKS_MISSING,
+  ENFORCE_ADMINS_DISABLED,
+  HOOKS_PATH_NEUTRALIZED,
+  NOT_EVALUATED,
+} = require('../integrations/doctor')
 const { runScaffoldDoctor, SCAFFOLD_DIVERGENT, SCAFFOLD_MISSING, SCAFFOLD_WRONG_MODE } = require('../integrations/scaffold_doctor')
+const { runDoctorRemote } = require('../integrations/doctor_remote')
 const projectConfig = require('../config')
 
 function printReport(findings) {
@@ -15,8 +25,12 @@ function printReport(findings) {
   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 requiredChecksMissing = findings.filter(finding => finding.finding === REQUIRED_STATUS_CHECKS_MISSING).length
+  const enforceAdminsDisabled = findings.filter(finding => finding.finding === ENFORCE_ADMINS_DISABLED).length
+  const hooksPathNeutralized = findings.filter(finding => finding.finding === HOOKS_PATH_NEUTRALIZED).length
+  const notEvaluated = findings.filter(finding => finding.finding === NOT_EVALUATED).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`,
+    `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, ${requiredChecksMissing} required-status-checks-missing, ${enforceAdminsDisabled} enforce-admins-disabled, ${hooksPathNeutralized} hooks-path-neutralized, ${notEvaluated} not-evaluated`,
     '',
   ]
   for (const finding of findings) {
@@ -28,6 +42,7 @@ function printReport(findings) {
 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.option('--remote', 'Also check GitHub branch protection (required_status_checks, enforce_admins) and local core.hooksPath neutralization. Requires network + a GitHub credential with admin access; absence of either is reported as not-evaluated, never as a pass (ADR-2026-09-02).')
 cmd.action(async options => {
   const projectRoot = process.cwd()
   const catalogFindings = runDoctor({ agentModels: projectConfig.load().agentModels || {} })
@@ -35,7 +50,12 @@ cmd.action(async options => {
   // 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]
+  let findings = [...catalogFindings, ...scaffoldFindings]
+  // Remote modality (ADR-2026-09-02, ML-3A): opt-in only — never runs without --remote, so
+  // doctor's offline default is unchanged.
+  if (options.remote) {
+    findings = [...findings, ...runDoctorRemote({ configForge: projectConfig.load().forge || '', repoDir: projectRoot })]
+  }
   if (options.json) {
     process.stdout.write(`${JSON.stringify(findings, null, 2)}\n`)
     return

package/src/commands/init.js

@@ -5,6 +5,7 @@ const identityStore = require('../identity')
 const identityWizard = require('./identity-wizard')
 const { resolveIdentityPreset, identityFileExists } = identityWizard
 const { resolveScope } = require('./integrations')
+const { homedir } = require('../homedir')
 
 const cmd = new Command('init')
 cmd.description(t('init.description'))
@@ -16,7 +17,7 @@ cmd.action(async (options, command) => {
   const path = require('path')
   const generators = require('../generators/init')
 
-  const home = os.homedir()
+  const home = homedir()
 
   // A validação e persistência da flag acontecem incondicionalmente, acima
   // do early-return não-TTY abaixo — é isso que faz um --identity-preset

package/src/commands/integrations.js

@@ -10,6 +10,7 @@ const identityWizard = require('./identity-wizard')
 const { t } = require('../i18n')
 const { createThirdPartyCommand } = require('./thirdparty')
 const configModule = require('../config')
+const { homedir } = require('../homedir')
 
 const csv = value => String(value).split(',').map(entry => entry.trim()).filter(Boolean)
 const collect = (value, previous) => previous.concat(value)
@@ -179,7 +180,7 @@ function createLifecycleCommand(kind) {
       let presetChanged = false
       if (mutation && kind === 'agents') {
         presetChanged = cmd.getOptionValueSource('identityPreset') === 'cli'
-        if (presetChanged) identityWizard.applyIdentityPresetFlag(os.homedir(), options.identityPreset, operation)
+        if (presetChanged) identityWizard.applyIdentityPresetFlag(homedir(), options.identityPreset, operation)
       }
 
       if (mutation && (!options.targets || !options.targets.length)) {
@@ -197,7 +198,7 @@ function createLifecycleCommand(kind) {
       // planos abaixo. Espelha
       // internal/commands/integrations_flags.go:executeIntegrationMutation.
       if (mutation && kind === 'agents' && !presetChanged) {
-        const homeRoot = os.homedir()
+        const homeRoot = homedir()
         const identityExists = identityWizard.identityFileExists(homeRoot)
         const isTTY = Boolean(process.stdin.isTTY)
         if (identityWizard.shouldPromptIdentity(kind, isTTY, identityExists, forceIdentity)) {
@@ -221,7 +222,7 @@ function createLifecycleCommand(kind) {
         }
       }
 
-      const { models: resolvedModels, warning: modelsWarning } = configModule.resolveAgentModels(options.scope, os.homedir(), process.cwd())
+      const { models: resolvedModels, warning: modelsWarning } = configModule.resolveAgentModels(options.scope, homedir(), process.cwd())
       if (modelsWarning) process.stderr.write(modelsWarning + '\n')
       options.agentModels = resolvedModels
       const output = execute(kind, operation, options)
@@ -254,7 +255,7 @@ function createAgentModelsCommand() {
   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())
+    const { models: agentModels, source: modelsSource } = configModule.loadGlobalAgentModels(homedir(), process.cwd())
 
     // Source line (AC5): show origin before the table; advisory to stderr when not resolved.
     const sourceLines = {

package/src/commands/req.js

@@ -4,6 +4,7 @@ const os = require('os')
 const { Command } = require('commander')
 const { listREQs, moveREQ } = require('../generators/req')
 const { t } = require('../i18n')
+const { homedir } = require('../homedir')
 
 const cmd = new Command('req')
 cmd.description(t('req.description'))
@@ -38,7 +39,7 @@ cmd.command('new <title>')
         default: 'local',
       })
       const adrDir = adrScope === 'global'
-        ? path.join(os.homedir(), '.trackfw', 'adr')
+        ? path.join(homedir(), '.trackfw', 'adr')
         : require('../config').load().adrDirs[0]
 
       // Perguntas dinâmicas por probe

package/src/commands/thirdparty.js

@@ -19,6 +19,7 @@ const { checkMarkers, checksum: sha256hex } = require('../thirdparty/markers')
 const { quarantinePath, newQuarantineEntry, writeQuarantine, readQuarantine, decodeContent } = require('../thirdparty/quarantine')
 const { loadProvenance, verifyApproval, upsertProvenanceEntry } = require('../thirdparty/provenance')
 const { upsertThirdPartyReference, normalizeThirdPartyContent, resolveThirdPartySkillDestination } = require('../thirdparty/references')
+const { homedir } = require('../homedir')
 
 // api is the module.exports object itself, referenced internally via
 // `api.thirdPartyFetch(...)` so tests can substitute the network fetch by
@@ -189,7 +190,7 @@ 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)
+  const { models: resolvedAgentModels, warning: agentModelsWarning } = configModule.resolveAgentModels(scope, homedir(), projectRoot)
   if (agentModelsWarning) process.stderr.write(agentModelsWarning + '\n')
   let identityConfig
   if (options.applyTo && options.applyTo.length) {

package/src/commands/update-harness.js

@@ -8,6 +8,7 @@ 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')
+const { homedir } = require('../homedir')
 
 // `trackfw update harness` is the global counterpart to `trackfw update` —
 // see docs/cli-parity.md, "`trackfw update` vs `trackfw update harness`".
@@ -40,7 +41,7 @@ const { mergeClaudeHookArray, mergeSimpleCommandArray, mergeCopilotHookArray, ge
 
 // claudeSkillContent — mirrors generators/init.js:installSkillsForce
 // (npm/src/generators/init.js:1242) byte-for-byte. Duplicated here, not
-// imported, because installSkillsForce() bakes os.homedir() internally with
+// imported, because installSkillsForce() bakes homedir() internally with
 // an unconditional overwrite and no dry-run mode — it cannot be reused
 // without either mutating on --dry-run or forking its signature. Reported
 // as a follow-up cleanup opportunity in the ML-6C handoff report.
@@ -880,7 +881,7 @@ function run(options) {
     process.exit(1)
   }
 
-  const homeRoot = os.homedir()
+  const homeRoot = homedir()
   const dryRun = Boolean(options.dryRun)
   const installMissing = Boolean(options.installMissing)
 

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);
 
@@ -274,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')) {
@@ -359,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;
 }
@@ -369,7 +370,7 @@ function _cwdAgentModelsSource(cwd) {
 }
 
 // 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).
+// 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