@mmerterden/multi-agent-pipeline 20.11.1 → 20.13.0

package/pipeline/lib/analysis-quality.mjs

@@ -0,0 +1,261 @@
+/**
+ * analysis-quality.mjs  -  document-quality checks on a rendered analysis
+ * document: every use case says how it fails, the document does not contradict
+ * itself, each layer carries only its own kind of content, and a design frame
+ * belongs to a use case.
+ *
+ * Each check takes the document's lines and returns `{errors, warns}` so the
+ * validator stays the only place that prints and decides the exit code.
+ *
+ * @module pipeline/lib/analysis-quality
+ */
+
+import { sectionBody, tableDataRows } from "./analysis-sections.mjs";
+
+const cellsOf = (row) =>
+  row
+    .trim()
+    .replace(/^\||\|$/g, "")
+    .split("|")
+    .map((c) => c.trim());
+const unbold = (s) => s.replace(/\*\*/g, "").trim();
+const isHeading = (l) => /^#{1,6}\s/.test(l);
+const isNumberedHeading = (l) => /^#{2,4}\s+\d+(\.\d+)*\.?\s/.test(l);
+const UC_HEADING = /\bUC-\d{2,3}\b/;
+
+const MAIN_FLOW = ["Ana Akış", "Ana Akis", "Main Flow"];
+const EXCEPTION_FLOW = ["İstisna Akışı", "Istisna Akisi", "Exception Flow"];
+const EXPLICIT_NONE = /^(yok|none)\s*:\s*\S/i;
+
+/** Use-case sections: from a heading naming `UC-NNN` up to the next numbered heading. */
+function useCaseBlocks(lines) {
+  const blocks = [];
+  let current = null;
+  for (const l of lines) {
+    if (isHeading(l)) {
+      const uc = l.match(UC_HEADING);
+      if (uc && isNumberedHeading(l)) {
+        current = { id: uc[0], lines: [] };
+        blocks.push(current);
+        continue;
+      }
+      if (isNumberedHeading(l) || /^#\s/.test(l)) current = null;
+    }
+    if (current) current.lines.push(l);
+  }
+  return blocks;
+}
+
+function fieldRow(lines, names) {
+  for (const l of lines) {
+    if (!l.trim().startsWith("|")) continue;
+    const c = cellsOf(l);
+    if (c.length >= 2 && names.some((n) => unbold(c[0]).toLowerCase() === n.toLowerCase())) {
+      return c[1];
+    }
+  }
+  return undefined;
+}
+
+/**
+ * A use case with a main flow states its exception flow. Missing is an error on
+ * a final document and a warning on a draft; "-" or empty is a warning;
+ * "Yok: <reason>" / "None: <reason>" is an explicit answer.
+ */
+export function exceptionFlow(lines, { final = false } = {}) {
+  const errors = [];
+  const warns = [];
+  for (const uc of useCaseBlocks(lines)) {
+    if (fieldRow(uc.lines, MAIN_FLOW) === undefined) continue;
+    const v = fieldRow(uc.lines, EXCEPTION_FLOW);
+    if (v === undefined) {
+      const msg = `${uc.id} has a main flow but no exception flow row (İstisna Akışı / Exception Flow)`;
+      (final ? errors : warns).push(msg);
+    } else if (!v || /^\p{Pd}$/u.test(v)) {
+      warns.push(
+        `${uc.id} exception flow is empty; write the failure path, or "Yok: <reason>" when there is none`,
+      );
+    } else if (/^(yok|none)\.?$/i.test(v) && !EXPLICIT_NONE.test(v)) {
+      warns.push(`${uc.id} exception flow says none without a reason ("Yok: <reason>")`);
+    }
+  }
+  return { errors, warns };
+}
+
+const normalize = (s) =>
+  s
+    .toLocaleLowerCase("tr")
+    .replace(/[.,;:!?"'`*_]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+
+const GOALS_KEYWORDS = [
+  "Hedefler ve Karşı Hedefler",
+  "Hedefler ve Karsi Hedefler",
+  "Goals and Non-Goals",
+  "Goals",
+];
+
+/** The same item on both sides of the goals table. */
+export function scopeOverlap(lines) {
+  const errors = [];
+  const body = sectionBody(lines, GOALS_KEYWORDS);
+  if (!body) return { errors, warns: [] };
+  const goals = new Map();
+  const nonGoals = new Set();
+  for (const row of tableDataRows(body)) {
+    const c = cellsOf(row);
+    if (c.length < 2) continue;
+    if (c[0] && c[0] !== "-") goals.set(normalize(c[0]), c[0]);
+    if (c[1] && c[1] !== "-") nonGoals.add(normalize(c[1]));
+  }
+  for (const [key] of goals) {
+    if (key && nonGoals.has(key)) {
+      errors.push(`"${key}" is both in scope and out of scope in the goals table (Locked 14)`);
+    }
+  }
+  return { errors, warns: [] };
+}
+
+const CITABLE = [
+  /\bBR-[a-z0-9]+(?:-[a-z0-9]+)*-\d+\b/gi,
+  /\bCB-[a-z0-9]+(?:-[a-z0-9]+)*-\d+\b/gi,
+  /\b(?:IG|FG)-\d{2,3}\b/g,
+  /\bUC-\d{2,3}\b/g,
+];
+
+/**
+ * Ids the text cites but never defines. An id is defined by the first cell of a
+ * table row or by a heading. Section 20 `AS-NN` ids have their own pairing check.
+ */
+export function citedUndefined(lines) {
+  const defined = new Set();
+  const cited = new Set();
+  for (const l of lines) {
+    const t = l.trim();
+    const sources = [];
+    if (isHeading(t)) {
+      sources.push([t, defined]);
+    } else if (t.startsWith("|")) {
+      const c = cellsOf(t);
+      sources.push([unbold(c[0] || ""), defined], [c.slice(1).join(" | "), cited]);
+    } else {
+      sources.push([t, cited]);
+    }
+    for (const [chunk, set] of sources) {
+      for (const re of CITABLE) {
+        for (const m of chunk.matchAll(re)) set.add(m[0].toUpperCase());
+      }
+    }
+  }
+  const errors = [...cited]
+    .filter((id) => !defined.has(id))
+    .sort()
+    .map((id) => `${id} is cited but never defined (no table row or heading names it)`);
+  return { errors, warns: [] };
+}
+
+const FIGMA_FRAME = /https:\/\/(?:www\.)?figma\.com\/[^\s)|\]]*node-id=([0-9]+[-:][0-9]+)/g;
+const REFERENCES = /Referans|References/i;
+
+/** A Figma frame linked outside every use case and outside the references (corporate). */
+export function designFrameUnmapped(lines) {
+  const warns = [];
+  let inUc = false;
+  let inRefs = false;
+  for (const l of lines) {
+    if (isHeading(l)) {
+      if (isNumberedHeading(l) || /^#\s/.test(l)) {
+        inUc = UC_HEADING.test(l) && isNumberedHeading(l);
+        inRefs = REFERENCES.test(l) && /^##\s/.test(l);
+      } else if (/^##\s/.test(l)) {
+        inUc = false;
+        inRefs = false;
+      }
+      continue;
+    }
+    if (inUc || inRefs) continue;
+    for (const m of l.matchAll(FIGMA_FRAME)) {
+      warns.push(
+        `design frame ${m[1]} is linked outside every use case; list it under the use case it serves`,
+      );
+    }
+  }
+  return { errors: [], warns };
+}
+
+const PART_A = new Set(["1", "2", "3", "4", "18", "19", "20"]);
+const REDESIGN_EVIDENCE = [
+  "Mevcut Davranış",
+  "Mevcut Davranis",
+  "Current Behaviour",
+  "Current Behavior",
+  "Endpoint Eşlemesi",
+  "Endpoint Eslemesi",
+  "Endpoint Mapping",
+];
+const CODE_PATH =
+  /[\w.-]+(?:\/[\w.-]+)+\.(?:swift|kt|kts|java|tsx?|jsx?|mjs|py|mm?|go|rb|cs|dart)\b/g;
+const ENDPOINT = /\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/[\w{}/.-]*/g;
+
+/**
+ * File paths and endpoints in the business layer (Part A: sections 1-4, 18-20) of
+ * the global profile. Collapsible `<details>` blocks and the redesign evidence
+ * tables are where such evidence belongs, so they are not read.
+ */
+export function businessLayerTechnical(lines) {
+  const warns = [];
+  let section = null;
+  let skip = false;
+  let details = 0;
+  for (const l of lines) {
+    const top = l.match(/^##\s+(\d+)\.?\s/);
+    if (top) {
+      section = top[1];
+      skip = false;
+      continue;
+    }
+    if (/^#\s/.test(l)) {
+      section = null;
+      continue;
+    }
+    if (/^#{3,4}\s/.test(l)) {
+      skip = REDESIGN_EVIDENCE.some((k) => l.includes(k));
+      continue;
+    }
+    details += (l.match(/<details\b/gi) || []).length;
+    const closes = (l.match(/<\/details>/gi) || []).length;
+    const inDetails = details > 0;
+    details = Math.max(0, details - closes);
+    if (!section || !PART_A.has(section) || skip || inDetails) continue;
+    for (const re of [CODE_PATH, ENDPOINT]) {
+      for (const m of l.matchAll(re)) {
+        warns.push(
+          `Section ${section} (business layer) names "${m[0].trim()}"; move it to Part B/C or into a <details> evidence block`,
+        );
+      }
+    }
+  }
+  return { errors: [], warns };
+}
+
+const PANEL = /^>\s*\*\*(Missing inputs|Eksik girdiler)\s*:?\s*\*\*/i;
+
+/** A final document that still lists missing inputs. */
+export function missingInputsFinal(lines, { final = false } = {}) {
+  if (!final) return { errors: [], warns: [] };
+  const start = lines.findIndex((l) => PANEL.test(l.trim()));
+  if (start < 0) return { errors: [], warns: [] };
+  let items = 0;
+  for (const l of lines.slice(start + 1)) {
+    const t = l.trim();
+    if (!t.startsWith(">")) break;
+    if (/^>\s*[-*]\s+\S/.test(t)) items++;
+  }
+  return {
+    errors: [],
+    warns: items
+      ? [`the document is final but its missing inputs panel lists ${items} input(s)`]
+      : [],
+  };
+}

package/pipeline/lib/analysis-sections.mjs

@@ -0,0 +1,105 @@
+/**
+ * analysis-sections.mjs  -  locate sections and table rows in a rendered
+ * analysis document.
+ *
+ * Shared by the document validator and the story-tree planner, so both read a
+ * section the same way. Sections are found by heading keyword, not by number:
+ * the global and corporate profiles number the same content differently, and a
+ * rendered document keeps canonical numbers with gaps.
+ *
+ * @module pipeline/lib/analysis-sections
+ */
+
+/**
+ * Body lines of the first numbered heading at one of `levels` whose text holds
+ * one of `keywords`. Closed by the next heading at the same level or shallower,
+ * so the last sub-section of a parent does not run into the following section.
+ *
+ * @param {string[]} lines
+ * @param {string[]} keywords
+ * @param {number|number[]} levels
+ * @returns {string[]|null}
+ */
+export function sectionBody(lines, keywords, levels = 2) {
+  for (const level of [].concat(levels)) {
+    const open = new RegExp(`^#{${level}}\\s+\\d+(\\.\\d+)*\\.?\\s`);
+    const close = new RegExp(`^#{1,${level}}\\s`);
+    const start = lines.findIndex((l) => open.test(l) && keywords.some((k) => l.includes(k)));
+    if (start < 0) continue;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+      if (close.test(lines[i])) {
+        end = i;
+        break;
+      }
+    }
+    return lines.slice(start + 1, end);
+  }
+  return null;
+}
+
+/**
+ * Data rows of the tables in `bodyLines`: the pipe-rows after a separator row,
+ * which is the only shape that tells them from the header without reading cells.
+ *
+ * @param {string[]} bodyLines
+ * @returns {string[]}
+ */
+export function tableDataRows(bodyLines) {
+  const rows = [];
+  let afterSeparator = false;
+  for (const line of bodyLines) {
+    const t = line.trim();
+    if (!t.startsWith("|")) {
+      afterSeparator = false;
+      continue;
+    }
+    if (/^\|[\s\-:|]+\|$/.test(t)) {
+      afterSeparator = true;
+      continue;
+    }
+    if (afterSeparator) rows.push(t);
+  }
+  return rows;
+}
+
+const CB_KEYWORDS = ["Mevcut Davranış", "Mevcut Davranis", "Current Behaviour", "Current Behavior"];
+const EP_KEYWORDS = ["Endpoint Eşlemesi", "Endpoint Eslemesi", "Endpoint Mapping"];
+const DL_KEYWORDS = ["Fark Listesi", "Difference List"];
+
+/**
+ * Where each redesign artefact lives per profile. The global profile has them as
+ * sub-sections 4.5, 4.6 and 9.5; the corporate profile nests them under its own
+ * spine (2.1.1, 2.3.1 and the endpoint mapping under Section 5 service details).
+ */
+export const REDESIGN_SECTIONS = {
+  global: {
+    cb: { keywords: CB_KEYWORDS, levels: [3], label: "4.5 Current Behaviour" },
+    ep: { keywords: EP_KEYWORDS, levels: [3], label: "4.6 Endpoint Mapping" },
+    dl: { keywords: DL_KEYWORDS, levels: [3], label: "9.5 Difference List" },
+  },
+  corporate: {
+    cb: { keywords: CB_KEYWORDS, levels: [4], label: "2.1.1 Mevcut Davranış / Current Behaviour" },
+    ep: {
+      keywords: EP_KEYWORDS,
+      levels: [4],
+      label: "5.(N+4).1 Endpoint Eşlemesi / Endpoint Mapping",
+    },
+    dl: { keywords: DL_KEYWORDS, levels: [4], label: "2.3.1 Fark Listesi / Difference List" },
+  },
+};
+
+/**
+ * The three redesign artefact bodies for a profile, plus their labels.
+ *
+ * @param {string[]} lines
+ * @param {string} profile
+ */
+export function redesignSections(lines, profile) {
+  const spec = REDESIGN_SECTIONS[profile] || REDESIGN_SECTIONS.global;
+  const out = {};
+  for (const [key, s] of Object.entries(spec)) {
+    out[key] = { body: sectionBody(lines, s.keywords, s.levels), label: s.label };
+  }
+  return out;
+}

package/pipeline/lib/jira-epic-link.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# jira-epic-link.sh  -  which fields link a new story to an existing epic.
+#
+# Jira links a story to its epic in two different ways. Cloud uses the standard
+# `parent` field; Server and Data Center use an "Epic Link" custom field whose id
+# differs per site. The id is discovered from the field list by its schema type,
+# never assumed. When no way is found the story is created without a link and a
+# warning says so, rather than writing a guessed field.
+#
+# Pure: the caller fetches /rest/api/2/serverInfo and /rest/api/2/field and
+# passes the JSON in, so the decision is testable offline.
+#
+#   epic_link_fields <mode> <epicKey> <fieldId> <serverInfoJson> <fieldsJson>
+#     mode: auto | parent | epicLinkField | none
+#   Prints a JSON object to merge into the create body's `fields`.
+
+EPIC_LINK_SCHEMA="com.pyxis.greenhopper.jira:gh-epic-link"
+
+epic_link_fields() {
+  local mode="${1:-auto}" epic="$2" field_id="$3" server="$4" fields="$5" deployment found
+  command -v jq >/dev/null 2>&1 || { echo "ERR: jq is required to link an epic" >&2; return 3; }
+  if [ -z "$epic" ] || [ "$mode" = "none" ]; then
+    printf '{}\n'
+    return 0
+  fi
+  case "$mode" in
+    parent)
+      jq -cn --arg e "$epic" '{parent: {key: $e}}'
+      return 0
+      ;;
+    epicLinkField)
+      if [ -z "$field_id" ]; then
+        echo "WARN: epicLinkField mode needs issueTree.epicLinkFieldId; the epic is not linked" >&2
+        printf '{}\n'
+        return 0
+      fi
+      jq -cn --arg f "$field_id" --arg e "$epic" '{($f): $e}'
+      return 0
+      ;;
+  esac
+  deployment="$(printf '%s' "$server" | jq -r '.deploymentType // empty' 2>/dev/null || true)"
+  if [ "$deployment" = "Cloud" ]; then
+    jq -cn --arg e "$epic" '{parent: {key: $e}}'
+    return 0
+  fi
+  found="${field_id:-$(printf '%s' "$fields" | jq -r --arg s "$EPIC_LINK_SCHEMA" \
+    '[.[]? | select(.schema.custom == $s) | .id] | first // empty' 2>/dev/null || true)}"
+  if [ -z "$found" ]; then
+    echo "WARN: no epic-link field on this site; the stories are created without an epic" >&2
+    printf '{}\n'
+    return 0
+  fi
+  jq -cn --arg f "$found" --arg e "$epic" '{($f): $e}'
+}

package/pipeline/lib/model-rung.sh

@@ -128,6 +128,13 @@ fi
 mv "$TMP" "$PREFS"
 trap - EXIT
 
+# Agents spawned without an explicit model run on their frontmatter, so the
+# installed fable-tier agents follow the switch in the same step.
+if command -v node >/dev/null 2>&1 && [ -f "$_MA_MR_HERE/agent-model-sync.mjs" ]; then
+  node "$_MA_MR_HERE/agent-model-sync.mjs" --prefs "$PREFS" ||
+    echo "model-rung: installed agents could not be updated; run node $_MA_MR_HERE/agent-model-sync.mjs" >&2
+fi
+
 echo "fable rung:    $CUR -> $WANT"
 echo "cost pricing:  $PRICING -> $WANT_PRICING"
 echo ""

package/pipeline/multi-agent-refs/analysis/locked.md

@@ -46,7 +46,7 @@ behind.
 ### Full list
 
 1. **One feature per run.** Every Figma URL, Confluence page, Jira ID, and Standards source the user supplies belongs to the **same feature**. The command never asks "which feature is this for?" or "which URL is primary?". Mixed inputs covering multiple features are treated as user error: surface the conflict, stop, and ask the user to split into separate runs.
-2. **Section omission rule.** Sections with zero evidence are dropped entirely; no `TBD` placeholder section. **A rendered section keeps its canonical template number**, so the set has gaps and that is correct: `1, 2, 4, 9, 13, 14, 21` is a valid rendered document. Numbering does NOT re-flow sequentially `1..N`: that cannot hold alongside Locked 30, which threads ids across sections BY NUMBER (`Section 15.1 scenario`, `Section 4.4`, `Section 3/5 layout cells`), so a re-flowed document sends every one of those cross-references to the wrong section or to nothing. What IS checked: every rendered number is a real template number, and the numbers ascend without repeating.
+2. **Section omission rule.** Sections with zero evidence are dropped entirely; no `TBD` placeholder section. **A rendered section keeps its canonical template number**, so the set has gaps and that is correct: `1, 2, 4, 9, 13, 14, 21` is a valid rendered document. Numbers are never rewritten into a sequential `1..N`, because Locked 30 threads ids across sections BY NUMBER (`Section 15.1 scenario`, `Section 4.4`, `Section 3/5 layout cells`) and renumbering would send every one of those cross-references to the wrong section or to nothing. What IS checked: every rendered number is a real template number, and the numbers ascend without repeating.
 3. **Citation discipline.** Every quoted UI string, endpoint path, error code, or analytics event name in Sections 2-4 must carry an inline citation: `[Figma annotation <nodeId>]` for copy taken from a Dev Mode annotation, `[Figma <nodeId>]` (MCP) or `[figma-export: <project-slug>/<screen-slug>:<nodeId>]` (local source) for design strings; `file:line` for repo evidence; `Confluence:<pageId>:<heading-slug>` for spec text. **Annotation-as-copy precedence:** when the project's `figma-config` has `annotations.enabled` and a node carries a Dev Mode annotation, that annotation is the authoritative copy for the node and the visible text layer is treated as a placeholder; cite the annotation, not the layer text. Never invent copy - blank beats a guess; a node whose annotation has the base language but is missing a target language emits a Section 20 (Risks) row rather than a fabricated value. Uncited quotes are downgraded to `[label TBD - see Open Questions]` and a row is added to Section 7 Risks. Subagent prose and Code Connect snippets are not citations.
 4. **The spec is forward-looking.** Section bodies describe the new feature as drawn / specified. Findings that exist only in legacy code or the existing branch appear as `> Legacy reference: <text> (file:line)` blockquotes inside the relevant section, never as the lead sentence or a primary table row. A legacy-only finding with no forward counterpart goes to Section 7 Risks as a decision item: "current code does X; should the new feature keep, change, or drop this?".
 5. **Output default = Local file.** The Phase 3.5 output picker keeps `Local file` pre-selected. Confluence and Jira outputs are never default-selected (see `analysis-output-confluence-on-request` memory).
@@ -56,13 +56,13 @@ behind.
 9. **Per-platform output split.** One markdown file is produced per selected platform under `analysis/<feature>-<platform>.md`. There is no merged single file. Section duplication follows the A3 hybrid table in `$HOME/.claude/multi-agent-refs/analysis-template.md` (Sections 1 + 4 duplicated verbatim; Sections 2, 3, 5, 6, 7 projected per platform). Each file carries a YAML front-matter header naming the feature, platform, generated-at timestamp, sibling file list, and binding standards source.
 10. **Output destination is asked after drafts exist.** Phase 3 renders each per-platform markdown to `/tmp/analysis-<feature-slug>-<timestamp>/` first. Only then does Phase 3.5 surface the output-destination picker (Local / Confluence / Jira). Drafts in `/tmp/` are the source of truth on resume; `/multi-agent:resume` re-uses them when `phase == awaiting_output_decision`.
 11. **Repo-evidence reuse-first.** Phase 1b runs a repo-evidence collector against each selected repo, producing 13 buckets (services, dtos, useCases, validationRules, domainEntities, routes, coordinators, diConfigurators, uiComponents, tokens, localizationKeys, testingIdentifiers, analyticsEvents) with each row tagged `direct-match | same-domain | cross-cutting`. Section 7 emits `Reuse existing X (file:line)` rows for `direct-match` items and advisory rows for `cross-cutting` items. New-write tasks for items that have a `direct-match` are downgraded to Risks ("existing X candidate found; reuse or document why a new one is needed").
-12. **MUST: Figma access - 3-tier fallback chain, pipeline-wide.** When any Figma URL or node ID is supplied (Phase 0 Step 5), Phase 1 establishes a Figma ground-truth artefact via the 3-tier chain before any UI synthesis runs: (1) Figma MCP `get_design_context` / `get_screenshot` / `get_metadata` for every referenced frame, with one re-auth retry on auth failure; (2) Figma REST API (`GET /v1/files/{fileKey}/nodes`, `GET /v1/images/{fileKey}`) using the PAT resolved through `~/.claude/lib/credential-store.sh get <logical-key>` where `<logical-key>` = `prefs.global.keychainMapping.figma`; (3) a user-attached screenshot as last resort. The tier in use is persisted as `state.figmaAccess.tier`. On Tier 1 the `CodeConnectSnippet` blocks name the exact target component consumed verbatim in Section 2 and Section 7. On Tier 2 the canonical-component decision falls back to the repo's `*.figma.swift` / `*.figma.kt` mappings keyed by `fileKey` + `nodeId`. On Tier 3 the canonical-component decision becomes "tier-3 best-fit pending design review" and produces a forced Open Question in Section 7 plus a Phase 4 `review_blocking` flag. Sound-alike alternatives, "more flexible" wrappers, and extrapolating from Confluence text-only "Component Kompozisyonu" / "Component Inventory" tables are forbidden in every tier. If all three tiers fail, halt the run and ask the user for access; never proceed with text-derived guesses. Section 7 architecture decisions must cite the node ID (Tier 1 or Tier 2) or the user-screenshot reference (Tier 3) for every UI atom row. Violations cost rebuild rounds (raw-primitive substitution; sound-alike-component swap). Generic rule rationale and checklist: see `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain (BLOCKING, pipeline-wide)". Memory: `[[figma-no-guesswork]]`. **A channel's design may not be called missing until the file tree has been scanned.** Run `figma-screenshot.sh --discover-sections --file-key <k> --feature-slug <s>`; sibling sections it returns join `evidence.figma[]` as their own entries and are never re-asked (Locked 1). Only an empty `candidates` list lets a channel be recorded as having no design, and the record must cite the scan (`fileKey`, `pagesScanned`, `tokensTried`). Declaring a channel missing without scanning fails the dispatch gate: one run did, and the sibling was sitting in the same file with nine frames in it.
+12. **MUST: Figma access - 3-tier fallback chain, pipeline-wide.** When any Figma URL or node ID is supplied (Phase 0 Step 5), Phase 1 establishes a Figma ground-truth artefact via the 3-tier chain before any UI synthesis runs: (1) Figma MCP `get_design_context` / `get_screenshot` / `get_metadata` for every referenced frame, with one re-auth retry on auth failure; (2) Figma REST API (`GET /v1/files/{fileKey}/nodes`, `GET /v1/images/{fileKey}`) using the PAT resolved through `~/.claude/lib/credential-store.sh get <logical-key>` where `<logical-key>` = `prefs.global.keychainMapping.figma`; (3) a user-attached screenshot as last resort. The tier in use is persisted as `state.figmaAccess.tier`. On Tier 1 the `CodeConnectSnippet` blocks name the exact target component consumed verbatim in Section 2 and Section 7. On Tier 2 the canonical-component decision falls back to the repo's `*.figma.swift` / `*.figma.kt` mappings keyed by `fileKey` + `nodeId`. On Tier 3 the canonical-component decision becomes "tier-3 best-fit pending design review" and produces a forced Open Question in Section 7 plus a Phase 4 `review_blocking` flag. Sound-alike alternatives, "more flexible" wrappers, and extrapolating from Confluence text-only "Component Kompozisyonu" / "Component Inventory" tables are forbidden in every tier. If all three tiers fail, halt the run and ask the user for access; never proceed with text-derived guesses. Section 7 architecture decisions must cite the node ID (Tier 1 or Tier 2) or the user-screenshot reference (Tier 3) for every UI atom row. Violations cost rebuild rounds (raw-primitive substitution; sound-alike-component swap). Generic rule rationale and checklist: see `$HOME/.claude/rules/figma-pipeline.md` "MUST: Figma access - 3-tier fallback chain (BLOCKING, pipeline-wide)". Memory: `[[figma-no-guesswork]]`. **A channel's design may not be called missing until the file tree has been scanned.** Run `figma-screenshot.sh --discover-sections --file-key <k> --feature-slug <s>`; sibling sections it returns join `evidence.figma[]` as their own entries and are never re-asked (Locked 1). Only an empty `candidates` list lets a channel be recorded as having no design, and the record must cite the scan (`fileKey`, `pagesScanned`, `tokensTried`). Declaring a channel missing without scanning fails the dispatch gate, because a channel's frames often sit in a sibling section of the same file.
 13. **Gherkin user stories.** Section 4 scenarios use Given / When / Then. Plain-prose user stories are rejected at render time.
 14. **Goals and Non-Goals are paired.** Section 2 always carries both columns. A row in only the goal column without an explicit non-goal counterpart is rejected. Vague "out of scope" phrasing does not satisfy the non-goal column; each non-goal names what is excluded.
 15. **New assets default to SVG.** Section 8 entries marked `new` are SVG unless a documented exception is captured in the rationale column (Lottie for motion design, optimized PNG for raster-only icons). PDF, JPG, and unoptimized PNG are rejected.
 16. **Files-to-Add tag mandatory.** Every row in Section 14 carries one tag from `Reuse | Add new | Modify`. Untagged rows fail the dispatch gate.
 17. **API response variants exhaustive.** Section 9 lists every HTTP status code returned by the endpoint with at least one example body and the matching UI outcome. Phrases like "other errors" or "various 4xx" are rejected.
-18. **Screenshots embedded, not linked, and every inventory row gets one.** Section 5 frame galleries reference local PNG files. Dispatch uploads them as Confluence multipart attachments and injects `<ac:image><ri:attachment ri:filename="..." /></ac:image>` into the page body. The gallery is generated from the inventory, never hand-picked: one row, one embedded image, ordered by node id and titled `<nodeId> <frame name>`. A bare filename in a table cell is text to the reader, not a picture, which is how a run that uploaded 34 attachments and embedded 14 of them was reported as "frames not uploaded" - the files were there and invisible. Narrowing to a canonical subset for page weight is not a call the run makes on its own; the display-width cap (`md2confluence-v3.py --image-width`, phone frames overriding to 320) already solves readability without dropping evidence. Dispatch reports the embedded-over-inventory ratio and warns below 1. URL-only Figma references in Section 5 are a review finding, not a validator ERROR: the check belongs to the Confluence dispatch step, which is the only place that knows whether an attachment upload succeeded.
+18. **Screenshots embedded, not linked, and every inventory row gets one.** Section 5 frame galleries reference local PNG files. Dispatch uploads them as Confluence multipart attachments and injects `<ac:image><ri:attachment ri:filename="..." /></ac:image>` into the page body. The gallery is generated from the inventory, never hand-picked: one row, one embedded image, ordered by node id and titled `<nodeId> <frame name>`. A bare filename in a table cell is text to the reader, not a picture: an attachment that is uploaded but not embedded is invisible on the page. Narrowing to a canonical subset for page weight is not a call the run makes on its own; the display-width cap (`md2confluence-v3.py --image-width`, phone frames overriding to 320) already solves readability without dropping evidence. Dispatch reports the embedded-over-inventory ratio and warns below 1. URL-only Figma references in Section 5 are a review finding, not a validator ERROR: the check belongs to the Confluence dispatch step, which is the only place that knows whether an attachment upload succeeded.
 19. **All Figma variants drilled, and drilled means read.** When a Figma section URL is supplied, all child frames are drilled, not just the canonical default. The renderer enumerates child frames via `mcp__claude_ai_Figma__get_metadata` (Tier 1) or `figma-screenshot.sh --section` (Tier 2) and produces one Section 5.1 row per child frame. Counting them is not drilling them: extract the visible `TEXT` layers inside each frame's own bounds, dropping hidden layers and component-instance boilerplate that overflows the frame (default card and widget filler can outnumber the real text several times over). A frame may be called out of scope only by quoting its own extracted text; "the name looked unrelated" is not a reason. Opening a Section 20 question about a frame requires that its text was extracted first, and asking about a frame nobody read fails the dispatch gate: a frame whose name looks ambiguous can spell out a whole step in its text.
 20. **Localization mode (ownership-aware).** Section 10's shape is driven by the project `figma-config` `localization.ownership` (default `in-repo`). The locale set comes from `localization.locales` (default `tr, en, ar, de, es, fr, it, ru`); do not hardcode a locale list in the render.
     - **`in-repo`** (default, historical behavior): new keys carry filled cells for every configured locale. Placeholder values `[bekleniyor: çeviri ekibi]` / `[pending: translation team]` are a soft state and the dispatch report flags `i18n_pending: <count>` as a blocker. Empty cells are rejected outright.
@@ -82,5 +82,5 @@ behind.
 32. **Corporate backbone always renders.** In the `corporate` profile the Locked 2 omission rule is replaced for Part A and the footer: those sections render even with zero evidence, carrying `N/A` when the section is genuinely out of scope for the feature and `EKLENECEK` when evidence is expected but missing. This is the point of a requirements document - a reader has to be able to tell "we considered hardware needs and there are none" from "nobody looked". Every `EKLENECEK` emits a matching Section 20 Risks and Open Questions row naming what is missing and who can answer it; an `EKLENECEK` with no such row fails the dispatch gate, because an unanswered question nobody owns is how a placeholder reaches production. **Missing inputs never block the run**: the corporate source practice of halting until every input arrives is deliberately not adopted - the document is produced with `EKLENECEK` in the gaps and the gaps are raised in Section 20. Part B follows the global omission table unchanged. In the `global` profile Locked 2 applies as written, with no placeholder of any kind.
 33. **References are built from the evidence record, not written.** Section 21 is emitted by `$HOME/.claude/scripts/build-references.mjs` from `state.analysisSpec.evidence.*` in both profiles. Each row carries a precision anchor in its `Sürüm / Ref` column - Figma node id, Confluence `pageId` plus page version, the commit SHA a repo was read at, the Swagger spec version - because a reference with no anchor points at a moving target. Each row carries an `Erişim / Access` cell: a declared source that could not be fetched still gets a row reading `erişilemedi (<reason>)`, since a silently dropped source reads to the next person as a source that never existed. User statements from the conversation that no fetched source contains are recorded as `Serbest metin` rows, quoted verbatim, with the decision they settled. **Coverage gate**: every entry in `evidence.figma[]`, `confluence[]`, `jira[]`, `swagger[]`, `repo[]`, `standards[]`, `firebase[]`, `documents[]`, `outside[]`, `freeText[]` and every entry in `evidence.fetchErrors[]` must appear as a row, and every row must map to an evidence entry. A source that shaped the document but is missing from References fails the dispatch gate; so does an invented row with no evidence behind it.
 34. **Stack-optional render.** Platform and repo selection are optional. When `state.analysisSpec.platforms[]` is empty, the run still completes: the analysis layers that do not need a target repository render in full - Part A and Part B in the corporate profile, Sections 1-12 and 16-17 in the global profile - and only the development layer is dropped (corporate Part C; global Sections 13, 14, 15) along with the Pass B projection, since there are no conventions to project onto. A Section 20 row records that the development analysis awaits a repo selection. **The channel split survives the missing repo.** Channels are derived from the evidence instead of repo stack tags (`intake.md` Step 3 carries the signal table) and one document is emitted per derived channel - `mobile`, `web`, or both. A phone screen and a browser screen carry different requirements before anyone has picked a repository; the split (Locked 9) exists to carry that difference and only its *projection* half needs conventions. `mobile` stays one channel rather than iOS plus Android, since without conventions nothing tells the two apart. Evidence with no interface at all yields a single channel-agnostic `<feature>.md`. Files land under `~/Desktop/multiAgentAnalysis/<feature-name>/`, named `<feature>-<channel>.md` (or `<feature>.md` for the channel-agnostic case): the repo-relative `analysis/` path has nothing to be relative to without a repo, and the current working directory is never used, since for a repo-less run it is arbitrary. Desktop rather than a hidden directory because the document is a deliverable somebody is meant to open and hand over, and `multiAgentAnalysis` rather than a bare `Analysis` because a generic word collides with whatever else is on a desktop while the producer name groups every run this command ever writes. The Phase 3.5 picker shows the resolved path and takes an override through its Other input. A requirements document is useful before anyone has decided which repository will hold the code, and refusing to produce one until that decision exists inverts the order the work actually happens in.
-35. **The document is reviewed before it is published.** An analysis run used to go from draft straight to dispatch behind a deterministic validator, so nothing read what it was about to publish: one run put a channel it never searched for, an open question about a frame it never opened, and twenty-three unowned `EKLENECEK` markers onto a live page. Every one is what a reader catches on the first pass. Phase 3.2 runs `phases/phase-3-review.md` Step 0 (strict validator, the host's three-reviewer set, triage) on the draft before the destination is chosen: a finding is cheap while nothing is written. Reviewers are subagents holding `analysis/review.md`, never the context that wrote the document, which cannot notice a search it never thought to run. A blocking finding returns to Phase 2b with dispatch closed and never becomes an open question, since "the document is wrong" is not something to ask the reader; capped at two returns. Phase 3.3 sorts every remaining gap into searched-and-closed, asked-and-answered, or `AS-NN`; an unstamped gap fails the dispatch gate. Autopilot runs both; only the asking degrades, into rows stamped `autopilot: could not ask`.
+35. **The document is reviewed before it is published.** A deterministic validator checks structure, not content: a channel nobody searched for, an open question about a frame nobody opened, and an unowned `EKLENECEK` marker all pass it, and every one is what a reader catches on the first pass. Phase 3.2 runs `phases/phase-3-review.md` Step 0 (strict validator, the host's three-reviewer set, triage) on the draft before the destination is chosen: a finding is cheap while nothing is written. Reviewers are subagents holding `analysis/review.md`, never the context that wrote the document, which cannot notice a search it never thought to run. A blocking finding returns to Phase 2b with dispatch closed and never becomes an open question, since "the document is wrong" is not something to ask the reader; capped at two returns. Phase 3.3 sorts every remaining gap into searched-and-closed, asked-and-answered, or `AS-NN`; an unstamped gap fails the dispatch gate. Autopilot runs both; only the asking degrades, into rows stamped `autopilot: could not ask`.
 36. **A redesign records v1 before it plans v2.** `options.redesign` is an opt-in on the `options.uiTests` axis, never a third `mode` value: `mode` says how many sections, `redesign` says which content, and a `mode: redesign` would switch off the Full-mode traceability, Test Plan and rule-to-test gates in exactly the documents that need them. It adds three sub-sections and no top-level section: current behaviour with `CB-<slug>-NN` ids and `repo/file:line` citations, the v1 to v2 endpoint mapping, and a difference list over a closed status vocabulary. Every `Missing` and `Partial` owes a Section 20 row by `AS-NN`, and a `CB-` id in one table but not the other fails in both directions - a behaviour that is in the code and on nobody's difference list is what a redesign loses and production finds. Evidence and certainty are derived from `repoEvidence`, never graded by the writer (Locked 24, same reason), and `options.redesign` is an `evidence_digest` input. Contract and the eight checks: `analysis/redesign.md`, loaded only on a redesign run.

package/pipeline/multi-agent-refs/analysis/redesign.md

@@ -41,7 +41,9 @@ intake opt-in, written into the front-matter, enforced by the validator's
 ## The three artefacts
 
 Section numbers are per profile. The global profile uses sub-sections of existing
-sections (4.5, 4.6, 9.5) and the corporate profile uses 2.1, 2.3 and 5.N+4; no
+sections (4.5, 4.6, 9.5) and the corporate profile nests them one level deeper in
+its own spine (2.1.1 current behaviour, 2.3.1 difference list, 5.(N+4).1 endpoint
+mapping); the validator looks each one up by profile. No
 new top-level section is introduced in either, because section numbers are quoted
 in 172 places and renumbering them to add a mode is a worse trade than nesting.
 

package/pipeline/multi-agent-refs/analysis/render.md

@@ -8,9 +8,11 @@
 
 1b. **Template selection** (Locked 31): read `state.analysisSpec.profile`. `global` renders against `$HOME/.claude/multi-agent-refs/analysis-template.md`; `corporate` renders against `$HOME/.claude/multi-agent-refs/analysis-template-corporate.md`. The evidence is the same either way - this step chooses the projection, nothing else. In the corporate profile the Part A backbone and the footer render even with zero evidence, carrying `N/A` or `EKLENECEK`, and each `EKLENECEK` emits its Section 20 row (Locked 32).
 
-2. **Markdown render**: for each platform in `state.analysisSpec.platforms[]`, concatenate the per-platform spec into one markdown file. Tables in pipe-syntax. Numbering uses plain `## 1.`, `## 2.`, ... - omitted sections do **not** create gaps. Visible numbering is sequential 1..N over the rendered set. In the corporate profile the Part A and footer numbers are fixed and do not re-flow, since the backbone never drops; Part B and Part C follow the omission table as usual.
+2. **Markdown render**: for each platform in `state.analysisSpec.platforms[]`, concatenate the per-platform spec into one markdown file. Tables in pipe-syntax. Each rendered section keeps its canonical number, so omitted sections leave gaps (Locked 2). Corporate Part A and footer never drop; Parts B and C follow the omission table.
 
-   **When `platforms[]` is empty** (Locked 34), the channels come from the evidence instead of from repo stack tags, so this loop runs once per derived channel (`mobile`, `web`, or one channel-agnostic pass). What drops is the development layer (corporate Part C, global Sections 13, 14, 15) and the Pass B projection are skipped, Section 20 carries a row recording that they await a repo selection, and the front-matter `platform` key reads `none`. Everything that does not need a target repository still renders in full.
+   **Missing inputs panel** above Section 1: `build-references.mjs "$STATE" --lang "$LANG" --missing-panel` (prints nothing when every source was read). "Not reachable" is never written as "does not exist".
+
+   **When `platforms[]` is empty** (Locked 34), the loop runs once per channel derived from the evidence (`mobile`, `web`, or one channel-agnostic pass). The development layer (corporate Part C, global Sections 13-15) and the Pass B projection are skipped, Section 20 records that they await a repo selection, and front-matter `platform` reads `none`. Everything else renders in full.
 
 3. **Humanizer pass (required: actually invoke the `ai-common-toolkit:humanizer` skill on the rendered markdown - the punctuation grep alone does NOT satisfy this step)** (`technical-explanatory` tone for the scratch buffer; per-channel re-humanize happens in Phase 4 when actually emitting):
    ```
@@ -21,7 +23,7 @@
      content: <markdown>
    ```
 
-   **Explicit punctuation policy** (enforced by `stripFancyPunctuation: true`): no em-dash (U+2014), no en-dash (U+2013), no horizontal ellipsis (U+2026), no curly quotes (U+2018, U+2019, U+201C, U+201D), no section sign (U+00A7). The humanizer replaces these with ASCII equivalents (`-`, `:`, `,`, `...`, `'`, `"`, and `bölüm` / `section` for the section sign per `outputLanguage`) before emit. Tables, code blocks, URLs, and front-matter YAML are exempt. Post-emit verification runs through `node $HOME/.claude/scripts/validate-analysis-doc.mjs <file>`, which checks this policy deterministically in Node on all three operating systems. Do NOT verify with `grep -P`: BSD grep (macOS, the pipeline's primary platform) has no `-P`, so that command never runs and "zero matches" is trivially true. The per-language readability rules (Turkish sentence shape, nominalization chains, which terms stay untranslated) live in the humanizer skill itself, not here; this paragraph owns only the punctuation policy the validator enforces. **Diacritics are PRESERVED, not stripped: this policy targets ONLY the listed fancy-punctuation codepoints. Turkish letters (ş/Ş, ç/Ç, ğ/Ğ, ı/I, İ, ö/Ö, ü/Ü) and all other `outputLanguage` letters MUST stay verbatim. Never ASCII-fold the prose - emit `Geliştirme Özeti`, `için`, `Kullanıcı Hikayeleri`, NOT `Gelistirme Ozeti`, `icin`, `Kullanici`. ASCII-folded Turkish is a humanizer-skipped smell and fails review.**
+   **Explicit punctuation policy** (enforced by `stripFancyPunctuation: true`): no em-dash (U+2014), no en-dash (U+2013), no horizontal ellipsis (U+2026), no curly quotes (U+2018, U+2019, U+201C, U+201D), no section sign (U+00A7). The humanizer replaces these with ASCII equivalents (`-`, `:`, `,`, `...`, `'`, `"`, and `bölüm` / `section` for the section sign per `outputLanguage`) before emit. Tables, code blocks, URLs, and front-matter YAML are exempt. Verify with `node $HOME/.claude/scripts/validate-analysis-doc.mjs <file>`, not a Perl-regex grep (BSD grep lacks it, so "zero matches" is trivially true). Readability rules live in the humanizer skill; this paragraph owns only the punctuation policy. **Diacritics are PRESERVED: only the listed codepoints are replaced. Turkish letters (ş, ç, ğ, ı, İ, ö, ü) stay verbatim; never ASCII-fold (`Geliştirme Özeti`, not `Gelistirme Ozeti`). ASCII-folded Turkish fails review.**
 
 3b. **Build Section 21 References** (Locked 33): emit the table with
 
@@ -207,36 +209,33 @@ Provenance:
 
 ## Confluence write (on-request only)
 
-Per the `analysis-output-confluence-on-request` memory, Confluence post is NEVER default-selected at Phase 3.5 (the output destination picker). Only when the user explicitly asks ("post this to Confluence", "create a page under the Coding Documentation parent", etc.) does the command:
+Confluence is NEVER default-selected at Phase 3.5. Only when the user explicitly asks to post does the command:
 
 1. Resolve the token via `~/.claude/lib/credential-store.sh get <key>`, where `<key>` is read from `prefs.global.keychainMapping.confluence` (per-user mapping; never hardcode the service name in this doc - see channel adapter doc `$HOME/.claude/multi-agent-refs/channels/confluence.md` for the lookup contract).
 2. Use parent page URL from user input. No default parent is hardcoded here; the user picks one at the prompt (LRU recents come from `prefs.projects[<project>].confluenceUrls`).
 
-   **Corporate profile exception.** When `state.analysisSpec.profile == "corporate"` and the bindings are configured, the destination is already settled and the prompt is skipped: the space comes from `prefs.global.analysisProfile.corporate.confluenceSpaceKey`, the parent from `prefs.global.analysisProfile.corporate.confluenceParentPageId`, and the page title is built from `prefs.global.analysisProfile.corporate.titleFormat` with `prefs.global.analysisProfile.corporate.titlePrefix` filling its `{prefix}` placeholder. A corporate analysis always lands in the same tree, so asking each time is a question whose answer never changes. Any of the four missing falls back to the prompt above rather than guessing, and a title that would collide with an existing page becomes an update (PUT with version bump), never a second page.
+   **Corporate profile exception.** With the bindings configured, the prompt is skipped: space `prefs.global.analysisProfile.corporate.confluenceSpaceKey`, parent `prefs.global.analysisProfile.corporate.confluenceParentPageId`, title from `prefs.global.analysisProfile.corporate.titleFormat` with `prefs.global.analysisProfile.corporate.titlePrefix` filling `{prefix}`. Any of the four missing falls back to the prompt; a colliding title becomes an update (PUT with version bump), never a second page.
 3. **Publish with `md2confluence-v3.py`, never a hand-rolled conversion + curl.** It
-   owns the three steps a hand-rolled path has already dropped: storage-XML conversion
-   (`channels/confluence.md`), the multipart upload of every PNG in `--attachments-dir`,
-   and the `![](file.png)` to `<ac:image><ri:attachment/>` injection that makes a frame
-   gallery render as pictures rather than filenames (Locked 18). It also warns when a
-   body references an image no attachment matched, which is how a missing screenshot
-   announces itself.
+   does the storage-XML conversion (`channels/confluence.md`), uploads every PNG in
+   `--attachments-dir`, injects `<ac:image><ri:attachment/>` so a frame gallery renders
+   as pictures (Locked 18), and warns on an image reference no attachment matched.
 
    ```bash
+   CONFLUENCE_BASE_URL="https://$(jq -r '.global.hosts.confluence // empty' "$HOME/.claude/multi-agent-preferences.json")"
+   export CONFLUENCE_BASE_URL
    python3 "$HOME/.claude/lib/md2confluence-v3.py" create \
      --space "$SPACE" --parent-page-id "$PARENT" --title "$TITLE" \
      --markdown "$DRAFT" --attachments-dir "$(dirname "$DRAFT")"
    # updating an existing page: `update --page-id <ID>` instead of `create --space ...`
    ```
 
-   Screenshots must already sit in `--attachments-dir` before this runs. Point
-   `figma-screenshot.sh --output-dir` at the draft directory during evidence
-   collection rather than letting it default to its own `/tmp` folder, because a
-   frame gallery whose PNGs live somewhere else converts to `<a href="frame-NNN.png">`
-   and the page shows filenames where the pictures should be. MCP asset URLs expire
-   after 7 days, so the cell must reference the local file, never the remote URL.
-4. Read the script's JSON envelope: it reports the page id and URL, every attachment
-   uploaded, and the `image reference has no matching attachment` warnings. A non-empty
-   warning list means the page shipped with missing pictures; surface it rather than
-   reporting a clean publish. Surface the page URL in the Phase 4 report.
+   Screenshots must already sit in `--attachments-dir`: point `figma-screenshot.sh
+   --output-dir` at the draft directory during evidence collection, or the gallery
+   renders filenames. MCP asset URLs expire after 7 days; cells reference the local file.
+   **Draft title:** while `status` is not `final`, prefix `[TASLAK] ` / `[DRAFT] ` (or fill the corporate `titleFormat` `{status}`); the final publish drops it.
+4. Read the script's JSON envelope (page id and URL, attachments, `image reference has
+   no matching attachment` warnings). A warning means missing pictures: surface it, not a
+   clean publish. Surface the page URL in the Phase 4 report.
+5. **Read the page back:** `confluence-readback.mjs --page-id "$PAGE_ID" --markdown "$DRAFT"`. Exit 1 names missing headings and unattached images; report it, never republish automatically.
 
 Token miss handling: surface a single line `WARN: Confluence token not configured (prefs.global.keychainMapping.confluence). Run /multi-agent:setup or skip Confluence output.` and continue with local-only output.

package/pipeline/multi-agent-refs/analysis/resolve.md

@@ -4,7 +4,7 @@
 >
 > The same three source labels drive `research/engine.md`, which generalises this walk to any gap list (maturity blockers, open questions) and adds a deterministic check of every cited source (`research-gate.mjs`) for runs nobody watches.
 >
-> The 31 inherited decisions are in `locked.md`; the ones below are this engine's own. Core invariant: the document is authoritative and forward-looking. The engine never invents an answer - when no source produces a credible candidate the only options are Defer and Other.
+> The 36 inherited decisions are in `locked.md`; the ones below are this engine's own. Core invariant: the document is authoritative and forward-looking. The engine never invents an answer - when no source produces a credible candidate the only options are Defer and Other.
 
 ## New Locked decisions (this command)