raptor-aios 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.10.0] - 2026-06-11
+
+### Added
+
+- **Jira → spec: nomes de campo resolvidos + filtro de relevância (`packages/core/src/jira/`).** Um card de Jira corporativo carrega centenas de custom fields de configuração (o `CDPOS-6532` real: 1408 campos, 515 não-nulos) que antes inundavam a `## Problem Statement` com blocos `### customfield_NNNNN` ilegíveis. Agora:
+  - **Nomes resolvidos.** O dialeto Rovo (hospedado, OAuth) passa a enviar `expand: "names"`, então cada `customfield_NNNNN` ganha seu rótulo humano ("Critérios de Aceite"). O `mcp-atlassian` (≥ 0.11.2) tem o rótulo desembrulhado do wrapper `{value, name}` (ele nunca ecoa o mapa `names`); `renderedFields` deixou de ser pedido (o servidor o descarta e a combinação suprime custom fields em algumas versões).
+  - **Filtro de relevância (`filterCustomFields`).** Camadas determinísticas (PT/EN, singular+plural): valor-ruído (enums, datas, placeholders) e rótulos de config (Responsável, Relator, Categorias, Branch, Repositório, EI/EO/EQ, CMDB, Nova Data…) caem; allowlist de história (Requisitos, Cenários, Critérios de Aceite, Ressalva de testes, Figma, Traduções, Documentação, Anexo…) e links de ferramenta de design (figma/miro/zeplin/notion/confluence) ficam — avaliados ANTES do denylist. Desconhecidos só ficam com prosa substantiva (rede *lose-nothing*).
+  - **`jira.custom_fields` ganha `exclude` e force-keep** (chaves case-insensitive): `<campo>: exclude` derruba; `<campo>: <bucket>` força a manter.
+  - **Anexos de imagem** (`image/*`) entram como `### Attachments (images)` (links, não baixados); outros tipos ficam no card.
+  - **Critérios de Aceite agrupados por cenário** (`acceptanceLines`): blocos "Cenário N …" viram um `[AC-#]` cada (não um por linha de Gherkin).
+
+### Changed
+
+- **`flattenAdf` rende `taskItem` e `table`.** Uma matriz de aplicabilidade do Jira (grade de checkboxes) agora vira texto legível: **só os itens marcados `[x]` sobrevivem** (os desmarcados são ruído) e tabelas viram uma linha por row com células separadas por `|`. No `CDPOS-6532`, "Cenários aplicáveis" encolheu de 2528 → 607 chars, mostrando o escopo real.
+- **URL do card browsable.** `resolveUrl` prefere o `base_url` do `raptor.yml` ao `self` do gateway `api.atlassian.com` (que não abre no navegador); `jira.base_url` é encanado do `raptor.yml` ao cliente OAuth.
+- **`raptor jira pull`** imprime quantos custom fields foram filtrados (descoberta para o escape hatch); `--json` segue despejando tudo sem filtro. O `jira-refresh.md` (clarify) usa o mesmo filtro — os três consumidores (`new`, `pull`, `jira-refresh`) mostram o mesmo card.
+
+Doc: [`docs/jira-spec-enrichment.md`](docs/jira-spec-enrichment.md) (seções F1–F4 + F3½ + §4b card corporativo). Validado E2E contra o `CDPOS-6532` real via OAuth.
+
 ## [0.9.0] - 2026-06-11
 
 ### Added

package/dist/_core/dist/jira/dialects.js

@@ -12,7 +12,7 @@ export const ROVO_DIALECT = {
         transition: ["transitionJiraIssue"],
     },
     args: {
-        getIssue: (cloudId, key) => ({ cloudId, issueIdOrKey: key }),
+        getIssue: (cloudId, key) => ({ cloudId, issueIdOrKey: key, expand: "names" }),
         search: (cloudId, jql, max) => ({ cloudId, jql, maxResults: max }),
         projects: (cloudId) => ({ cloudId }),
         createIssue: (input) => ({
@@ -53,7 +53,7 @@ export const MCP_ATLASSIAN_DIALECT = {
         getIssue: (_cloudId, key) => ({
             issue_key: key,
             fields: "*all",
-            expand: "names,renderedFields",
+            expand: "names",
             comment_limit: 10,
         }),
         search: (_cloudId, jql, max) => ({ jql, limit: max }),

package/dist/_core/dist/jira/index.js

@@ -3,4 +3,4 @@ export * from "./credentials.js";
 export { AtlassianOAuthProvider, isAccessTokenExpired, openBrowser, startCallbackServer, } from "./oauth.js";
 export { connectJira, connectMcpServer, makeJiraClient, clientToToolCaller, decodeToolResult, unwrapEnvelope, expandEnv, missingEnvRefs, } from "./mcp-client.js";
 export { ROVO_DIALECT, MCP_ATLASSIAN_DIALECT, DIALECTS, resolveDialect, detectDialect, } from "./dialects.js";
-export { parseJiraIssue, parseCreatedIssue, extractComments, extractCustomFields, classifyField, flattenFieldValue, mapIssueToSpecContext, flattenAdf, extractAcceptanceCriteria, } from "./mapper.js";
+export { parseJiraIssue, parseCreatedIssue, extractComments, extractCustomFields, extractAttachments, classifyField, filterCustomFields, isBoilerplateValue, isTemplateValue, acceptanceLines, flattenFieldValue, mapIssueToSpecContext, flattenAdf, extractAcceptanceCriteria, } from "./mapper.js";

package/dist/_core/dist/jira/mapper.js

@@ -33,18 +33,49 @@ export function parseJiraIssue(raw, baseUrl) {
         acceptanceCriteria: extractAcceptanceCriteria(fields, description),
         comments: extractComments(fields),
         customFields,
+        attachments: extractAttachments(fields),
         ...(url ? { url } : {}),
     };
 }
+export function extractAttachments(fields) {
+    const list = Array.isArray(fields["attachment"])
+        ? fields["attachment"]
+        : Array.isArray(fields["attachments"])
+            ? fields["attachments"]
+            : [];
+    const out = [];
+    for (const a of list) {
+        if (!isRecord(a))
+            continue;
+        const filename = str(a["filename"]);
+        if (!filename)
+            continue;
+        out.push({
+            filename,
+            mimeType: str(a["mimeType"]) || str(a["content_type"]),
+            url: str(a["content"]) || str(a["url"]),
+        });
+    }
+    return out;
+}
 export function extractCustomFields(fields, names) {
     const out = [];
     for (const [id, raw] of Object.entries(fields)) {
         if (!/^customfield_/i.test(id))
             continue;
-        const value = flattenFieldValue(raw);
+        let label = str(names[id]);
+        let inner = raw;
+        if (isRecord(raw) &&
+            "value" in raw &&
+            Object.keys(raw).every((k) => k === "value" || k === "name")) {
+            if (!label)
+                label = str(raw["name"]);
+            inner = raw["value"];
+        }
+        const value = flattenFieldValue(inner);
         if (!value)
             continue;
-        const name = str(names[id]) || id;
+        const name = label || id;
         out.push({ id, name, value, bucket: classifyField(name) });
     }
     return out;
@@ -55,21 +86,102 @@ export function classifyField(label) {
         return "acceptance";
     if (/cen[áa]rio|scenario/.test(l))
         return "scenarios";
-    if (/n[ãa]o[-\s]?funcional|non[-\s]?functional|\brnf\b/.test(l))
+    if (/n[ãa]o[-\s]?funcional|non[-\s]?functional|\brnf\b|ressalva/.test(l))
         return "nonFunctional";
     if (/requisito|requirement|\brf\b/.test(l))
         return "functional";
     if (/fora do escopo|out of scope|n[ãa]o escopo/.test(l))
         return "outOfScope";
-    if (/documenta|documentation|link|refer[êe]ncia|design|figma/.test(l))
+    if (/documenta|documentation|link|refer[êe]ncia|design|figma|tradu[çc]|translation/.test(l))
         return "docs";
     return "other";
 }
+const ENUM_NOISE = /^(?:sim|n[ãa]o|yes|no|true|false|n\/a|na|none|nenhum|classificar|backlog|portal|no prazo|⏳|✅|❌|-+)$/i;
+const PLACEHOLDER_LINE = /^(?:inserir|informar|descrever|preencher|selecionar|indicar|exportar|insira|informe|descreva|preencha|selecione|indique)\b/i;
+const CARD_CONFIG_LABEL = /\b(?:respons[áa]ve(?:l|is)|relator(?:a|es|as)?|reporter|assignee|aprovador(?:a|es|as)?|squads?|categorias?|data\s+limite|nova\s+data|due\s*date|prazos?|branch(?:es)?|reposit[óo]rios?|repositor(?:y|ies)|entradas?\s+externas?|sa[íi]das?\s+externas?|consultas?\s+externas?|\bei\b|\beo\b|\beq\b|cmdb|aplica[çc][ãa]o\s+afetada|epic\s*links?|rank|development|sprints?|itera[çc](?:[ãa]o|[õo]es)|iterations?|quarters?|garantias?|story\s*points?|time\s*tracking)\b/i;
+const ESSENTIAL_LABEL = /aceite|aceita[çc][ãa]o|acceptance|cen[áa]rio|scenario|requisito|requirement|\brnf\b|\brf\b|ressalva|figma|tradu[çc]|translation|documenta[çc]|documentation|refer[êe]ncia|\bdesign\b|anexo|attachment|prot[óo]tipo|prototype|hist[óo]ria|user\s*stor|fora\s+do\s+escopo|out\s+of\s+scope/i;
+const DOC_TOOL_URL = /\b(?:figma\.com|miro\.com|zeplin\.(?:io|app)|notion\.so|atlassian\.net\/wiki)\b/i;
+export function isBoilerplateValue(value) {
+    const v = value.trim();
+    if (!v)
+        return true;
+    if (ENUM_NOISE.test(v))
+        return true;
+    if (!v.includes("\n") && /^[\d|:.,\-T+Z\s/]+$/.test(v))
+        return true;
+    if (/^(?:espa[çc]o para inser[çc][ãa]o|campos a seguir)/i.test(v))
+        return true;
+    return false;
+}
+export function isTemplateValue(value) {
+    const v = value.trim();
+    if (v.length < 200)
+        return true;
+    if (v.includes("{panel") || v.includes("🚨"))
+        return true;
+    if (/^\{(?:pullrequest|dataType|json)\b/.test(v))
+        return true;
+    const segments = v
+        .split("\n")
+        .flatMap((l) => l.split(" | "))
+        .map((s) => s.replace(/^[-*\d.)\s]+/, "").trim())
+        .filter(Boolean);
+    return segments.filter((s) => PLACEHOLDER_LINE.test(s)).length >= 2;
+}
+export function filterCustomFields(fields, overrides = {}) {
+    const ovByKey = {};
+    for (const [k, v] of Object.entries(overrides))
+        ovByKey[k.toLowerCase()] = v;
+    const out = [];
+    for (const cf of fields) {
+        const ov = ovByKey[cf.id.toLowerCase()] ?? ovByKey[cf.name.toLowerCase()];
+        if (ov && ov.toLowerCase() === "exclude")
+            continue;
+        if (ov) {
+            out.push({ ...cf, bucket: ov });
+            continue;
+        }
+        if (isBoilerplateValue(cf.value))
+            continue;
+        if (ESSENTIAL_LABEL.test(cf.name)) {
+            out.push(cf);
+            continue;
+        }
+        if (DOC_TOOL_URL.test(cf.value)) {
+            out.push({ ...cf, bucket: "docs" });
+            continue;
+        }
+        if (CARD_CONFIG_LABEL.test(cf.name))
+            continue;
+        if (isTemplateValue(cf.value))
+            continue;
+        out.push(cf);
+    }
+    return out;
+}
+export function acceptanceLines(value) {
+    const lines = toLines(value);
+    const isStart = (l) => /^(?:cen[áa]rio|scenario)\b/i.test(l);
+    const starts = lines.filter(isStart).length;
+    const hasGherkin = lines.some((l) => /^(?:dado|quando|ent[ãa]o|given|when|then)\b/i.test(l));
+    if (starts === 0 || (starts === 1 && !hasGherkin))
+        return lines;
+    const blocks = [];
+    for (const l of lines) {
+        if (isStart(l) || blocks.length === 0)
+            blocks.push([l]);
+        else
+            blocks[blocks.length - 1].push(l);
+    }
+    return blocks.map((b) => b.join(" "));
+}
 export function flattenFieldValue(raw) {
     if (raw == null)
         return "";
     if (typeof raw === "string")
         return raw.trim();
+    if (typeof raw === "number" || typeof raw === "boolean")
+        return String(raw);
     if (Array.isArray(raw)) {
         return raw.map(flattenFieldValue).filter(Boolean).join("\n").trim();
     }
@@ -113,11 +225,7 @@ export function extractComments(fields) {
     return out;
 }
 export function mapIssueToSpecContext(issue, opts = {}) {
-    const overrides = opts.fieldBuckets ?? {};
-    const custom = (issue.customFields ?? []).map((cf) => {
-        const ov = overrides[cf.id] ?? overrides[cf.name.toLowerCase()];
-        return ov ? { ...cf, bucket: ov } : cf;
-    });
+    const custom = filterCustomFields(issue.customFields ?? [], opts.fieldBuckets);
     const ac = [];
     const seen = new Set();
     const pushAc = (line) => {
@@ -130,13 +238,19 @@ export function mapIssueToSpecContext(issue, opts = {}) {
     issue.acceptanceCriteria.forEach(pushAc);
     for (const cf of custom)
         if (cf.bucket === "acceptance")
-            toLines(cf.value).forEach(pushAc);
+            acceptanceLines(cf.value).forEach(pushAc);
     const sections = custom
         .filter((cf) => cf.bucket !== "acceptance")
         .map((cf) => ({ title: cf.name, body: cf.value, bucket: cf.bucket }));
+    const images = (issue.attachments ?? []).filter((a) => /^image\//i.test(a.mimeType));
     const ticketBody = [
         issue.description,
         ...sections.map((s) => `### ${s.title}\n${s.body}`),
+        images.length
+            ? `### Attachments (images)\n${images
+                .map((a) => `- [${a.filename}](${a.url})`)
+                .join("\n")}`
+            : "",
     ]
         .filter((s) => s && s.trim())
         .join("\n\n");
@@ -175,6 +289,18 @@ export function flattenAdf(node) {
         if (url)
             return type === "inlineCard" ? url : `${url}\n`;
     }
+    if (type === "taskItem") {
+        const attrs = isRecord(node["attrs"]) ? node["attrs"] : {};
+        if (attrs["state"] !== "DONE")
+            return "";
+        return `- [x] ${flattenAdf(node["content"]).trim()}\n`;
+    }
+    if (type === "tableRow") {
+        const cells = Array.isArray(node["content"])
+            ? node["content"].map((c) => flattenAdf(c).trim().replace(/\s*\n\s*/g, " · "))
+            : [];
+        return `${cells.join(" | ")}\n`;
+    }
     const inner = flattenAdf(node["content"]);
     const blockTypes = new Set([
         "paragraph",
@@ -184,6 +310,8 @@ export function flattenAdf(node) {
         "listItem",
         "codeBlock",
         "blockquote",
+        "table",
+        "taskList",
     ]);
     if (type === "hardBreak")
         return "\n";
@@ -256,13 +384,17 @@ function resolveUrl(issue, fields, key, baseUrl) {
     if (direct)
         return direct;
     const self = str(issue["self"]);
-    if (self) {
+    const selfOrigin = (() => {
         try {
-            return `${new URL(self).origin}/browse/${key}`;
+            const u = new URL(self);
+            return u.hostname === "api.atlassian.com" ? undefined : u.origin;
         }
         catch {
+            return undefined;
         }
-    }
+    })();
+    if (selfOrigin)
+        return `${selfOrigin}/browse/${key}`;
     if (baseUrl) {
         try {
             return `${new URL(baseUrl).origin}/browse/${key}`;
@@ -270,6 +402,13 @@ function resolveUrl(issue, fields, key, baseUrl) {
         catch {
         }
     }
+    if (self) {
+        try {
+            return `${new URL(self).origin}/browse/${key}`;
+        }
+        catch {
+        }
+    }
     return undefined;
 }
 function nestedName(v) {

package/dist/_core/dist/jira/mcp-client.js

@@ -90,6 +90,7 @@ export async function connectJira(opts = {}) {
     }
     return makeJiraClient(await clientToToolCaller(client), {
         dialect: ROVO_DIALECT,
+        ...(opts.baseUrl ? { baseUrl: opts.baseUrl } : {}),
     });
 }
 export async function connectMcpServer(cfg) {

package/dist/_core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raptor/core",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "main": "dist/index.js"
 }

package/dist/_core/templates/spec.md.hbs

@@ -111,8 +111,9 @@ and assets are incorporated, catalogued and present on disk — no loose ends.
 {{jiraTicketBody}}
 
 <!--
-Imported VERBATIM from Jira {{jira}} — the description PLUS every rich custom field
-(scenarios, requirements, test caveats, documentation/design links) the card holds.
+Imported VERBATIM from Jira {{jira}} — the description PLUS every STORY-relevant custom
+field (scenarios, requirements, test caveats, documentation/design links) the card holds;
+card-config fields (workflow enums, form templates, tracking metadata) were filtered out.
 This is the authoritative source for this feature. The agent MUST redistribute ALL of
 it into the canonical sections below, LOSING NOTHING (each `### <field>` block too):
   - each user story / "História" → ## User Stories (as [US#] with priority, why, independent test)
@@ -123,6 +124,7 @@ it into the canonical sections below, LOSING NOTHING (each `### <field>` block t
   - test caveats / "Ressalvas de testes" → ## Edge Cases (or the relevant [NFR-#])
   - the ticket's out-of-scope / "Fora do Escopo" list → ## Out of Scope
   - design / documentation links (Figma etc.) → ## Dependencies & Assumptions
+  - "### Attachments (images)" → ## Design Reference / Dependencies & Assumptions (visual sources)
 Then REDUCE this section to a crisp problem statement (who is affected today and how). Do not leave the raw dump here.
 -->
 {{else}}{{#if description}}

package/dist/commands/jira/pull.js

@@ -1,6 +1,6 @@
 import { Args, Flags } from "@oclif/core";
 import { BaseCommand } from "../../base-command.js";
-import { mapIssueToSpecContext } from "../../_core/dist/index.js";
+import { filterCustomFields, mapIssueToSpecContext } from "../../_core/dist/index.js";
 import { readConfig, requireProjectRoot } from "../../shared/project.js";
 import { jiraConn, openJiraInteractive } from "../../shared/jira.js";
 export default class JiraPull extends BaseCommand {
@@ -61,5 +61,11 @@ export default class JiraPull extends BaseCommand {
             for (const line of s.body.split("\n"))
                 this.log(`    ${line}`);
         }
+        const total = (issue.customFields ?? []).length;
+        const kept = filterCustomFields(issue.customFields ?? [], conn.customFields).length;
+        if (total > kept) {
+            this.log(`\n  (${total - kept} of ${total} custom fields filtered as card config — ` +
+                `inspect with --json; force-keep via jira.custom_fields in raptor.yml)`);
+        }
     }
 }

package/dist/shared/jira.js

@@ -1,6 +1,6 @@
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { connectJira, connectMcpServer, hasStoredTokens, parseSpec, } from "../_core/dist/index.js";
+import { connectJira, connectMcpServer, filterCustomFields, hasStoredTokens, parseSpec, } from "../_core/dist/index.js";
 import { featureDir, readConfig } from "./project.js";
 export function jiraConn(config) {
     const j = config.jira;
@@ -10,6 +10,7 @@ export function jiraConn(config) {
     const common = {
         provider,
         ...(j.project_key ? { projectKey: j.project_key } : {}),
+        ...(j.base_url ? { baseUrl: j.base_url } : {}),
         statusSync: j.status_sync !== false,
         transitions: j.transitions ?? {},
         customFields: j.custom_fields ?? {},
@@ -36,7 +37,7 @@ export async function openJiraClient(conn) {
             throw new Error("Jira 'mcp' provider has no server config.");
         return connectMcpServer(conn.mcp);
     }
-    return openJiraNonInteractive(conn.serverUrl);
+    return openJiraNonInteractive(conn.serverUrl, conn.baseUrl);
 }
 export async function openJiraInteractive(conn) {
     if (conn.provider === "mcp") {
@@ -44,11 +45,15 @@ export async function openJiraInteractive(conn) {
             throw new Error("Jira 'mcp' provider has no server config.");
         return connectMcpServer(conn.mcp);
     }
-    return connectJira(conn.serverUrl ? { serverUrl: conn.serverUrl } : {});
+    return connectJira({
+        ...(conn.serverUrl ? { serverUrl: conn.serverUrl } : {}),
+        ...(conn.baseUrl ? { baseUrl: conn.baseUrl } : {}),
+    });
 }
-export async function openJiraNonInteractive(serverUrl) {
+export async function openJiraNonInteractive(serverUrl, baseUrl) {
     return connectJira({
         ...(serverUrl ? { serverUrl } : {}),
+        ...(baseUrl ? { baseUrl } : {}),
         onAuthorizationUrl: () => {
             throw new Error("re-authorization required");
         },
@@ -81,7 +86,7 @@ export async function refreshJiraSidecar(cmd, root, feature, dir) {
     }
     try {
         const issue = await client.getJiraIssue(conn.cloudId, storyKey);
-        writeFileSync(join(dir, "jira-refresh.md"), renderRefresh(issue));
+        writeFileSync(join(dir, "jira-refresh.md"), renderRefresh(issue, conn.customFields));
         cmd.log(`  ↪ Jira ${storyKey}: refreshed → jira-refresh.md`);
     }
     catch (err) {
@@ -91,7 +96,7 @@ export async function refreshJiraSidecar(cmd, root, feature, dir) {
         await client.close();
     }
 }
-function renderRefresh(issue) {
+function renderRefresh(issue, fieldOverrides = {}) {
     const lines = [
         `# Jira refresh — ${issue.key}`,
         "",
@@ -113,9 +118,15 @@ function renderRefresh(issue) {
         for (const ac of issue.acceptanceCriteria)
             lines.push(`- ${ac}`);
     }
-    for (const cf of issue.customFields ?? []) {
+    for (const cf of filterCustomFields(issue.customFields ?? [], fieldOverrides)) {
         lines.push("", `## ${cf.name}`, "", cf.value);
     }
+    const images = (issue.attachments ?? []).filter((a) => /^image\//i.test(a.mimeType));
+    if (images.length) {
+        lines.push("", "## Attachments (images)");
+        for (const a of images)
+            lines.push(`- [${a.filename}](${a.url})`);
+    }
     if (issue.comments.length) {
         lines.push("", "## Recent comments");
         for (const c of issue.comments.slice(-5)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raptor-aios",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Raptor — Spec-Driven Development (SDD) CLI for modern mobile apps. Constitutional gates, audit trail, real verification (a11y/perf/stores/OS matrix), and AI-agent slash commands.",
   "type": "module",
   "bin": {

package/scripts/prepare-npm.mjs

@@ -29,7 +29,7 @@ const CLI = join(ROOT, "packages", "cli");
 const CORE = join(ROOT, "packages", "core");
 const OUT = join(ROOT, "build", "npm");
 
-const VERSION = "0.9.0";
+const VERSION = "0.10.0";
 
 function log(msg) {
   process.stdout.write(`  ${msg}\n`);