trackfw 7.1.0 → 7.3.0

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.
@@ -44,4 +46,16 @@ Before releasing the next wave, verify each acceptance criterion yourself: read
 ## Mission
 Map the existing architecture and traceability chain before proposing changes. Record material decisions as ADRs, produce decision-complete plans, and delegate implementation to the appropriate specialist. Do not implement product code.
 
+## Response length
+
+Default: what changed · what I decided · what I need from you. Three to five lines.
+
+Scale up only on these three triggers, and only on them: a **blocker** that stops the next wave; a **pending user decision** that cannot be inferred from context; an **error I made** that cannot be self-corrected.
+
+Never cut, even when short: measured evidence (command and result), barrier verdict, decision taken and why. A response that buries a blocker in paragraph seven produced the same effect as not reporting it.
+
+Cut: restating what an executor already reported, re-explaining reasoning already given, recapping state that has not changed, closing praise. Tables and code blocks only when they replace prose, never when they add to it.
+
+Depth is on demand from the user.
+
 — Architect, Principal Software Architect

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/index.js

@@ -56,7 +56,7 @@ function buildPlans(kind, options = {}) {
       for (const item of selected.itemEntries) {
         for (const installPath of paths) {
           const destination = installPath.path.replace('{{id}}', item.id)
-          let content = render({ target: targetEntry.id, kind, item, content: readAsset(item), capability, destination, identity: identityConfig })
+          let content = render({ target: targetEntry.id, kind, item, content: readAsset(item), capability, destination, identity: identityConfig, agentModels: options.agentModels || {} })
           // D5/D9 extension point: reproduce any persisted third-party
           // reference block so regenerating this exact artifact (e.g. a
           // later `trackfw agents update`) settles at state "current"

package/src/integrations/render.js

@@ -97,6 +97,19 @@ function mapModelCursor(model) {
   return CURSOR_MODEL_MAP[model] || ''
 }
 
+// containsControlChar reports whether s contains any ASCII control character
+// (U+0000–U+001F) or a Unicode line/paragraph separator (U+2028, U+2029).
+// Mirrors internal/integrations/render.go:containsControlChar (ML-5C).
+// In JavaScript, strings are UTF-16; U+2028/U+2029 are single code units
+// accessible via charCodeAt, so no surrogate-pair handling is needed.
+function containsControlChar(s) {
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    if (c < 0x20 || c === 0x2028 || c === 0x2029) return true
+  }
+  return false
+}
+
 // rewriteFrontmatterModelLine substitui a linha "model:" do frontmatter de um
 // markdown cru por value, preservando toda outra linha do frontmatter e o
 // corpo byte a byte. Se o frontmatter não tiver linha "model:", uma é
@@ -105,7 +118,14 @@ function mapModelCursor(model) {
 // espelha a detecção de fronteira usada por rewriteFrontmatterFields,
 // escopada à chave única "model". Espelha
 // internal/integrations/render.go:rewriteFrontmatterModelLine.
+//
+// Throws an Error if value contains any ASCII control character (U+0000–U+001F).
+// Model IDs never require control characters; any such value is rejected to
+// prevent frontmatter injection (ML-5A).
 function rewriteFrontmatterModelLine(source, value) {
+  if (containsControlChar(value)) {
+    throw new Error(`model value contains control character and was rejected: model IDs never require newlines or other control characters (got ${JSON.stringify(value)})`)
+  }
   const trimmed = String(source).trim()
   if (!trimmed.startsWith('---\n')) return trimmed
   const end = trimmed.indexOf('\n---', 4)
@@ -296,6 +316,27 @@ function frontmatterName(content) {
   return undefined
 }
 
+// isVersionString reports whether s is a bare version string (digits and dots
+// only, e.g. "5", "4.6", "1.0.2"). Mirrors internal/integrations/render.go:isVersionString.
+// Values that don't match — pre-composed IDs like "claude-sonnet-4-5-20250929" (hyphens),
+// "latest" (letters), or "" (empty) — return false and the caller uses the value literally
+// (escape hatch, ADR-2026-08-21 §3).
+function isVersionString(s) {
+  if (!s) return false
+  return /^[0-9]+(\.[0-9]+)*$/.test(s)
+}
+
+// composeClaudeModelID builds a Claude model identifier from tier and version,
+// applying the three composition rules from the official Anthropic docs.
+// Mirrors internal/integrations/render.go:composeClaudeModelID.
+//   Rule 1: dots become hyphens ("4.6" → "claude-sonnet-4-6")
+//   Rule 2: major-only version never gets "-0" ("5" → "claude-sonnet-5")
+//   Rule 3: handled via escape hatch — pre-composed IDs are never version strings
+function composeClaudeModelID(tier, version) {
+  const hyphenated = version.replace(/\./g, '-')
+  return `claude-${tier}-${hyphenated}`
+}
+
 // render converte um item canônico do catálogo para a representação nativa
 // declarada por uma surface alvo. Quando identity carrega uma identidade
 // customizada para item.id, o name/description/body renderizados são
@@ -321,7 +362,12 @@ function frontmatterName(content) {
 // normalize(content) — a mesma expressão usada antes de existir suporte a
 // identidade — então a saída sem identidade é garantida byte a byte
 // inalterada por construção, não por coincidência.
-function render({ kind, content, capability, item, identity: cfg, target }) {
+//
+// agentModels (opcional) — objeto de tier→versão lido de trackfw.yaml's agent_models.
+// Ausente ou vazio: saída idêntica a antes. Somente o alvo "claude" recebe IDs
+// compostos; Codex, Cursor, Antigravity, OpenCode, Gemini, Kiro não são afetados
+// (ADR-2026-08-21 §4 — gate, não cuidado).
+function render({ kind, content, capability, item, identity: cfg, target, agentModels }) {
   if (kind === 'skills') return normalize(content)
 
   const id = item && cfg ? lookupIdentity(cfg, item.id) : undefined
@@ -407,6 +453,18 @@ function render({ kind, content, capability, item, identity: cfg, target }) {
   if (target === 'cursor') {
     const mappedModel = mapModelCursor(parts.model)
     source = mappedModel ? rewriteFrontmatterModelLine(source, mappedModel) : removeFrontmatterModelLine(source)
+  } else if (target === 'claude' && agentModels && Object.keys(agentModels).length > 0) {
+    // Allowlist: only the "claude" target receives composed model IDs.
+    // Codex, Cursor, Antigravity, OpenCode, Gemini, Kiro and any other target are left
+    // untouched even when agentModels is populated (ADR-2026-08-21 §4 — gate, not cuidado).
+    const version = agentModels[parts.model]
+    if (version) {
+      const modelID = isVersionString(version)
+        ? composeClaudeModelID(parts.model, version)
+        : version // escape hatch: non-version value used literally (ADR-2026-08-21 §3)
+      source = rewriteFrontmatterModelLine(source, modelID)
+    }
+    // Empty string version means "no pin": leave source unchanged (tier alias preserved).
   }
   if (!id) return normalize(source)
   const withBody = insertBodyPrefix(source, greeting)
@@ -415,4 +473,60 @@ function render({ kind, content, capability, item, identity: cfg, target }) {
   return normalize(withSignature)
 }
 
-module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields, rewriteSignatureLine }
+// resolveAgentModel returns the model string that render() would write to the
+// model field of an artifact with the given representation and targetID, for
+// an agent with the given tier. Mirrors
+// internal/integrations/models.go:ResolveAgentModel.
+//
+// Returns { resolved: string, present: boolean }.
+// present=false means the artifact format omits the model field entirely — the
+// caller should display "—" or equivalent rather than the tier alias.
+//
+// agentModels applies only for the "claude" target (ADR-2026-08-21 §4).
+function resolveAgentModel(tier, representation, targetID, agentModels) {
+  if (representation === 'custom-agent-toml') {
+    const v = resolveModelCodex(tier)
+    return { resolved: v, present: v !== '' }
+  }
+  if (representation === 'cli-agent-json' || representation === 'agent-json') {
+    return { resolved: '', present: false }
+  }
+  if (representation === 'agent-directory') {
+    const v = resolveModel(tier)
+    return { resolved: v, present: v !== '' }
+  }
+  if (representation === 'opencode-agent') {
+    return { resolved: '', present: false }
+  }
+  // default branch — mirrors render()'s default case
+  if (targetID === 'cursor') {
+    const v = mapModelCursor(tier)
+    return { resolved: v, present: v !== '' }
+  }
+  if (targetID === 'claude') {
+    const am = agentModels || {}
+    const version = am[tier]
+    if (version) {
+      const modelID = isVersionString(version) ? composeClaudeModelID(tier, version) : version
+      return { resolved: modelID, present: true }
+    }
+    // no pin → tier alias unchanged
+  }
+  return { resolved: tier, present: true }
+}
+
+// looksLikeSuspectModelValue reports whether v is an agent_models value that
+// will trigger the escape-hatch path and likely produce an invalid model
+// identifier in the rendered artifact. Returns true when v is not a bare
+// version string AND does not start with "claude-". Callers should emit a
+// per-tier warning to stderr (not per-row) when this returns true.
+// Mirrors internal/integrations/models.go:LooksLikeSuspectModelValue.
+// looksLikeSuspectModelValue mirrors internal/integrations/models.go:LooksLikeSuspectModelValue.
+// ML-5A: values with control characters are always suspect — rewriteFrontmatterModelLine
+// rejects them outright, so this function must agree with the write path to keep the
+// "agents models" inspection command aligned with "agents install/update" behavior.
+function looksLikeSuspectModelValue(v) {
+  return containsControlChar(v) || (!isVersionString(v) && !v.startsWith('claude-'))
+}
+
+module.exports = { render, markdownParts, frontmatterName, greetingLine, insertBodyPrefix, rewriteFrontmatterFields, rewriteFrontmatterModelLine, rewriteSignatureLine, isVersionString, composeClaudeModelID, resolveAgentModel, looksLikeSuspectModelValue }