raptor-aios 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.8.0] - 2026-06-09
+
+### Added
+
+- **`raptor new --jira` now seeds the spec from the WHOLE card, not just its description.** A ticket's scenarios, requirements, acceptance criteria, test caveats and design/documentation links — wherever they live — are captured, kept verbatim, and routed into the spec for the agent to redistribute (enforced by `gate.spec.ready`, not a brittle extractor). Four parts:
+  - **Fetch-all** — the `mcp-atlassian` dialect requests `fields="*all"` with `expand="names,renderedFields"` instead of six fixed fields, so custom fields and the id→label map come back.
+  - **Link preservation** — `flattenAdf` now surfaces a link mark's `href` (as `[text](url)`) and smart-link card URLs (`inlineCard`/`blockCard`/`embedCard`), so a Figma link embedded in the body survives flattening and re-enables the `design/` scaffold + `gate.design.ready`.
+  - **Rich custom fields** — `JiraIssue` gains `customFields[]` (id, human label, value, canonical bucket). A PT/EN classifier (`classifyField`) routes "Critérios de aceite", "Cenários", "Requisitos", "Fora do escopo", "Documentação"… into the right section; `flattenFieldValue` tolerates ADF/select/multi-select shapes. Nothing is dropped — an unrecognised field falls to an appendix.
+  - **Verbatim ticket body** — `mapIssueToSpecContext` builds `jiraTicketBody` (description + labelled `### <field>` sections), folds acceptance-bucket fields into the AC list (de-duped, feeding `acceptance.ids`/M7), and the `spec.md` Problem Statement dumps it with explicit redistribution instructions. `raptor jira pull` and the clarify-time `jira-refresh.md` surface the same fields.
+- **New `jira.custom_fields` config** — deterministic `id`/`label → bucket` overrides for servers that don't honour `expand=names`.
+- **New docs** — `docs/jira-spec-enrichment.md` documents how the card is captured, how the agent is instructed, and how the gates validate it (anchored on a real card).
+
+### Internal
+
+- New `extractCustomFields` / `classifyField` / `flattenFieldValue` and `MapIssueOptions` in `jira/mapper.ts`; `JiraCustomField` / `JiraFieldBucket` types. A test proves `gate.spec.ready` blocks an approved-but-un-redistributed Jira seed on three independent axes (leftover `[PREENCHER]`, uncovered user stories, unmirrored `acceptance.ids`) — locking in "Raptor delivers verbatim, the agent redistributes, the gate enforces". Verified end-to-end against the real KAN-2 card.
+
 ## [0.7.1] - 2026-06-08
 
 ### Fixed

package/README.md

@@ -471,6 +471,8 @@ raptor jira pull APP-1234           # importa a issue
 raptor new login --jira APP-1234    # semeia a spec a partir da issue
 ```
 
+> 📖 Como o card é capturado **por inteiro** (campos ricos, links de Figma) e redistribuído na spec — com os gates cobrando: veja [docs/jira-spec-enrichment.md](docs/jira-spec-enrichment.md).
+
 ---
 
 ## 📖 Referência de comandos CLI

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

@@ -52,7 +52,8 @@ export const MCP_ATLASSIAN_DIALECT = {
     args: {
         getIssue: (_cloudId, key) => ({
             issue_key: key,
-            fields: "summary,description,status,issuetype,labels,comment",
+            fields: "*all",
+            expand: "names,renderedFields",
             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, } from "./mcp-client.js";
 export { ROVO_DIALECT, MCP_ATLASSIAN_DIALECT, DIALECTS, resolveDialect, } from "./dialects.js";
-export { parseJiraIssue, parseCreatedIssue, extractComments, mapIssueToSpecContext, flattenAdf, extractAcceptanceCriteria, } from "./mapper.js";
+export { parseJiraIssue, parseCreatedIssue, extractComments, extractCustomFields, classifyField, flattenFieldValue, mapIssueToSpecContext, flattenAdf, extractAcceptanceCriteria, } from "./mapper.js";

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

@@ -17,6 +17,12 @@ export function parseJiraIssue(raw, baseUrl) {
         nestedName(fields["issue_type"]);
     const labels = strArray(fields["labels"]);
     const url = resolveUrl(issue, fields, key, baseUrl);
+    const names = isRecord(issue["names"])
+        ? issue["names"]
+        : isRecord(obj["names"])
+            ? obj["names"]
+            : {};
+    const customFields = extractCustomFields(fields, names);
     return {
         key,
         summary,
@@ -26,9 +32,57 @@ export function parseJiraIssue(raw, baseUrl) {
         labels,
         acceptanceCriteria: extractAcceptanceCriteria(fields, description),
         comments: extractComments(fields),
+        customFields,
         ...(url ? { url } : {}),
     };
 }
+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);
+        if (!value)
+            continue;
+        const name = str(names[id]) || id;
+        out.push({ id, name, value, bucket: classifyField(name) });
+    }
+    return out;
+}
+export function classifyField(label) {
+    const l = label.toLowerCase();
+    if (/aceite|aceita[çc][ãa]o|acceptance/.test(l))
+        return "acceptance";
+    if (/cen[áa]rio|scenario/.test(l))
+        return "scenarios";
+    if (/n[ãa]o[-\s]?funcional|non[-\s]?functional|\brnf\b/.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))
+        return "docs";
+    return "other";
+}
+export function flattenFieldValue(raw) {
+    if (raw == null)
+        return "";
+    if (typeof raw === "string")
+        return raw.trim();
+    if (Array.isArray(raw)) {
+        return raw.map(flattenFieldValue).filter(Boolean).join("\n").trim();
+    }
+    if (isRecord(raw)) {
+        if ("content" in raw || raw["type"] === "doc")
+            return flattenAdf(raw).trim();
+        const opt = str(raw["value"]) || str(raw["name"]);
+        if (opt)
+            return opt;
+        return flattenAdf(raw).trim();
+    }
+    return "";
+}
 export function parseCreatedIssue(raw) {
     const obj = coerceObject(raw);
     if (!obj)
@@ -58,11 +112,38 @@ export function extractComments(fields) {
     }
     return out;
 }
-export function mapIssueToSpecContext(issue) {
-    const ac = issue.acceptanceCriteria;
+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 ac = [];
+    const seen = new Set();
+    const pushAc = (line) => {
+        const t = line.trim();
+        if (t && !seen.has(t)) {
+            seen.add(t);
+            ac.push(t);
+        }
+    };
+    issue.acceptanceCriteria.forEach(pushAc);
+    for (const cf of custom)
+        if (cf.bucket === "acceptance")
+            toLines(cf.value).forEach(pushAc);
+    const sections = custom
+        .filter((cf) => cf.bucket !== "acceptance")
+        .map((cf) => ({ title: cf.name, body: cf.value, bucket: cf.bucket }));
+    const ticketBody = [
+        issue.description,
+        ...sections.map((s) => `### ${s.title}\n${s.body}`),
+    ]
+        .filter((s) => s && s.trim())
+        .join("\n\n");
     return {
         jiraSummary: issue.summary,
         jiraDescription: issue.description,
+        jiraTicketBody: ticketBody,
         jiraStatus: issue.status ?? "",
         jiraIssueType: issue.issueType ?? "",
         jiraUrl: issue.url ?? "",
@@ -71,6 +152,7 @@ export function mapIssueToSpecContext(issue) {
         jiraAcceptanceNumbered: ac.map((text, i) => ({ n: i + 1, text })),
         jiraAcceptanceNextN: ac.length + 1,
         jiraHasAcceptance: ac.length > 0,
+        jiraCustomSections: sections,
     };
 }
 export function flattenAdf(node) {
@@ -82,8 +164,17 @@ export function flattenAdf(node) {
         return node.map(flattenAdf).join("");
     if (!isRecord(node))
         return "";
-    if (typeof node["text"] === "string")
-        return node["text"];
+    if (typeof node["text"] === "string") {
+        const text = node["text"];
+        const href = linkHref(node["marks"]);
+        return href && href !== text ? `[${text}](${href})` : text;
+    }
+    const type = str(node["type"]);
+    if (type === "inlineCard" || type === "blockCard" || type === "embedCard") {
+        const url = cardUrl(node["attrs"]);
+        if (url)
+            return type === "inlineCard" ? url : `${url}\n`;
+    }
     const inner = flattenAdf(node["content"]);
     const blockTypes = new Set([
         "paragraph",
@@ -94,7 +185,6 @@ export function flattenAdf(node) {
         "codeBlock",
         "blockquote",
     ]);
-    const type = str(node["type"]);
     if (type === "hardBreak")
         return "\n";
     if (type === "listItem")
@@ -103,16 +193,40 @@ export function flattenAdf(node) {
         return `${inner}\n`;
     return inner;
 }
+function linkHref(marks) {
+    if (!Array.isArray(marks))
+        return undefined;
+    for (const m of marks) {
+        if (isRecord(m) && m["type"] === "link" && isRecord(m["attrs"])) {
+            const href = m["attrs"]["href"];
+            if (typeof href === "string" && href)
+                return href;
+        }
+    }
+    return undefined;
+}
+function cardUrl(attrs) {
+    if (!isRecord(attrs))
+        return undefined;
+    const url = attrs["url"];
+    if (typeof url === "string" && url)
+        return url;
+    const data = attrs["data"];
+    if (isRecord(data) && typeof data["url"] === "string" && data["url"]) {
+        return data["url"];
+    }
+    return undefined;
+}
 export function extractAcceptanceCriteria(fields, description) {
     for (const [k, v] of Object.entries(fields)) {
-        if (!/acceptance/i.test(k))
+        if (!/acceptance|aceite|aceita[çc]/i.test(k))
             continue;
         const flat = flattenAdf(v);
         const lines = toLines(flat);
         if (lines.length)
             return lines;
     }
-    const m = description.match(/acceptance\s+criteria\s*:?\s*\n([\s\S]+?)(?:\n\s*\n|$)/i);
+    const m = description.match(/(?:acceptance\s+criteria|crit[ée]rios?\s+de\s+aceita[çc][ãa]o|crit[ée]rios?\s+de\s+aceite)\s*:?\s*\n([\s\S]+?)(?:\n\s*\n|$)/i);
     if (m && m[1]) {
         const lines = toLines(m[1]);
         if (lines.length)

package/dist/_core/package.json

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

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

@@ -88,18 +88,22 @@ and assets are incorporated, catalogued and present on disk — no loose ends.
 {{/if}}
 
 ## Problem Statement
-{{#if jiraDescription}}
-{{jiraDescription}}
+{{#if jiraTicketBody}}
+{{jiraTicketBody}}
 
 <!--
-Imported VERBATIM from Jira {{jira}} — this is the full ticket body, the authoritative source for this feature.
-The agent MUST redistribute this content into the canonical sections below, LOSING NOTHING:
+Imported VERBATIM from Jira {{jira}} — the description PLUS every rich custom field
+(scenarios, requirements, test caveats, documentation/design links) the card holds.
+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)
   - each functional requirement / "Requisito Funcional / RF" → ## Functional Requirements (as [FR-#])
   - each non-functional requirement / "Requisito Não Funcional / RNF" → ## Non-Functional Requirements (as [NFR-#])
+  - each applicable scenario / "Cenário aplicável" → ## User Scenarios & Testing (and a covering [AC-#])
   - each acceptance scenario / "Critério de Aceitação / Cenário" → ## Acceptance Criteria (as [AC-#] Given/When/Then, covering a [US#])
+  - 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 links (Figma etc.) → ## Dependencies & Assumptions
+  - design / documentation links (Figma etc.) → ## Dependencies & Assumptions
 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

@@ -36,7 +36,7 @@ export default class JiraPull extends BaseCommand {
             this.log(JSON.stringify(issue, null, 2));
             return;
         }
-        const ctx = mapIssueToSpecContext(issue);
+        const ctx = mapIssueToSpecContext(issue, { fieldBuckets: conn.customFields });
         this.log(`=== ${issue.key} — ${issue.summary} ===\n`);
         if (issue.issueType)
             this.log(`  Type:    ${issue.issueType}`);
@@ -56,5 +56,10 @@ export default class JiraPull extends BaseCommand {
             for (const ac of ctx.jiraAcceptance)
                 this.log(`    - ${ac}`);
         }
+        for (const s of ctx.jiraCustomSections) {
+            this.log(`\n  ${s.title} [${s.bucket}]:`);
+            for (const line of s.body.split("\n"))
+                this.log(`    ${line}`);
+        }
     }
 }

package/dist/commands/new.js

@@ -138,7 +138,7 @@ export default class New extends BaseCommand {
             ? [
                 flags.desc,
                 jiraContext?.jiraSummary,
-                jiraContext?.jiraDescription,
+                jiraContext?.jiraTicketBody,
             ]
                 .filter(Boolean)
                 .join("\n")
@@ -447,7 +447,12 @@ export default class New extends BaseCommand {
         }
         try {
             const issue = await client.getJiraIssue(conn.cloudId, key);
-            return { ok: true, context: mapIssueToSpecContext(issue) };
+            return {
+                ok: true,
+                context: mapIssueToSpecContext(issue, {
+                    fieldBuckets: conn.customFields,
+                }),
+            };
         }
         catch (err) {
             return {

package/dist/shared/jira.js

@@ -12,6 +12,7 @@ export function jiraConn(config) {
         ...(j.project_key ? { projectKey: j.project_key } : {}),
         statusSync: j.status_sync !== false,
         transitions: j.transitions ?? {},
+        customFields: j.custom_fields ?? {},
     };
     if (provider === "mcp") {
         if (!j.mcp?.command)
@@ -112,6 +113,9 @@ function renderRefresh(issue) {
         for (const ac of issue.acceptanceCriteria)
             lines.push(`- ${ac}`);
     }
+    for (const cf of issue.customFields ?? []) {
+        lines.push("", `## ${cf.name}`, "", cf.value);
+    }
     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.7.1",
+  "version": "0.8.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.7.1";
+const VERSION = "0.8.0";
 
 function log(msg) {
   process.stdout.write(`  ${msg}\n`);