@mmerterden/multi-agent-pipeline 20.12.0 → 20.13.0

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)
 

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

@@ -102,14 +102,27 @@ The verdict names the profile it judged against, the counts per severity, and wh
 ```
 Verdict: 2 Blocker, 3 Important, 1 Suggestion   (profile: global, mode: full)
 
-  A evidence          2      D altitude          none
-  B backbone          none   E admitted gaps     1
-  C ...                      F contradiction     3
+  A buildability      2      D altitude          none
+  B evidence          none   E gaps              1
+  C spine             none   F contradiction     3
 
 Not checked: references coverage (no state file passed)
 Provenance:  evidence_digest sha256:1f3a9c2   base_commit 4c1b2de
+
+Publish ready: no
+Fix first:
+  1. [A] 4.4 BR-login-03 has no acceptance criterion
+  2. [A] 13.2 names no file for the session store
+  3. [F] 9.1 and 4.2 disagree on the code lifetime (3 min vs 5 min)
+Verified OK: front-matter, required sections, traceability, references (12 of 12)
 ```
 
+**Publish ready** is `yes` only with zero Blocker findings and a clean
+validator run. `Fix first` lists the Blocker and Important findings in the
+order they should be fixed, each with its class and section, so the author has
+a work list rather than a report. `Verified OK` names what was checked and
+held, with counts, so a clean area is distinguishable from an unexamined one.
+
 ## Phase 4 - Output
 
 Default is the chat report. Nothing is written anywhere without an explicit choice.

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

@@ -32,6 +32,14 @@ synthesizedSections = {
 | 6. Business + Tests | If sections 2 and 4 are both `null` AND `evidence.firebase[]` is empty → null. Otherwise produce use-case + mock stubs + per-platform test skeletons + shared Firebase events table. Reuse Red-Green-Refactor naming from `$HOME/.claude/rules/tdd.md`. |
 | 7. Development Plan | Always present. Tasks for the current platform only. Architecture standards come from `evidence.standards[]` filtered by platform (see Pass B step 1). **Reuse-first rule (Locked 11)**: when an item has `direct-match` in `evidence.repoEvidence[<repo>].buckets.<X>`, emit `Reuse existing <FQN> (<file>:<line>)` instead of `Add new <FQN>`. New-write task with a `direct-match` competitor becomes a Risk row. |
 
+#### Pass A - content rules
+
+- **Edge cases are proposals.** Failure paths the evidence states (refusal, error code, timeout, empty or expired state) go to `state.analysisSpec.edgeCandidates[]` (`{target, candidate, source}`) and the Pass B preview; only accepted ones enter the document. No source, no candidate.
+- **Nothing invented:** no event name, sample value or threshold without a source. Show the type; a missing event name is a Section 20 question.
+- **Unreadable is not absent.** A source that failed is listed in the missing-inputs panel and References; the body never infers absence from it.
+- **One question, one Section 20 row**, listing every section it affects.
+- Validator-enforced: an item is never both goal and non-goal (`scope-overlap`); every cited id is defined (`cited-undefined`); Part A carries no file path or endpoint outside `<details>` (`business-layer-technical`).
+
 #### Phase 2a - Pass B preview (Locked 25)
 
 Before Pass B renders any file, present the resolved convention table to the user via `AskUserQuestion` (`picker-contract.md`). The table is one row per concept, one column per selected platform.
@@ -86,7 +94,7 @@ For each `platform` in `state.analysisSpec.platforms[]`:
    - `android` → `~/.claude/rules/kotlin-android.md` first → `evidence.standards[]` entries whose path contains `android` or `kotlin`
    - `backend` → `evidence.standards[]` entries matching language hints (`python`, `go`, `node`, `fastapi`) → fall back to `~/.claude/rules/security.md` + `code-style.md`
    - `web` → `evidence.standards[]` entries matching `react`, `vue`, `next`, `sveltekit` → `~/.claude/rules/code-style.md`
-2. **Apply per-platform omission rules.** Backend-only file drops Sections 5, 6, 7, 8, 16. Web with no UI inventory still keeps 5 (UI exists in code). Sections 1, 2, 4, 9, 13, 14, 20, 21 always present per Locked decision 2 + 13; their numbers are canonical and never re-flowed.
+2. **Apply per-platform omission rules.** Backend-only file drops Sections 5, 6, 7, 8, 16. Web with no UI inventory still keeps 5 (UI exists in code). Sections 1, 2, 4, 9, 13, 14, 20, 21 always present per Locked decision 2 + 13; their numbers are canonical and never renumbered.
 3. **Resolve the section set from evidence, not from a mode.** There is one
    pipeline. A section renders when it has evidence and is dropped when it does
    not, per Locked 2. A fixed section list chosen by a size score would fight
@@ -95,7 +103,7 @@ For each `platform` in `state.analysisSpec.platforms[]`:
    would keep Section 9 for being on it.
 4. **Produce YAML front-matter header** (see `$HOME/.claude/multi-agent-refs/analysis-template.md`). Include `profile: <state.analysisSpec.profile | global>` and `platform: <platform | none>` so the validator applies the right contract per profile (Locked 31) and recognises the stack-optional render (Locked 34), plus `ui_tests: <state.analysisSpec.options.uiTests | false>`, `a11y_depth: <state.analysisSpec.options.a11yDepth | basic>` and `redesign: <state.analysisSpec.options.redesign | false>` so the pre-dispatch validator can enforce the opt-in coverage (15.6 present when ui_tests, 16.2 walkthrough present when a11y_depth is full, 4.5 / 4.6 / 9.5 present when redesign). `status` is written only by `/multi-agent:analysis-resolve`; a rendered document is a draft.
 5. **Read conventions for this platform's repo.** For each cell Pass B fills in Section 13 and in any per-platform projection (Sections 5, 6, 7, 8, 10, 11, 13, 14, 15, 16, 17), read `state.analysisSpec.evidence.conventions[<repo>].<field>` and emit the value with a footnote (Locked 24). If `conventionOverrides` has an entry for that field, use the override and footnote with `^[user-override: <reason>]` instead of evidence path.
-6. **Concatenate non-null sections in canonical order.** Each rendered section keeps its canonical template number, so omitted sections DO leave gaps - `1, 2, 4, 9, 13, 14, 21` is a correct rendered document. Locked 30 cites sections by number across the whole document; re-flowing them would break every one of those references.
+6. **Concatenate non-null sections in canonical order.** Each rendered section keeps its canonical template number, so omitted sections DO leave gaps - `1, 2, 4, 9, 13, 14, 21` is a correct rendered document. Locked 30 cites sections by number across the whole document; renumbering them would break every one of those references.
 7. **Schema validation** on the per-platform spec object:
    ```bash
    python3 -c "import json,jsonschema; jsonschema.validate(json.load(open('state/<feature>-<platform>.json')), json.load(open('$HOME/.claude/schemas/analysis-spec.schema.json')))"

package/pipeline/multi-agent-refs/analysis-template-corporate.md

@@ -20,14 +20,14 @@ This is a sibling of `analysis-template.md` (the global profile), not a replacem
 | Altitude | What to build and how | What is required and why; the how follows in Parts B and C |
 | Current state | Legacy findings are blockquotes inside forward-looking sections (Locked 4) | Section 2.1 is a first-class current-state analysis, and 2.3 is the diff between 2.1 and 2.2 |
 | Empty section | Dropped entirely (Locked 2) | Backbone sections always render, with `N/A` or `EKLENECEK` (Locked 32) |
-| Version history | Section 22 Changelog at the bottom | `DOKÜMAN TARİHÇESİ` table at the top |
+| Version history | Section 23 Changelog at the bottom | `DOKÜMAN TARİHÇESİ` table at the top |
 | Use cases | Gherkin scenarios in Section 4 | UC tables with Aktör / Ön Koşul / Ana Akış / Alternatif Akış |
 
 Everything else is shared: citation discipline (Locked 3), forward-looking spec for Part B and C (Locked 4), the Figma 3-tier chain (Locked 12), Pass B footnotes (Locked 24), and References at the bottom (Locked 21).
 
 ## Section map
 
-Numbering is fixed for Parts A and B and does not re-flow, because the corporate backbone never drops (Locked 32). Section 5 sub-numbering shifts with the use-case count, exactly as the source documents do.
+Numbering is fixed for Parts A and B, because the corporate backbone never drops (Locked 32). Section 5 sub-numbering shifts with the use-case count, exactly as the source documents do.
 
 | Layer | Sections | Carries |
 |---|---|---|
@@ -127,6 +127,16 @@ rather than a footnote.>
 |---|---|---|---|
 | 1 | <capability> | Var / Yok / Kısmi | <detail> |
 
+#### 2.1.1 Mevcut Davranış / Current Behaviour
+
+<Only when the front-matter carries `redesign: true` (Locked 36, `analysis/redesign.md`);
+omitted otherwise. One `CB-<slug>-NN` row per v1 behaviour a reader could only find by
+reading v1, each with the evidence that proves it.>
+
+| Id | Davranış | Kanıt | Kesinlik |
+|---|---|---|---|
+| CB-<slug>-01 | <behaviour> | <path:line> | confirmed / uncertain |
+
 ### 2.2 Hedeflenen Durum Analizi
 
 <What the product will do once this work ships. Sourced from the design and the
@@ -150,6 +160,16 @@ reason 2.1 and 2.2 are separate; if it is empty, one of them was not done.>
 |---|---|---|---|
 | <area> | <from 2.1> | <from 2.2> | <what has to change> |
 
+#### 2.3.1 Fark Listesi / Difference List
+
+<Only under `redesign: true`. Every `CB-` row from 2.1.1 appears here once with a status:
+Moved / Taşındı, Partial / Kısmi, Missing / Yok, New / Yeni, Out of scope / Kapsam dışı.
+Partial and Missing rows name the `AS-NN` that decides them.>
+
+| Id | Durum | Nerede | AS-NN |
+|---|---|---|---|
+| CB-<slug>-01 | Moved / Taşındı | <section> | - |
+
 ### 2.4 Kısıtlar, Varsayımlar, Bağımlılıklar
 
 | Tür | Madde | Kaynak |
@@ -230,6 +250,7 @@ Sub-numbering shifts with the use-case count. For `N` use cases:
 | **Kullanım Sıklığı** | <how often> |
 | **Ana Akış** | 1. <step> 2. <step> 3. <step> |
 | **Alternatif Akış** | 2a. <alternative to step 2> 4a. <alternative to step 4> |
+| **İstisna Akışı** | E1. <what happens when step N fails: refusal, error, timeout> |
 | **İş Kuralları / Referans** | IG-01, IG-03 |
 
 ### Ekranlar
@@ -245,12 +266,14 @@ Rules the renderer enforces:
 
 - **Ana Akış is numbered and single-directional.** A nested option takes a second-level number under its step.
 - **Alternatif Akış always binds to a main-flow step**: `2a.`, `2b.`, `4a.`. A free-floating alternative sentence is rejected, because a reader cannot tell which step it replaces.
+- **İstisna Akışı is never left out.** It is the failure path: what the user sees when the system refuses, errors or times out, and what state the flow is left in. A use case with genuinely no failure path writes `Yok: <reason>`. `validate-analysis-doc.mjs` (`exception-flow`) warns on a draft with no row or an empty one and fails a `status: final` document with no row. Edge-case candidates the synthesis proposes are written here only after the analyst accepts them.
+- **Every screen belongs to a use case.** A design frame is listed in the `Ekranlar` block of the use case it serves; a frame linked anywhere else (outside Section 21) is a warning (`design-frame-unmapped`), because a screen no flow reaches is either missing a use case or out of scope.
 - **Concrete limits appear only when a source states them.** A threshold nobody wrote down is invented (Locked 3), and an invented threshold in a requirements document reaches production as a bug.
 - **FG references inside main-flow steps are optional but must be consistent.** Either every use case cites them or none does; half a document doing it reads as an omission.
 
 ### 5.(N+1) Kullanım Senaryosu Diyagramları
 
-One mermaid diagram per use case, under a `### UC-00<i>: <name>` heading. The diagram shows the flow, including the alternative branches named in the table.
+One mermaid diagram per use case, under a `### UC-00<i>: <name>` heading. The diagram shows the flow, including the alternative and exception branches named in the table. A use case that calls more than one service also gets a `sequenceDiagram`, so the call order and the failure point of each call are visible.
 
 ### 5.(N+2) Kullanım Senaryosu - İş Gereksinimi Eşleştirme
 
@@ -300,6 +323,14 @@ renders; when the whole contract is unknown, write one line instead of six `EKLE
 cells: `Bu servisin sozlesmesi tanimli degil (AS-NN).` Render the table only once
 `Name` and `Path` are both known.
 
+#### 5.(N+4).1 Endpoint Eşlemesi / Endpoint Mapping
+
+<Only under `redesign: true`. One row per v1 endpoint and the v2 endpoint that replaces it.>
+
+| v1 | v2 | Değişiklik |
+|---|---|---|
+| <METHOD /v1/path> | <METHOD /v2/path> | unchanged / renamed / split / removed |
+
 ### 5.(N+5) Servis - Fonksiyonel Gereksinim Eşleştirmesi
 
 ```markdown
@@ -311,9 +342,9 @@ cells: `Bu servisin sozlesmesi tanimli degil (AS-NN).` Render the table only onc
 ### 5.(N+6) Gereksinim İzlenebilirlik Matrisi
 
 ```markdown
-| İş Gereksinimi | Kullanım Senaryosu | Fonksiyonel Gereksinim | Servis |
-|---|---|---|---|
-| IG-01 | UC-001 | FG-01, FG-02 | <operation name> |
+| İş Gereksinimi | Kullanım Senaryosu | Fonksiyonel Gereksinim | Servis | Ekran | Test |
+|---|---|---|---|---|---|
+| IG-01 | UC-001 | FG-01, FG-02 | <operation name> | <frame name> | <test row id> |
 ```
 
 **This matrix is the most expensive thing in the document to get wrong**, because every downstream reader trusts it instead of re-deriving the chain.
@@ -325,6 +356,8 @@ The rest is the renderer's obligation, checked by reading rather than by a scrip
 - every `IG` appears in at least one `UC`, and every `UC` cites at least one `IG`
 - every `FG` names a source `UC` and a source `IG` that exist
 - a struck-through requirement is struck through in all four places it appears
+- `Ekran` names the frame from the use case's `Ekranlar` block; `Test` names the Section 19 row that proves the requirement, or `-` when Part C is not rendered
+- tickets are not a matrix column: `/multi-agent:analysis-jira` writes them to a `## Tickets` table at the end of the document, keyed by the same ids
 
 ## 6. Donanım ve Altyapı / Hardware and Infrastructure
 
@@ -433,11 +466,13 @@ Never omitted.
 ## 20. Riskler ve Açık Sorular    <!-- TR -->
 ## 20. Risks and Open Questions   <!-- EN -->
 
-| Id | Konu | Neden açık | Kime sorulacak | Etkilediği bölüm |
-|---|---|---|---|---|
-| AS-01 | <question> | <what evidence is missing> | <role or team> | 2.3 |
+| Id | Konu | Neden açık | Kime sorulacak | Etkilediği bölüm | Kategori | Karar |
+|---|---|---|---|---|---|---|
+| AS-01 | <question> | <what evidence is missing> | <role or team> | 2.3, 5.2 | <business / design / service / content / legal> | <empty until answered> |
 ```
 
+One question, one row: a question that affects several sections is written once and lists every section it affects, rather than repeated per section. `Karar` records the answer once it arrives, and `/multi-agent:analysis-resolve` folds it back into those sections.
+
 The source corporate documents keep open questions out of the page and raise them in conversation instead. This profile keeps them in the document deliberately: an `EKLENECEK` with no matching `AS-NN` row here is an unanswered question nobody owns. Every `EKLENECEK` and every unverified assumption in 2.4 emits a row (Locked 32).
 
 ## 21. Referanslar / References

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

@@ -67,7 +67,7 @@ Phase 1 compares `evidence_digest` against an existing document to decide whethe
 
 ## Layer headings (A / B / C)
 
-The 23 sections render under three named layers. This is an **additive heading level**, not a renumbering: section numbers are referenced in 172 places across the repo including two deterministic validators, so they do not move. Layer headings are `#` (h1); sections stay `##`. `validate-analysis-doc.mjs` collects `^#{1,3}` and `md2confluence-v3.py` maps `#{1,6}` to `<h{level}>`, so the extra level is safe in both and gives the Confluence page a two-level table of contents.
+The 23 sections render under three named layers, an **additive heading level** that never renumbers: layer headings are `#` (h1), sections stay `##`, and both the validator and `md2confluence-v3.py` read the extra level, which gives the Confluence page a two-level table of contents.
 
 | Layer | Sections | What is lost if it is missing |
 |---|---|---|
@@ -76,7 +76,9 @@ The 23 sections render under three named layers. This is an **additive heading l
 | `# Bölüm C - Geliştirme Analizi` / `# Part C - Development Analysis` | 13, 14, 15 | **how** to build it: class name, file path, reuse, test row |
 | (footer, no heading) | 21, 22, 23 | |
 
-**Boundary rule.** Which layer a row belongs to is settled by one question: remove it, what becomes unclear? A row that is unclear in two layers at once is two rows. `A carries no technology name; C carries no business rationale.`
+**Boundary rule.** Which layer a row belongs to is settled by one question: remove it, what becomes unclear? A row that is unclear in two layers at once is two rows. `A carries no technology name; C carries no business rationale.` Evidence that must stay in A goes in `<details>`.
+
+**Document head**, above Section 1: the missing-inputs panel (if any), then one line of counts, e.g. `At a glance: 6 rules, 3 screens, 4 services, 2 open questions`.
 
 A layer whose sections all drop for lack of evidence drops its heading too (Locked 2). Numbering still flows 1..N over the rendered set.
 
@@ -84,7 +86,7 @@ A layer whose sections all drop for lack of evidence drops its heading too (Lock
 
 ## Omission rules
 
-Locked 2 - no `TBD` / `Not applicable` placeholder. Sections with zero evidence are omitted entirely. Numbering remains sequential `1..N` over the rendered set; numbers re-flow when sections drop. The dispatch report logs the omission list.
+Locked 2 - no `TBD` / `Not applicable` placeholder. Sections with zero evidence are omitted entirely. Each rendered section keeps its canonical number, so an omitted section leaves a gap (`1, 2, 4, 9, ...` is correct); section numbers are cited across the document and must not move. The dispatch report logs the omission list.
 
 | Section | Omission condition |
 |---|---|
@@ -472,15 +474,17 @@ Authorization: Bearer <token>
 
 \`\`\`json
 {
-  "field1": "value",
-  "field2": 0
+  "field1": "<string>",
+  "field2": "<integer>"
 }
 \`\`\`
 
-| Alan / Field | Tip / Type | Zorunlu / Required | Validation |
-|---|---|---|---|
-| field1 | string | yes | <rule> |
-| field2 | integer | no | <rule> |
+| Alan / Field | Tip / Type | Zorunlu / Required | Validation | Kaynak / Source |
+|---|---|---|---|---|
+| field1 | string | yes | <rule> | <spec path or page that defines it> |
+| field2 | integer | no | <rule> | <spec path or page that defines it> |
+
+Types, never sample values; `Kaynak / Source` names where each field is defined.
 
 ### 9.3 Response varyantları / Response variants
 
@@ -933,13 +937,16 @@ Never omitted.
 ## 20. Riskler ve Açık Sorular   <!-- TR -->
 ## 20. Risks and Open Questions  <!-- EN -->
 
-| Risk / Soru / Risk / Question | Sahibi / Owner | Durum / Status |
-|---|---|---|
-| <risk or question> | <name or role> | Açık / Open |
-| <convention fallback applied> | Pass B (auto) | Açık / Open |
-| <existing X candidate found; reuse or document why a new one is needed> | <name> | Açık / Open |
+| ID | Risk / Soru / Risk / Question | Sahibi / Owner | Durum / Status |
+|---|---|---|---|
+| AS-01 | <risk or question> | <name or role> | Açık / Open |
+| AS-02 | <convention fallback applied> | Pass B (auto) | Açık / Open |
+| AS-03 | <existing X candidate found; reuse or document why a new one is needed> | <name> | Açık / Open |
 ```
 
+Every row carries an `AS-NN` id: a gap marker elsewhere in the document names the row
+it is answered by, and the closure gate pairs them by that id.
+
 Auto-populated rows (Locked 11, 23): repo-evidence direct-match candidates that conflict with planned new-write; convention fallbacks where Phase 1c confidence was none.
 
 ## 21. Referanslar / References

package/pipeline/multi-agent-refs/cross-cli-contract.md

@@ -288,6 +288,10 @@ argument-hint: "<input hint>"
 
 **`not-for`** is optional and lists sibling commands this one must not be chosen for, as bare names (`not-for: jira, review-jira`). It is written for the model reading the routing surface, so it belongs beside the description rather than in prose further down. `lint-skills.mjs` also consumes it: a trigger-vocabulary collision either side has named drops off the warning list and is reported as settled instead, and a name that resolves to no sibling on the same surface is an error - a typo would otherwise leave the pair unanswered while the author believes it is handled. Both trees spell the value the same way and the lint reads it from either place; the `multi-agent-` prefix on the Copilot side is stripped before matching.
 
+**Command-only keys stay top-level.** `parameters`, `gui`, `destructive`, `confirm` and `description-tr` sit at the top level of a command's frontmatter, not under `metadata:`. Claude Code ignores a key it does not recognize, command files are never packaged for claude.ai or the Skills API (where unknown keys are rejected), and these keys are read by the command contract, the GUI catalog and the installer's localizer, which all parse the top level. A shared skill keeps every key no host reads under `metadata:`, because shared skills are the files that do get packaged.
+
+**`disable-model-invocation: true`** marks every command whose `destructive` is true: such a command runs only when the user types it. It is set on the Claude command only; the Copilot mirror does not carry it. Commands that only confirm (`confirm: required` without `destructive`), such as `sync`, stay model-invocable because they are routinely run on request and confirm inside their own flow. `test/command-contract.test.mjs` holds the rule.
+
 **Invariant**: the English `description` must have the same meaning on both sides, and a `description-tr` line (when present) must be a faithful translation of it. Semantic drift is not allowed. `description-en` sidecars are an installed-tree artifact and must never appear in repo or Copilot files.
 
 ---

package/pipeline/multi-agent-refs/features/analysis-jira.md

@@ -7,6 +7,10 @@
 - [Identity is a label, not a title](#identity-is-a-label-not-a-title)
 - [The write is ledgered](#the-write-is-ledgered)
 - [An existing node is skipped, never updated](#an-existing-node-is-skipped-never-updated)
+- [The story body is document text, escaped](#the-story-body-is-document-text-escaped)
+- [An existing epic, linked the way the site links](#an-existing-epic-linked-the-way-the-site-links)
+- [Channel clones are opt-in](#channel-clones-are-opt-in)
+- [The document lists its tickets](#the-document-lists-its-tickets)
 - [Every site-specific name is a VALUE, never a schema key](#every-site-specific-name-is-a-value-never-a-schema-key)
 - [Auth](#auth)
 <!-- /toc -->
@@ -17,16 +21,18 @@ Two files do it, and the split is the design:
 | File | Does | Network |
 |---|---|---|
 | `scripts/analysis-story-tree.mjs` | decides WHAT to create, checks coverage, assigns identity | none |
+| `scripts/analysis-story-body.mjs` | builds each story's description from the document | none |
 | `lib/analysis-jira-write.sh` | creates it | yes |
+| `lib/jira-epic-link.sh` | decides which field links a story to its epic | none (the writer passes the site's answers in) |
+| `scripts/analysis-tickets-writeback.mjs` | writes the created keys back into the document | none |
 
 Planning is deterministic and testable offline; creating issues is neither. Kept
 apart, the file that can write to a tracker is small enough to read in one
 sitting.
 
-`jira-publish.sh` could not be extended to do this: it writes a comment or a
-description on an issue that already exists. The only creation path in the repo
-was a curl hand-written inside a markdown instruction, which is what this
-replaces.
+`jira-publish.sh` writes a comment or a description on an issue that already
+exists; creating issues is a different contract, so it is a different file, and
+the only one that creates issues.
 
 ## The marker gate runs first, before any network call
 
@@ -69,10 +75,9 @@ verdict is `unverifiable`, never `ok`. It appears:
 - as a separate fourth approval option, not folded into `Approve`
 - in the writer's own output, and beside every key in the ledger
 
-Such a document still plans work, from its user-story sub-sections. That is not
-a convenience: without it the no-atom document produced no stories, exited
-"nothing to plan", and the `unverifiable` branch was unreachable - a case the
-code claimed to handle and never could.
+Such a document still plans work, from its user-story sub-sections, so a
+document without atoms gets stories and an honest `unverifiable` verdict rather
+than "nothing to plan".
 
 ## Identity is a label, not a title
 
@@ -99,8 +104,55 @@ answerable from the tree's own trail.
 ## An existing node is skipped, never updated
 
 Jira has no backup path for fields other than description. Rewriting a body an
-engineer has since edited would repeat, at tree scale, the defect that made
-`jira-publish.sh` take backups in the first place.
+engineer has since edited would lose that edit with no way back. A node found by
+its label is recorded in the ledger as `exists`, beside its key.
+
+## The story body is document text, escaped
+
+`buildStoryBody()` assembles the description from the document alone:
+
+| Part | Global profile | Corporate profile |
+|---|---|---|
+| User story | the "As a ..." line of the story's own section; the user-story section only when it holds exactly one | the use case's actor and short description |
+| Acceptance criteria | the G/W/T column of each rule, else the rule | each functional requirement, plus the use case's alternative and exception flows |
+| Current vs target | redesign rows that point at the story's section | the same, from the corporate redesign sub-sections |
+| Links | the analysis page, Figma URLs in the story's sections, Swagger/OpenAPI URLs in References | same |
+
+At most 8 criteria. What is missing stays missing and becomes a body warning
+(no user story, fewer than 2 criteria, no negative criterion); nothing is filled
+in. Every piece of document text passes `escapeJiraWiki()` before it is placed
+in wiki markup, and links pass `wikiLink()`, which accepts http and https only,
+so document text cannot become a macro, a mention, an image or a link.
+
+## An existing epic, linked the way the site links
+
+`--epic KEY` links every story to an epic that already exists; the tree never
+creates one. Cloud links through the `parent` field. Server and Data Center use
+an Epic Link custom field whose id differs per site, so `issueTree.epicLinkMode:
+auto` reads `serverInfo` and discovers the field by its schema type
+(`com.pyxis.greenhopper.jira:gh-epic-link`). No field found means the stories
+are created unlinked, with a warning; a field id is never guessed. `parent`,
+`epicLinkField` (with `epicLinkFieldId`) and `none` force one path. A story that
+already exists is not relinked.
+
+## Channel clones are opt-in
+
+With `issueTree.cloneByChannel: true` and `channelComponents` filled, each story
+gets one clone per channel: its own label (the story's identity plus
+`ch:<channel>`), the channel's component, and an issue link of
+`cloneLinkType` (default `Relates`) back to the story. Clone labels are part of
+the label search, and a link is checked before it is sent, so a re-run doubles
+neither.
+
+## The document lists its tickets
+
+After the write, `analysis-tickets-writeback.mjs` puts a `## Tickets` table at
+the end of the local document, between `<!-- tickets:start -->` and
+`<!-- tickets:end -->`: story, key, source ids and channel, keys taken from the
+ledger. It carries no section number, so the canonical numbering is untouched,
+and a re-run replaces the block. An unverifiable tree is titled
+`## Tickets (coverage unverified)`. Publishing the updated document to its
+Confluence page is a separate approval.
 
 ## Every site-specific name is a VALUE, never a schema key
 
@@ -113,6 +165,8 @@ are values the site fills in:
 - `subtaskRoles` ships **empty**. An empty list is an instruction to look at how
   this board actually splits work; a ready-made list would be the guess most
   worth avoiding
+- `epicLinkFieldId`, when set, is the site's own field id; otherwise it is
+  discovered
 - `subtaskIssueType: null` means discover it - `createmeta` returns whichever
   type carries `subtask: true`, under whatever name the site gave it. Same rule
   as `features/jira-context.md`: the type travels as it comes from Jira and is
@@ -126,14 +180,10 @@ setting is visible before the writes rather than in Jira afterwards.
 `lib/_jira-auth.sh` holds one host-and-token resolution and one curl idiom: the
 token reaches curl through a `-K` config on process substitution and never
 touches argv, a log, or `ps`. That idiom is the part most easily retyped badly,
-which is why the third writer got a shared copy instead of a third hand-written
-one.
-
-**Only this writer consumes it today.** `jira-publish.sh` and `issue-fetcher.sh`
-still carry their own resolution, and retrofitting them is real work rather than
-a rename - `issue-fetcher.sh` resolves per-account token keys that this helper
-does not model yet. So the file is the shared copy going forward, not a
-consolidation that has already happened, and saying otherwise would describe a
-cleanup nobody did. The leak property itself is asserted on all three callers
+so it lives in one file.
+
+**Only this writer consumes it.** `jira-publish.sh` and `issue-fetcher.sh`
+carry their own resolution; `issue-fetcher.sh` resolves per-account token keys
+that this helper does not model. The file is the shared copy for new callers. The leak property itself is asserted on all three callers
 independently in `smoke-analysis-jira.sh`, which is the part that must hold
 whether or not they ever share code.