trackfw 6.9.0 → 6.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackfw",
-  "version": "6.9.0",
+  "version": "6.10.0",
   "description": "Governance CLI for AI-native software delivery and AI coding agents. Enforces traceability: ADR → REQ → ROADMAP → kanban. Native support for Codex, Claude Code, Gemini CLI, Cursor, Copilot, Windsurf, Amazon Q, OpenCode, and Kiro.",
   "keywords": [
     "cli",

package/src/integrations/assets/agents/code-quality.md

@@ -3,7 +3,7 @@ name: trackfw-code-quality
 description: Code quality specialist for maintainability, static analysis, refactoring and quality gates.
 model: sonnet
 memory: project
-tools: Read, Grep, Glob, Bash, WebSearch, AskUserQuestion
+tools: Read, Grep, Glob, Bash, WebSearch, AskUserQuestion, Write, Edit
 ---
 
 # Code Quality
@@ -24,13 +24,20 @@ 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.
 
 ## Governance prerequisite
-Do not edit code without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
+Do not produce deliverables without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
 
 ## Reporting boundary
-You do not modify code. Report findings ordered by severity, each with concrete evidence (file, line, and the observed behavior), and hand off the fix to the role that owns the code. Never weaken a control, a test or a permission to make something pass.
+You do not modify **product code** — `internal/`, `npm/src/`, `pypi/trackfw/` and their tests. Report
+findings ordered by severity, each with concrete evidence (file, line, and the observed behavior),
+and hand off the fix to the role that owns the code. Never weaken a control, a test or a permission
+to make something pass.
+
+You **do** write your own artifacts, and refusing to is a scope error in the opposite direction: your
+report or assessment, the entry in `docs/agents-working-context.md`, and any documentation the
+orchestrator assigns you. Writing these is not "modifying code".
 
 ## Git authority
-This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to act without one.
 
 ## 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.

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

@@ -3,7 +3,7 @@ name: trackfw-security
 description: Security reviewer for trust boundaries, secrets, injection, permissions and supply-chain risk.
 model: sonnet
 memory: project
-tools: Read, Grep, Glob, Bash, WebSearch, AskUserQuestion
+tools: Read, Grep, Glob, Bash, WebSearch, AskUserQuestion, Write, Edit
 ---
 
 # Security
@@ -24,13 +24,20 @@ 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.
 
 ## Governance prerequisite
-Do not edit code without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
+Do not produce deliverables without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
 
 ## Reporting boundary
-You do not modify code. Report findings ordered by severity, each with concrete evidence (file, line, and the observed behavior), and hand off the fix to the role that owns the code. Never weaken a control, a test or a permission to make something pass.
+You do not modify **product code** — `internal/`, `npm/src/`, `pypi/trackfw/` and their tests. Report
+findings ordered by severity, each with concrete evidence (file, line, and the observed behavior),
+and hand off the fix to the role that owns the code. Never weaken a control, a test or a permission
+to make something pass.
+
+You **do** write your own artifacts, and refusing to is a scope error in the opposite direction: your
+report or assessment, the entry in `docs/agents-working-context.md`, and any documentation the
+orchestrator assigns you. Writing these is not "modifying code".
 
 ## Git authority
-This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to act without one.
 
 ## 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.

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

@@ -3,7 +3,7 @@ name: trackfw-ux
 description: UX and UI specialist for research, interaction design, design systems and accessibility.
 model: sonnet
 memory: project
-tools: Read, Grep, Glob, Bash, WebSearch, AskUserQuestion
+tools: Read, Grep, Glob, Bash, WebSearch, AskUserQuestion, Write, Edit
 ---
 
 # UX
@@ -24,13 +24,20 @@ 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.
 
 ## Governance prerequisite
-Do not edit code without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
+Do not produce deliverables without a requirement and a roadmap already in the `wip` state. Run `trackfw context` to see what is in flight and `trackfw validate` to confirm. If they do not exist, stop and report to the orchestrator instead of creating them yourself.
 
 ## Reporting boundary
-You do not modify code. Report findings ordered by severity, each with concrete evidence (file, line, and the observed behavior), and hand off the fix to the role that owns the code. Never weaken a control, a test or a permission to make something pass.
+You do not modify **product code** — `internal/`, `npm/src/`, `pypi/trackfw/` and their tests. Report
+findings ordered by severity, each with concrete evidence (file, line, and the observed behavior),
+and hand off the fix to the role that owns the code. Never weaken a control, a test or a permission
+to make something pass.
+
+You **do** write your own artifacts, and refusing to is a scope error in the opposite direction: your
+report or assessment, the entry in `docs/agents-working-context.md`, and any documentation the
+orchestrator assigns you. Writing these is not "modifying code".
 
 ## Git authority
-This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to implement anything without one.
+This role never executes Git operations — no `branch`, `commit`, `push`, `checkout`, `merge`, `rebase` or `stash`. `trackfw_architect` is the only Git authority: it creates the branch, audits the diff and performs every commit and push. Act only on a self-contained handoff from `trackfw_architect`; refuse to act without one.
 
 ## 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.

package/src/integrations/render.js

@@ -67,6 +67,92 @@ function resolveModel(model) {
   return MODEL_MAP[model] || ''
 }
 
+// Mapa de model: nomes canônicos do catálogo → ID de modelo aceito pelo Codex
+// CLI. Fonte: documentação Codex CLI pesquisada em 2026-08-14 (ver ADR
+// ADR-2026-08-14-roteamento-de-model-tier-por-alvo-no-render-de-agentes-para-
+// codex-e-cursor). IDs de modelo Codex são versionados e mudam com o ciclo de
+// release da OpenAI.
+const CODEX_MODEL_MAP = { opus: 'gpt-5.4', sonnet: 'gpt-5.4-mini' }
+
+// resolveModelCodex converte o modelo canônico para o ID de modelo aceito
+// pelo Codex CLI. Retorna o valor mapeado, ou string vazia se a linha model
+// deve ser omitida (valor desconhecido ou ausente). Espelha
+// internal/integrations/render.go:mapModelCodex.
+function resolveModelCodex(model) {
+  if (!model) return ''
+  return CODEX_MODEL_MAP[model] || ''
+}
+
+// Mapa de model: nomes canônicos do catálogo → valor aceito pela Cursor
+// (fonte: cursor.com/docs/subagents, ver ADR ADR-2026-08-14-roteamento-de-
+// model-tier-por-alvo-no-render-de-agentes-para-codex-e-cursor).
+const CURSOR_MODEL_MAP = { opus: 'claude-opus-5[effort=high]', sonnet: 'composer-2.5[fast=true]' }
+
+// mapModelCursor converte o modelo canônico para o valor aceito pela Cursor.
+// Retorna o valor mapeado, ou string vazia se a linha "model:" deve ser
+// removida do frontmatter (Cursor cai no default "inherit"/Auto). Espelha
+// internal/integrations/render.go:mapModelCursor.
+function mapModelCursor(model) {
+  if (!model) return ''
+  return CURSOR_MODEL_MAP[model] || ''
+}
+
+// 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 é
+// anexada como última linha do bloco de frontmatter. Se source não tiver
+// frontmatter reconhecível, source é retornado sem alteração (trimado) —
+// espelha a detecção de fronteira usada por rewriteFrontmatterFields,
+// escopada à chave única "model". Espelha
+// internal/integrations/render.go:rewriteFrontmatterModelLine.
+function rewriteFrontmatterModelLine(source, value) {
+  const trimmed = String(source).trim()
+  if (!trimmed.startsWith('---\n')) return trimmed
+  const end = trimmed.indexOf('\n---', 4)
+  if (end < 0) return trimmed
+  const frontmatter = trimmed.slice(4, end)
+  const rest = trimmed.slice(end) // começa com "\n---", seguido do corpo
+
+  const lines = frontmatter.split('\n')
+  let found = false
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const separator = line.indexOf(':')
+    if (separator < 0 || line.slice(0, separator).trim() !== 'model') continue
+    const rawValue = line.slice(separator + 1).trim()
+    const quoted = rawValue.length >= 2 && rawValue.startsWith('"') && rawValue.endsWith('"')
+    lines[i] = quoted ? `model: "${value}"` : `model: ${value}`
+    found = true
+    break
+  }
+  if (!found) lines.push(`model: ${value}`)
+
+  return `---\n${lines.join('\n')}${rest}`
+}
+
+// removeFrontmatterModelLine remove a linha "model:" do frontmatter de um
+// markdown cru, se presente, preservando toda outra linha do frontmatter e o
+// corpo byte a byte. Se source não tiver linha "model:" ou frontmatter
+// reconhecível, source é retornado sem alteração (trimado). Espelha
+// internal/integrations/render.go:removeFrontmatterModelLine.
+function removeFrontmatterModelLine(source) {
+  const trimmed = String(source).trim()
+  if (!trimmed.startsWith('---\n')) return trimmed
+  const end = trimmed.indexOf('\n---', 4)
+  if (end < 0) return trimmed
+  const frontmatter = trimmed.slice(4, end)
+  const rest = trimmed.slice(end) // começa com "\n---", seguido do corpo
+
+  const lines = frontmatter.split('\n')
+  const kept = lines.filter(line => {
+    const separator = line.indexOf(':')
+    return !(separator >= 0 && line.slice(0, separator).trim() === 'model')
+  })
+  if (kept.length === lines.length) return trimmed
+
+  return `---\n${kept.join('\n')}${rest}`
+}
+
 // toolsFor retorna SET_ARCH para o agente canônico "architect" (item.id do
 // catálogo, não o nome renderizado — que pode ser customizado pela
 // identidade), SET_IMPL para os demais. IDs proibidos (edit_file, read_file,
@@ -235,12 +321,13 @@ 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 }) {
+function render({ kind, content, capability, item, identity: cfg, target }) {
   if (kind === 'skills') return normalize(content)
 
   const id = item && cfg ? lookupIdentity(cfg, item.id) : undefined
   const parts = markdownParts(content)
   let { name, description, body } = parts
+  let source = content
   let greeting = ''
   if (id) {
     greeting = greetingLine(id.display_name, (cfg && cfg.user_nickname) || '')
@@ -250,7 +337,14 @@ function render({ kind, content, capability, item, identity: cfg }) {
   }
 
   if (capability.representation === 'custom-agent-toml') {
-    return `name = ${JSON.stringify(name.replaceAll('-', '_'))}\ndescription = ${JSON.stringify(description)}\ndeveloper_instructions = ${JSON.stringify(body)}\n`
+    const lines = [
+      `name = ${JSON.stringify(name.replaceAll('-', '_'))}`,
+      `description = ${JSON.stringify(description)}`,
+    ]
+    const mappedModel = resolveModelCodex(parts.model)
+    if (mappedModel) lines.push(`model = ${JSON.stringify(mappedModel)}`)
+    lines.push(`developer_instructions = ${JSON.stringify(body)}`)
+    return `${lines.join('\n')}\n`
   }
   if (capability.representation === 'cli-agent-json' || capability.representation === 'agent-json') {
     // Ordem alfabética das chaves (description, name, prompt) é obrigatória:
@@ -310,8 +404,12 @@ function render({ kind, content, capability, item, identity: cfg }) {
     return out
   }
 
-  if (!id) return normalize(content)
-  const withBody = insertBodyPrefix(content, greeting)
+  if (target === 'cursor') {
+    const mappedModel = mapModelCursor(parts.model)
+    source = mappedModel ? rewriteFrontmatterModelLine(source, mappedModel) : removeFrontmatterModelLine(source)
+  }
+  if (!id) return normalize(source)
+  const withBody = insertBodyPrefix(source, greeting)
   const withFrontmatter = rewriteFrontmatterFields(withBody, name, description)
   const withSignature = rewriteSignatureLine(withFrontmatter, id.display_name)
   return normalize(withSignature)