trackfw 7.2.0 → 7.3.0

package/src/generators/init.js

@@ -123,6 +123,10 @@ function generateValidateScript(cfg, cwd) {
   const script = buildValidateScript(cfg)
   const scriptPath = path.join(root, 'scripts', 'trackfw-validate.sh')
   fs.writeFileSync(scriptPath, script, { encoding: 'utf8', mode: 0o755 })
+  // AC9 (REQ-2026-08-28): writeFileSync's {mode} option applies only on O_CREAT;
+  // for an existing file the mode is not changed. fs.chmodSync restores 0o755
+  // unconditionally, matching Python's os.chmod behavior (which was already correct).
+  fs.chmodSync(scriptPath, 0o755)
   console.log(`  ✓ ${path.join('scripts', 'trackfw-validate.sh')}`)
 }
 
@@ -201,10 +205,13 @@ function generateCIWorkflow(cfg) {
   }
 }
 
-function generateGitHubActionsWorkflow() {
-  fs.mkdirSync('.github/workflows', { recursive: true })
-
-  const content = `name: trackfw-gate
+// buildGitHubActionsWorkflowContent returns the byte-identical content the GitHub Actions
+// workflow generator would write. Exported for scaffold doctor (ADR-2026-08-27): the
+// comparison uses the same function the write path uses, so drift is structurally impossible.
+// The cfg parameter is accepted for API symmetry with Go's buildGitHubActionsWorkflowContent
+// (which also ignores cfg for now — the template is not cfg-dependent).
+function buildGitHubActionsWorkflowContent(_cfg) {
+  return `name: trackfw-gate
 on:
   pull_request:
     branches: [main]
@@ -222,14 +229,11 @@ jobs:
       - name: Governance gate
         run: trackfw validate
 `
-
-  const filePath = '.github/workflows/trackfw-gate.yml'
-  fs.writeFileSync(filePath, content, 'utf8')
-  console.log(`  ✓ ${filePath}`)
 }
 
-function generateGitLabCIWorkflow() {
-  const content = `# trackfw governance gate
+// buildGitLabCIWorkflowContent mirrors buildGitHubActionsWorkflowContent for GitLab CI.
+function buildGitLabCIWorkflowContent(_cfg) {
+  return `# trackfw governance gate
 trackfw-gate:
   stage: test
   image: alpine:latest
@@ -241,8 +245,17 @@ trackfw-gate:
   only:
     - merge_requests
 `
+}
+
+function generateGitHubActionsWorkflow() {
+  fs.mkdirSync('.github/workflows', { recursive: true })
+  const filePath = '.github/workflows/trackfw-gate.yml'
+  fs.writeFileSync(filePath, buildGitHubActionsWorkflowContent(null), 'utf8')
+  console.log(`  ✓ ${filePath}`)
+}
 
-  fs.writeFileSync('.gitlab-ci-trackfw.yml', content, 'utf8')
+function generateGitLabCIWorkflow() {
+  fs.writeFileSync('.gitlab-ci-trackfw.yml', buildGitLabCIWorkflowContent(null), 'utf8')
   console.log('  ✓ .gitlab-ci-trackfw.yml')
 }
 
@@ -452,7 +465,7 @@ Delete the file when resolved. Visible as a live banner in \`trackfw serve\`.
 - **Docker + .env from day 1:** containerize early; all config via env vars
 - **2-layer validation:** frontend (UX) + backend (security) — never only one
 - **API-first:** define OpenAPI contract before coding frontend/backend integration
-- **Security wave:** include a red-team review wave in every feature roadmap
+- **Threat model waves:** every feature roadmap opens with a Wave 0 threat model (before implementation) and closes with a red-team review wave (before release)
 - **Test coverage:** TDD for critical logic; min 60% (prototype) / 80% (production)
 - Use \`/trackfw:architect\` to define stack before the first REQ
 ` + conventionsSection + `
@@ -855,7 +868,7 @@ trackfw não está instalado. Instale com:
 3. **Gerar o roadmap**
    Com base no conteúdo da REQ, gere um roadmap seguindo **estritamente** este formato:
 
-   \`\`\`markdown
+   \`\`\`\`markdown
    ---
    status: backlog
    date: <YYYY-MM-DD>
@@ -870,6 +883,28 @@ trackfw não está instalado. Instale com:
    ## Diagnóstico / Contexto
    <resumo do problema, motivação e escopo extraídos da REQ>
 
+   ## Wave 0 — Threat Model
+   > Dependencies: none. Blocks all implementation.
+
+   ### ML-0A — Threat model for this roadmap
+   **Status:** pending
+   **Files affected:**
+   **Actions:**
+   1. Enumeration completeness — is the list of surfaces in this roadmap complete? Name what is missing, or show the list is closed. Do not limit the search to the files already named by the REQ — before declaring the list closed, search the repository for other places that emit the same artifact or the same pattern (for example, grep for the literal the final artifact contains).
+   2. Threat model — who empties this Wave 0 without breaking any written rule, and how?
+   3. Falsification targets in both directions — for each surface, what breaks when the behavior regresses, and what breaks when it regresses the opposite way?
+   4. Declared residual — what this design accepts not covering.
+   **Acceptance criteria:**
+   - [ ] The four sections above answered with evidence, not a one-line assertion
+   - [ ] No implementation line written for this ML
+
+   **Gates da wave:**
+   \`\`\`bash
+   # Wave 0 gate — replace this placeholder with a project-specific check before
+   # marking ML-0A done. Do not remove the gate; replace its command (AC13).
+   exit 1  # placeholder gate fails closed until ML-0A replaces it — see docs/cli-parity.md
+   \`\`\`
+
    ## Wave 1 — <nome descritivo> (<N> MLs em paralelo)
    > Dependências: Independente
 
@@ -890,7 +925,7 @@ trackfw não está instalado. Instale com:
    ## Wave 2 — <nome> (depende de Wave 1)
    > Dependências: Wave 1 completa
    ...
-   \`\`\`
+   \`\`\`\`
 
    **Princípios obrigatórios:**
    - MLs dentro da mesma Wave são **independentes** (arquivos distintos, sem conflito)
@@ -1032,9 +1067,19 @@ Próximo passo: abrir PR com gh pr create
 
 Execute primeiro:
 \`\`\`bash
-trackfw barrier <roadmap> --wave <n> --json
+trackfw barrier <roadmap> --wave <n> --trust-local-gates --json
 \`\`\`
 
+\`--trust-local-gates\` é obrigatório aqui: roadmaps WIP (modificados localmente, ainda não commitados em
+\`origin/main\`) são marcados como não confiáveis pela CLI direta por padrão, como proteção contra a
+execução de gates de roadmaps chegados por PR de terceiro. O slash command aplica esse flag porque
+ele representa o fluxo legítimo do arquiteto operando no próprio repositório — não porque os gates
+são inspecionados previamente (o diff ainda é responsabilidade do checklist abaixo).
+
+⚠️ **Não use \`--trust-local-gates\` ao revisar um roadmap chegado por PR de terceiro** — use a CLI
+direta sem o flag (\`trackfw barrier <roadmap> --wave <n> --json\`) para que os gates sejam marcados
+como \`not_evaluated\` e não executados.
+
 Este comando é **necessário mas não suficiente**. Ele verifica MLs concluídos, evidências e \`trackfw validate\`, mas não substitui as inspeções especializadas nem a auditoria de diff abaixo — nenhuma delas é avaliada pelo binário. Consulte a seção \`trackfw barrier\` em \`docs/cli-parity.md\` para o contrato completo (estados, exit codes, saída JSON).
 
 Se o comando retornar exit code não-zero (\`blocked\` ou erro de resolução): pare, reporte a falha ao usuário e não prossiga no checklist até que a wave passe.
@@ -1258,8 +1303,11 @@ async function installAmazonQ(cwd = process.cwd()) {
  */
 async function installIntegrationTarget(target, cwd = process.cwd(), scope = 'project', { onSkip } = {}) {
   const { execute, buildPlans } = require('../integrations')
+  const { resolveAgentModels } = require('../config')
+  const { models: agentModels, warning: agentModelsWarning } = resolveAgentModels(scope, os.homedir(), cwd)
+  if (agentModelsWarning) process.stderr.write(agentModelsWarning + '\n')
   const roots = { projectRoot: cwd }
-  const options = { targets: [target], scope, onSkip }
+  const options = { targets: [target], scope, onSkip, agentModels }
   // D5 — transparency: print resolved destinations before writing anything.
   // buildPlans has no side effects, so it is safe to call here purely to
   // enumerate destinations; the actual write happens below via execute().
@@ -1383,4 +1431,12 @@ module.exports = {
   injectHooksDetected,
   trackfwRulesBlock,
   printArchitectNextSteps,
+  // Template constants and builders — exported for scaffold doctor (ADR-2026-08-27).
+  // Same single-source-of-truth principle as hooks.js exports: comparing against the
+  // same object the write path uses makes drift structurally impossible.
+  CLAUDE_COMMANDS,
+  buildValidateScript,
+  // CI workflow content builders (inline content from generateGitHub/GitLabCIWorkflow)
+  buildGitHubActionsWorkflowContent,
+  buildGitLabCIWorkflowContent,
 }

package/src/generators/roadmap.js

@@ -5,6 +5,42 @@ const config = require('../config')
 const { localDateISO } = require('./date')
 const { resolveReqFiles } = require('../validator/index.js')
 
+// wave0Block — "## Wave 0 — Threat Model" section prepended to every generated roadmap, before
+// the first implementation wave (AC1, AC12). Byte-identical to internal/generators/roadmap.go's
+// wave0Block/wave0GateFence and to pypi/trackfw/generators/roadmap.py's WAVE0_BLOCK (gate:
+// scripts/check-artifact-parity.sh).
+//
+// The gate command (`exit 1`) is fixed, literal and never interpolated with any REQ title, slug
+// or user-controlled string — see the Go generator's comment for the full rationale (AC13,
+// docs/cli-parity.md § "trackfw barrier"). It intentionally fails closed until ML-0A replaces it
+// with a real, project-specific check.
+//
+// The ML is always ML-0A, never ML-1A — newRoadmapFromReq labels MLs derived from REQ acceptance
+// criteria "ML-1A", "ML-1B", ... starting at the first criterion.
+const WAVE0_BLOCK = `## Wave 0 — Threat Model
+> Dependencies: none. Blocks all implementation.
+
+### ML-0A — Threat model for this roadmap
+**Status:** pending
+**Files affected:**
+**Actions:**
+1. Enumeration completeness — is the list of surfaces in this roadmap complete? Name what is missing, or show the list is closed. Do not limit the search to the files already named by the REQ — before declaring the list closed, search the repository for other places that emit the same artifact or the same pattern (for example, grep for the literal the final artifact contains).
+2. Threat model — who empties this Wave 0 without breaking any written rule, and how?
+3. Falsification targets in both directions — for each surface, what breaks when the behavior regresses, and what breaks when it regresses the opposite way?
+4. Declared residual — what this design accepts not covering.
+**Acceptance criteria:**
+- [ ] The four sections above answered with evidence, not a one-line assertion
+- [ ] No implementation line written for this ML
+
+**Gates da wave:**
+\`\`\`bash
+# Wave 0 gate — replace this placeholder with a project-specific check before
+# marking ML-0A done. Do not remove the gate; replace its command (AC13).
+exit 1  # placeholder gate fails closed until ML-0A replaces it — see docs/cli-parity.md
+\`\`\`
+
+`
+
 const VALID_STATES = ['backlog', 'analyzing', 'wip', 'blocked', 'done', 'abandoned']
 const STATE_ORDER = ['analyzing', 'wip', 'backlog', 'blocked', 'done', 'abandoned']
 const VALID_STATES_MESSAGE = VALID_STATES.join(', ')
@@ -400,6 +436,14 @@ function syncReqReferences(movedBasename, newRoadmapPath, cfg) {
  * Em modo by_agent, usa o primeiro agente configurado.
  */
 function newRoadmap(title, reqPath) {
+  // AC1/AC2: o título é dado de uma linha — newline e CR são entrada malformada.
+  // Mensagem byte-idêntica nos 3 CLIs (docs/cli-parity.md).
+  if (/[\n\r]/.test(title)) {
+    console.error('Error: roadmap title must be a single line: newline and carriage return are not allowed')
+    process.exitCode = 1
+    return
+  }
+
   const cfg = config.load()
   const date = localDateISO()
   const slug = toSlug(title)
@@ -441,7 +485,7 @@ REQ: ${reqPath || ''}
 - [ ]
 - [ ]
 
-## Wave 1 — <name> (parallel MLs)
+${WAVE0_BLOCK}## Wave 1 — <name> (parallel MLs)
 > Dependencies: none
 
 ### ML-1A — ${title}
@@ -476,6 +520,13 @@ function newRoadmapFromReq(reqPath) {
   const basename = path.basename(reqPath)
   const title = parsedTitle || basename.replace(/\.md$/, '').replace(/^REQ-/, '')
 
+  // AC1: o título lido da REQ também pode conter newline forjado — rejeitar cedo.
+  if (/[\n\r]/.test(title)) {
+    console.error('Error: roadmap title must be a single line: newline and carriage return are not allowed')
+    process.exitCode = 1
+    return
+  }
+
   const cfg = config.load()
   const date = localDateISO()
   const slug = toSlug(title)
@@ -509,7 +560,7 @@ function newRoadmapFromReq(reqPath) {
     mlLines.push('- [ ] build passes')
     mlLines.push('- [ ] tests green')
   }
-  const mlSection = mlLines.join('\n')
+  const mlSection = WAVE0_BLOCK + mlLines.join('\n')
 
   const adrRef = linkedADR ? `\nADR: ${linkedADR}` : ''
 

package/src/integrations/assets/agents/architect.md

@@ -24,16 +24,18 @@ Append an entry to `docs/agents-working-context.md` when you start and when you
 Before investigating a bug or unexpected behavior, read `vault/notes/index.md` when it exists and open the related notes. After reaching a non-obvious root cause, write a note and link it in the index. Rule of thumb: if another agent would lose more than ten minutes tomorrow without the note, the note must exist.
 
 ## Git authority
-`trackfw_architect` is the **only** role with Git authority in this project. No other agent creates branches, commits, pushes, checks out, merges or rebases — every specialist hands its work back to `trackfw_architect` uncommitted. This role: creates the branch with `trackfw branch new <type>/<slug>`, which validates a matching roadmap already sits in `wip/` or `done/` before running `git checkout -b` and blocks with governance orientation if none is found; falls back to a raw `git checkout -b` only if `trackfw branch new` is an unknown command (binary predating v6.4.0 or missing from PATH) or fails for a reason other than the expected missing-roadmap block, while still requiring REQ + roadmap in `wip` first; audits the full diff produced by specialists against the assigned scope; performs every commit, including orchestration artifacts (ADRs, REQs, roadmaps, vault notes, the working context file) and the product code produced by specialists once audited; pushes to the working branch; and suggests opening a pull request, opening it only when the user explicitly asks. Never merge.
+`trackfw_architect` is the **only** role with Git authority in this project. No other agent creates branches, commits, pushes, checks out, merges or rebases — every specialist hands its work back to `trackfw_architect` uncommitted. This role: creates the branch with `trackfw branch new <type>/<slug>`, which validates a matching roadmap already sits in `wip/` or `done/` before running `git checkout -b` and blocks with governance orientation if none is found; falls back to a raw `git checkout -b` only if `trackfw branch new` is an unknown command (binary predating v6.4.0 or missing from PATH) or fails for a reason other than the expected missing-roadmap block, while still requiring REQ + roadmap in `wip` first; audits the full diff produced by specialists against the assigned scope; performs every commit, including orchestration artifacts (ADRs, REQs, roadmaps, vault notes, the working context file) and the product code produced by specialists once audited; pushes commits already created to the working branch with `trackfw push`; and suggests opening a pull request, opening it only when the user explicitly asks. Never merge.
+
+Three distinct commands, never interchangeable: `trackfw commit` commits staged changes on the working branch; `trackfw push` pushes commits already created — use it instead of a raw `git push`, which the guard intercepts and redirects here; `trackfw ship` composes commit + push + PR into one governed step. Prefer the raw `git commit`/`git push` only when `trackfw commit`/`trackfw push` are unknown commands (binary predating the version that introduced them) or fail for a reason unrelated to governance.
 
 ## Barrier protocol
-Before releasing the next wave: invoke the `code-quality` and `security` roles whenever the change warrants their review (new code paths, dependencies, permissions, secrets, parsers, or attack surface); block the next wave on any failed check and dispatch a corrective microbatch to the owning role instead of proceeding; audit the diff and re-run the wave's gates before performing any commit. A green `trackfw barrier` result from the CLI is necessary but not sufficient — it does not replace the specialized code-quality/security review or the manual diff audit.
+Before releasing the next wave: confirm Wave 0 (threat model) of the current roadmap is audited — every MB in it, before dispatching any implementation wave; invoke the `code-quality` and `security` roles whenever the change warrants their review (new code paths, dependencies, permissions, secrets, parsers, or attack surface); block the next wave on any failed check and dispatch a corrective microbatch to the owning role instead of proceeding; audit the diff and re-run the wave's gates before performing any commit. A green `trackfw barrier` result from the CLI is necessary but not sufficient — it does not replace the specialized code-quality/security review or the manual diff audit.
 
 ## Parallelization
 Analyze real dependencies between microbatches before assigning work. Microbatches touching disjoint files run in parallel; microbatches sharing any file — including generated trees, build outputs and the git index — become sequential, and the reason is documented. Put an explicit barrier between waves. Every handoff prompt must be self-contained: exact files, exact values, exact commands. Never let two agents edit the same file at the same time.
 
 ## Workflow
-Analyze the codebase and requirements; record material decisions in an ADR; create the REQ with an explicit negative scope; produce a roadmap of waves and microbatches with measurable acceptance criteria; create the branch; commit the governance artifacts before any handoff; dispatch the wave; audit each microbatch against its acceptance criteria; update the roadmap; open the pull request only on request.
+Analyze the codebase and requirements; record material decisions in an ADR; create the REQ with an explicit negative scope; produce a roadmap of waves and microbatches with measurable acceptance criteria, starting with a Wave 0 threat model (`security` role, `trackfw barrier <roadmap> --wave 0`) that MUST be audited before any implementation wave is dispatched; create the branch; commit the governance artifacts before any handoff; dispatch Wave 0 first, then the implementation waves; audit each microbatch against its acceptance criteria; update the roadmap; open the pull request only on request.
 
 ## Dispatch contract
 Naming a specialist in prose or in a roadmap's `squad:` field is documentation, not delegation — it does not route the Agent tool call by itself. Every dispatch to a specialist MUST pass the Agent tool's `subagent_type` parameter explicitly; omitting it silently falls back to the generic `general-purpose` agent, which has none of the intended specialist's domain instructions. The correct `subagent_type` value is the `name:` from the frontmatter of that role's installed agent file — always `<slug>-tf`, where `<slug>` depends on the identity the user configured (Greek, Norse, custom, or otherwise); never assume a fixed name. If the exact value is not already known, read the installed agent file for that role before dispatching instead of guessing from the name used in prose. Confirm `subagent_type` is present and correct before every dispatch call.

package/src/integrations/assets/agents/security.md

@@ -42,6 +42,9 @@ This role never executes Git operations — no `branch`, `commit`, `push`, `chec
 ## Definition of done
 Green build and tests do not close a microbatch. It is done when the roadmap reflects the new status and the governance artifacts sit in the correct state folder. Leaving an artifact in the wrong folder is the failure the gate exists to catch.
 
+## Wave 0 deliverable
+When dispatched for a roadmap's `## Wave 0 — Threat Model`, produce a written threat model with exactly four sections, before any implementation line is written: **enumeration completeness** (is the list of surfaces in the roadmap complete? name what is missing, or show the list is closed); **threat model** (who empties this Wave 0 without breaking any written rule, and how — the adversary here is the rushed implementer and the optimistic architect, not an external attacker); **falsification targets in both directions** (for each surface: where the sabotage enters, which gate should catch it, in which direction — false negative and false positive); **declared residual** (what this design accepts not covering, said plainly). Mark each of the four sections done with evidence, not a one-line assertion — `trackfw barrier <roadmap> --wave 0` checks that the ML is `✅` and its acceptance criteria are `[x]`, never the quality of the analysis; a shallow Wave 0 can still pass those two checks, so the `trackfw_architect` audit of the artifact's content is what actually catches it.
+
 ## Mission
 Perform evidence-backed threat analysis. Prioritize concrete exploit paths and mitigations, preserve authentication and least privilege, and never expose secrets or weaken controls to make a test pass.
 

package/src/integrations/scaffold_doctor.js

@@ -0,0 +1,366 @@
+'use strict'
+
+/**
+ * scaffold_doctor.js — scaffold artifact coverage for `trackfw doctor`
+ * (ADR-2026-08-27-doctor-cobre-artefatos-de-scaffold-por-comparacao-com-o-template-
+ * com-propriedade-dada-pelo-caminho.md).
+ *
+ * Mirrors internal/generators/scaffold_doctor.go (Go, canonical source of truth).
+ * Same design decisions apply — see that file's doc comment for the full rationale.
+ *
+ * Key decisions:
+ *   - Property by path, not manifest (AC3): scaffold artifacts are identified by
+ *     well-known namespace paths. No manifest entry is written or read.
+ *   - Sibling classifier (AC15): scaffold artifacts are never in the manifest, so
+ *     routing them through classifyDoctor would produce wrong remedies. The finding
+ *     kinds SCAFFOLD_DIVERGENT / SCAFFOLD_MISSING are separate, with zero claim and
+ *     a trackfw-update remedy.
+ *   - Config-rendered templates (AC12): buildValidateScript(cfg) varies with
+ *     cfg.backend/cfg.frontend — rendered from the project's own trackfw.yaml.
+ *   - Eligibility for slash commands (AC14): only checked when
+ *     .claude/commands/trackfw/ directory already exists.
+ *   - Conditional artifacts (AC13): CI workflow only when cfg.ci declares it.
+ *   - Neutral blame message (AC16): binary version stated; direction ambiguous.
+ *   - Execute-bit checking (REQ-2026-08-28, AC2–AC5, AC10, AC11):
+ *     The five scripts written with mode 0o755 are additionally checked for the
+ *     owner-execute bit. The check uses (stat.mode & 0o100) !== 0 (not === 0o755)
+ *     so umask-narrowed modes (0o750, 0o700) are accepted (AC10). Non-executable
+ *     artifacts (slash commands, CI workflows) carry execBit=false and are never
+ *     accused of a missing execute bit (AC4/AC11). Content divergence takes
+ *     precedence over mode (at most one finding per artifact). Content correct +
+ *     bit missing → SCAFFOLD_WRONG_MODE (AC3 distinct state). On Windows
+ *     (process.platform === 'win32') the execute bit is not representable on NTFS,
+ *     so the mode check is suppressed entirely — AC5.
+ *
+ * _platform is a module-level constant seeded from process.platform so that unit
+ * tests can override it via the exported _setPlatformForTest helper (AC5 testability).
+ */
+
+const fs = require('fs')
+const path = require('path')
+const yaml = require('yaml')
+
+const { SIGNAL_SCRIPT, CLEANUP_SCRIPT, CREDENTIAL_GUARD_SCRIPT, GIT_BRANCH_GUARD_SCRIPT } =
+  require('../generators/hooks')
+const { CLAUDE_COMMANDS, buildValidateScript, buildGitHubActionsWorkflowContent, buildGitLabCIWorkflowContent } =
+  require('../generators/init')
+
+// Finding kind constants — mirrors Go's DoctorScaffoldDivergent / DoctorScaffoldMissing /
+// DoctorScaffoldWrongMode.
+const SCAFFOLD_DIVERGENT = 'scaffold-divergent'
+const SCAFFOLD_MISSING = 'scaffold-missing'
+// SCAFFOLD_WRONG_MODE: content correct but owner-execute bit missing (AC3).
+// Only emitted for artifacts with execBit=true; never on Windows (AC5).
+const SCAFFOLD_WRONG_MODE = 'scaffold-wrong-mode'
+
+// PYTHON_VALIDATE_SCRIPT_FORM is the byte-exact content Python's `trackfw init` and
+// `trackfw update` (validate-script target) write to scripts/trackfw-validate.sh.
+// Accepted by the set-membership check in checkValidateScriptArtifact so that a
+// project initialized by the Python runtime does not produce a false-positive
+// scaffold-divergent finding in the Node.js doctor.
+//
+// Scope of the exception: ONLY scripts/trackfw-validate.sh uses set-membership.
+// All other scaffold artifacts use single-template equality.
+// See docs/cli-parity.md, "validate.sh — pertencimento a conjunto (set-membership, escopado)".
+const PYTHON_VALIDATE_SCRIPT_FORM = '#!/usr/bin/env bash\nset -euo pipefail\ntrackfw validate\n'
+
+// Paths used by the scaffold doctor (mirrors Go's exported constants).
+const CLAUDE_COMMANDS_DIR_PATH = '.claude/commands/trackfw'
+const GITHUB_ACTIONS_WORKFLOW_PATH = '.github/workflows/trackfw-gate.yml'
+const GITLAB_CI_WORKFLOW_PATH = '.gitlab-ci-trackfw.yml'
+
+// _platform is seeded from process.platform at module load time.
+// Tests override it via _setPlatformForTest to exercise the Windows guard (AC5).
+let _platform = process.platform
+
+/**
+ * _setPlatformForTest overrides the platform string used by mode checks.
+ * ONLY for use in unit tests. Returns a restore function.
+ *
+ * @param {string} plat - e.g. 'win32' or 'darwin'
+ * @returns {function} call to restore the original value
+ */
+function _setPlatformForTest(plat) {
+  const prev = _platform
+  _platform = plat
+  return () => { _platform = prev }
+}
+
+/**
+ * execBitPresent returns true when the file at absPath has the owner-execute bit set
+ * (stat.mode & 0o100 !== 0). Returns false on any stat error.
+ *
+ * Uses bit mask rather than equality to 0o755 so that umask-narrowed modes like
+ * 0o750 or 0o700 are also accepted — AC10.
+ *
+ * @param {string} absPath - absolute path to the file
+ * @returns {boolean}
+ */
+function execBitPresent(absPath) {
+  try {
+    const stat = fs.statSync(absPath)
+    return (stat.mode & 0o100) !== 0
+  } catch (_) {
+    return false
+  }
+}
+
+/**
+ * scaffoldRemedy returns a ready-to-copy remedy command for a scaffold finding.
+ * The message is neutral about blame direction (AC16).
+ */
+function scaffoldRemedy(action, relPath) {
+  // Lazy-require version to avoid a circular dependency at module load time.
+  let ver = 'unknown'
+  try {
+    const pkg = require('../../package.json')
+    ver = pkg.version || 'unknown'
+  } catch (_) {}
+  return `trackfw update   # ${action} ${relPath}: content differs from the template trackfw v${ver} generates; if this project was initialized with a newer binary, update the binary instead`
+}
+
+/**
+ * scaffoldWrongModeRemedy returns a remedy command for the scaffold-wrong-mode finding.
+ * Names the missing execute bit explicitly to distinguish it from content divergence (AC3).
+ * The message is runtime-neutral so the parity check can diff Go, Node, and Python outputs
+ * byte-for-byte on this finding kind.
+ */
+function scaffoldWrongModeRemedy(relPath) {
+  return `trackfw update   # restore execute bit on ${relPath}: content is correct but the owner-execute bit is missing (mode 0755 required); trackfw update now restores the mode unconditionally on existing files`
+}
+
+/**
+ * loadProjectConfig reads trackfw.yaml from projectRoot and returns a cfg object
+ * with the same keys that buildValidateScript / buildCIWorkflowContent expect.
+ * Missing keys default to undefined/null — identical to Go's loadUpdateConfig().
+ */
+function loadProjectConfig(projectRoot) {
+  try {
+    const raw = fs.readFileSync(path.join(projectRoot, 'trackfw.yaml'), 'utf8')
+    const parsed = yaml.parse(raw) || {}
+    return {
+      backend: parsed.backend || null,
+      frontend: parsed.frontend || null,
+      pkgManager: parsed.pkg_manager || null,
+      ci: parsed.ci || null,
+    }
+  } catch (_) {
+    return { backend: null, frontend: null, pkgManager: null, ci: null }
+  }
+}
+
+/**
+ * checkValidateScriptArtifact checks scripts/trackfw-validate.sh using set-membership:
+ * accepted if the file content matches EITHER Go/Node's cfg-rendered form OR Python's
+ * fixed form (PYTHON_VALIDATE_SCRIPT_FORM). A file matching NO known form is accused.
+ * All other scaffold artifacts use checkScaffoldArtifact (single-template equality).
+ *
+ * After content membership passes, the execute bit is checked unless on Windows (AC5).
+ * Content divergence always takes precedence over mode (at most one finding per artifact).
+ *
+ * @param {string} absPath - absolute path to the file
+ * @param {string} relPath - relative path (used as destination in findings)
+ * @param {object} cfg - project config from trackfw.yaml
+ * @returns {object|null} finding or null
+ */
+function checkValidateScriptArtifact(absPath, relPath, cfg) {
+  let actual
+  try {
+    actual = fs.readFileSync(absPath, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return {
+        finding: SCAFFOLD_MISSING,
+        claim: { kind: '', item: '', target: '', surface: '', scope: '' },
+        destination: relPath,
+        remedy: scaffoldRemedy('restore', relPath),
+      }
+    }
+    return {
+      finding: SCAFFOLD_DIVERGENT,
+      claim: { kind: '', item: '', target: '', surface: '', scope: '' },
+      destination: relPath,
+      remedy: scaffoldRemedy('resync', relPath),
+    }
+  }
+  const goNodeForm = buildValidateScript(cfg)
+  if (actual !== goNodeForm && actual !== PYTHON_VALIDATE_SCRIPT_FORM) {
+    // Content diverges — scaffold-divergent takes precedence over any mode issue.
+    return {
+      finding: SCAFFOLD_DIVERGENT,
+      claim: { kind: '', item: '', target: '', surface: '', scope: '' },
+      destination: relPath,
+      remedy: scaffoldRemedy('resync', relPath),
+    }
+  }
+  // Content accepted. Check the execute bit (AC2/AC3).
+  // Suppressed on Windows where the bit is not representable (AC5).
+  if (_platform !== 'win32' && !execBitPresent(absPath)) {
+    return {
+      finding: SCAFFOLD_WRONG_MODE,
+      claim: { kind: '', item: '', target: '', surface: '', scope: '' },
+      destination: relPath,
+      remedy: scaffoldWrongModeRemedy(relPath),
+    }
+  }
+  return null
+}
+
+/**
+ * checkScaffoldArtifact compares the on-disk content at absPath against expected.
+ * Returns a finding if the file is divergent or (when reportMissing=true) absent.
+ * relPath is used as destination in the finding.
+ *
+ * @param {string} absPath - absolute path to the file
+ * @param {string} relPath - relative path (destination in findings)
+ * @param {string} expected - expected file content
+ * @param {boolean} reportMissing - if true, absence is a finding
+ * @param {boolean} execBit - if true, check the owner-execute bit after content passes
+ *   true  → artifact was written with 0o755; bit absence → SCAFFOLD_WRONG_MODE (AC2/AC3)
+ *   false → artifact is 0o644 (slash commands, CI workflows); never mode-checked (AC4/AC11)
+ * @returns {object|null} finding or null
+ */
+function checkScaffoldArtifact(absPath, relPath, expected, reportMissing, execBit) {
+  let actual
+  try {
+    actual = fs.readFileSync(absPath, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      if (!reportMissing) return null
+      return {
+        finding: SCAFFOLD_MISSING,
+        claim: { kind: '', item: '', target: '', surface: '', scope: '' },
+        destination: relPath,
+        remedy: scaffoldRemedy('restore', relPath),
+      }
+    }
+    // Unreadable artifact: report as divergent so the user is informed.
+    return {
+      finding: SCAFFOLD_DIVERGENT,
+      claim: { kind: '', item: '', target: '', surface: '', scope: '' },
+      destination: relPath,
+      remedy: scaffoldRemedy('resync', relPath),
+    }
+  }
+  if (actual !== expected) {
+    // Content diverges — takes precedence over any mode issue (at most one finding
+    // per artifact; update fixes both content and mode anyway).
+    return {
+      finding: SCAFFOLD_DIVERGENT,
+      claim: { kind: '', item: '', target: '', surface: '', scope: '' },
+      destination: relPath,
+      remedy: scaffoldRemedy('resync', relPath),
+    }
+  }
+  // Content matches. Check the execute bit when required (AC2/AC3).
+  // Suppressed on Windows where the bit is not representable (AC5).
+  if (execBit && _platform !== 'win32' && !execBitPresent(absPath)) {
+    return {
+      finding: SCAFFOLD_WRONG_MODE,
+      claim: { kind: '', item: '', target: '', surface: '', scope: '' },
+      destination: relPath,
+      remedy: scaffoldWrongModeRemedy(relPath),
+    }
+  }
+  return null
+}
+
+/**
+ * runScaffoldDoctor compares scaffold artifacts on disk against the templates the
+ * currently installed binary would generate (given the project's own trackfw.yaml),
+ * and returns findings for any artifact that is divergent or missing.
+ *
+ * @param {string} projectRoot - absolute path to the project root
+ * @returns {Array} findings
+ */
+function runScaffoldDoctor(projectRoot) {
+  // Eligibility: trackfw.yaml must exist.
+  try {
+    fs.statSync(path.join(projectRoot, 'trackfw.yaml'))
+  } catch (_) {
+    return []
+  }
+
+  const cfg = loadProjectConfig(projectRoot)
+  const findings = []
+
+  // --- Scripts (always in scope when trackfw.yaml is present) ---
+  //
+  // scripts/trackfw-validate.sh uses set-membership (Go/Node form OR Python form).
+  // The four remaining scripts use single-template equality via checkScaffoldArtifact.
+  // All five have execBit=true: the generator writes them with mode 0o755 (AC11).
+  const validateF = checkValidateScriptArtifact(
+    path.join(projectRoot, 'scripts/trackfw-validate.sh'),
+    'scripts/trackfw-validate.sh',
+    cfg,
+  )
+  if (validateF) findings.push(validateF)
+
+  const staticScripts = [
+    { relPath: 'scripts/trackfw-attention-signal.sh', expected: SIGNAL_SCRIPT, execBit: true },
+    { relPath: 'scripts/trackfw-attention-cleanup.sh', expected: CLEANUP_SCRIPT, execBit: true },
+    { relPath: 'scripts/trackfw-credential-guard.sh', expected: CREDENTIAL_GUARD_SCRIPT, execBit: true },
+    { relPath: 'scripts/trackfw-git-branch-guard.sh', expected: GIT_BRANCH_GUARD_SCRIPT, execBit: true },
+  ]
+  for (const { relPath, expected, execBit } of staticScripts) {
+    const f = checkScaffoldArtifact(path.join(projectRoot, relPath), relPath, expected, true, execBit)
+    if (f) findings.push(f)
+  }
+
+  // --- Slash commands (AC14: only when the directory already exists) ---
+  //
+  // Slash commands are markdown files written with mode 0644 — execBit=false (AC11).
+  const claudeDir = path.join(projectRoot, CLAUDE_COMMANDS_DIR_PATH)
+  let claudeDirExists = false
+  try {
+    fs.statSync(claudeDir)
+    claudeDirExists = true
+  } catch (_) {}
+  if (claudeDirExists) {
+    for (const [filename, content] of Object.entries(CLAUDE_COMMANDS)) {
+      const relPath = `${CLAUDE_COMMANDS_DIR_PATH}/${filename}`
+      const f = checkScaffoldArtifact(path.join(projectRoot, relPath), relPath, content, true, false)
+      if (f) findings.push(f)
+    }
+  }
+
+  // --- CI workflow (AC13: conditional on ci: in trackfw.yaml) ---
+  //
+  // CI workflow YAML files are written with mode 0644 — execBit=false (AC11).
+  if (cfg.ci === 'github-actions') {
+    const relPath = GITHUB_ACTIONS_WORKFLOW_PATH
+    const f = checkScaffoldArtifact(
+      path.join(projectRoot, relPath),
+      relPath,
+      buildGitHubActionsWorkflowContent(cfg),
+      true,
+      false,
+    )
+    if (f) findings.push(f)
+  } else if (cfg.ci === 'gitlab-ci') {
+    const relPath = GITLAB_CI_WORKFLOW_PATH
+    const f = checkScaffoldArtifact(
+      path.join(projectRoot, relPath),
+      relPath,
+      buildGitLabCIWorkflowContent(cfg),
+      true,
+      false,
+    )
+    if (f) findings.push(f)
+  }
+
+  // Deterministic output (AC7): sort by destination.
+  findings.sort((a, b) => (a.destination < b.destination ? -1 : a.destination > b.destination ? 1 : 0))
+
+  return findings
+}
+
+module.exports = {
+  runScaffoldDoctor,
+  checkValidateScriptArtifact,
+  SCAFFOLD_DIVERGENT,
+  SCAFFOLD_MISSING,
+  SCAFFOLD_WRONG_MODE,
+  PYTHON_VALIDATE_SCRIPT_FORM,
+  _setPlatformForTest,
+}