@mmerterden/multi-agent-pipeline 16.5.0 → 16.7.0

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

@@ -6,7 +6,11 @@
 
 1. **Language resolution**: read `prefs.global.outputLanguage` (`tr` or `en`, default `tr`). Use the `Output language matrix` table in `$HOME/.claude/multi-agent-refs/analysis-template.md` to swap headings and system strings.
 
-2. **Per-platform 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.
+1b. **Template selection** (Locked 32): 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 33).
+
+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.
+
+   **When `platforms[]` is empty** (Locked 35), render one platform-agnostic file instead of one per platform: 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.
 
 3. **Humanizer pass (MANDATORY: 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):
    ```
@@ -19,7 +23,15 @@
 
    **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.**
 
-4. **Write scratch drafts**: create `/tmp/analysis-<feature-slug>-<UTC-iso8601>/` and write `<feature>-<platform>.md` for each selected platform. Update `state.analysisSpec.outputs.draftDir` with the path.
+3b. **Build Section 21 References** (Locked 34): emit the table with
+
+   ```bash
+   node "$HOME/.claude/scripts/build-references.mjs" <state.json> --lang "$OUTPUT_LANGUAGE"
+   ```
+
+   and paste its output under the References heading. The model does not hand-write this table; it is a projection of `state.analysisSpec.evidence.*`, which is what keeps a source the run actually read from going unlisted and a remembered-but-unread source from appearing.
+
+4. **Write scratch drafts**: create `/tmp/analysis-<feature-slug>-<UTC-iso8601>/` and write `<feature>-<platform>.md` for each selected platform, or a single `<feature>.md` when `platforms[]` is empty. Update `state.analysisSpec.outputs.draftDir` with the path.
 
 5. **Surface the draft tree to the user**:
    ```
@@ -39,7 +51,7 @@ header: "Output"
 question: <localized: "Where should the per-platform analyses be written?">
 options:
   - label: "Local file"
-    description: "analysis/<feature>-<platform>.md in each selected repo's working tree"
+    description: <resolved path, shown literally: "<repo>/analysis/<feature>-<platform>.md" per selected repo, or "~/Desktop/multiAgentAnalysis/<feature-name>/<feature>.md" when no repo was selected>
   - label: "Confluence page"
   - label: "Jira issue"
     description: <localized: "As a comment by default; writing the description is a separate, explicit choice">
@@ -74,16 +86,17 @@ Result: `state.analysisSpec.outputs.requested[]`.
 ```bash
 for f in /tmp/analysis-<feature-slug>-<ts>/*.md; do
   node "$HOME/.claude/scripts/validate-analysis-doc.mjs" "$f" || GATE_FAILED=1
+  node "$HOME/.claude/scripts/build-references.mjs" <state.json> --check "$f" || GATE_FAILED=1
 done
 ```
 
-`validate-analysis-doc.mjs` enforces the mechanically-checkable Locked decisions on the emitted markdown itself (front-matter completeness, never-omitted sections per Locked 2, humanizer punctuation per Locked 7, and Full-mode business-rule traceability per Locked 31). Any ERROR blocks dispatch: fix the draft and re-validate. Warnings are advisory (run with `--strict` to treat them as blocking). This turns the "fails the dispatch gate" prose into a real, model-independent check.
+`validate-analysis-doc.mjs` enforces the mechanically-checkable Locked decisions on the emitted markdown itself (front-matter completeness, never-omitted sections per Locked 2, humanizer punctuation per Locked 7, Full-mode business-rule traceability per Locked 31, and in the corporate profile the backbone presence and `EKLENECEK`-to-Section-20 pairing per Locked 33). `build-references.mjs --check` runs the References coverage gate (Locked 34): a source the run consumed but did not list, or a listed row with no evidence behind it, blocks dispatch. Any ERROR blocks dispatch: fix the draft and re-validate. Warnings are advisory (run with `--strict` to treat them as blocking). This turns the "fails the dispatch gate" prose into a real, model-independent check.
 
 Iterate `state.analysisSpec.outputs.requested`. For each target:
 
 | Target | Action |
 |--------|--------|
-| Local | For each per-platform draft, `cp /tmp/analysis-<feature-slug>-<ts>/<feature>-<platform>.md` into `analysis/<feature>-<platform>.md` in the matching repo's working tree. When multiple repos exist for the same platform, the file is duplicated into each and the dispatch report lists every destination. **No commit.** |
+| Local | For each per-platform draft, `cp /tmp/analysis-<feature-slug>-<ts>/<feature>-<platform>.md` into `analysis/<feature>-<platform>.md` in the matching repo's working tree. When multiple repos exist for the same platform, the file is duplicated into each and the dispatch report lists every destination. **When no repo was selected** (Locked 35) there is no working tree to be relative to, so the file lands in `~/Desktop/multiAgentAnalysis/<feature-name>/<feature>.md`. The current working directory is never written to: for a repo-less run it is arbitrary, and creating a folder in whatever directory the command happened to be invoked from is the kind of surprise that costs a tool its trust. The user can override the path through the picker's Other input. **No commit.** |
 | Confluence | Re-humanize each per-platform draft with `formal-stakeholder` tone. One Confluence page per platform under the chosen parent, titled `<Feature> - <Platform>`. Cross-link siblings inside each page via `<ac:link><ri:page ri:content-title="<Feature> - <OtherPlatform>"/></ac:link>`. Markdown -> storage XML via `$HOME/.claude/multi-agent-refs/channels/confluence.md`. Re-emit on existing pages uses PUT with version bump. |
 | Jira | Re-humanize the combined body with `informal-technical` tone. Concatenate per-platform drafts under `h2. Platform: iOS`, `h2. Platform: Android`, `h2. Platform: Backend`, `h2. Platform: Frontend` separators (in the order platforms were selected), then run the whole body through the markdown → Jira wiki conversion table in `$HOME/.claude/multi-agent-refs/channels/jira.md`  -  both the comment body and the `description` field render wiki markup, so raw `##`/`**`/backticks arrive as literal text. Write the converted body to a file and publish it with `$HOME/.claude/lib/jira-publish.sh`, never with a hand-rolled `curl`: <br><br>`bash "$HOME/.claude/lib/jira-publish.sh" --issue "$KEY" --body-file "$F" --target comment` <br>`bash "$HOME/.claude/lib/jira-publish.sh" --issue "$KEY" --body-file "$F" --target description --mode append` <br><br>The script owns the parts that are easy to get wrong: it runs `jira-wiki-escape.mjs` on the body, resolves host + token without putting either in argv, and on the description path it GETs the current value, writes it to a backup under `~/.claude/logs/multi-agent/jira-backups/` and reports the path, appends below a `----` rule by default, and **refuses with exit 3** when `--mode replace` would discard a non-empty description unless `--confirm-overwrite` is passed. Exit 3 is reported to the user with the backup path, never retried with the flag added automatically  -  only the user's explicit "Description - replace" answer from Phase 3.5 supplies it. `--dry-run` previews the exact final body without writing. |
 
@@ -142,6 +155,8 @@ Per the `analysis-output-confluence-on-request` memory, Confluence post is NEVER
 
 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.
 3. Convert markdown to storage XML using the table in `$HOME/.claude/multi-agent-refs/channels/confluence.md`.
 4. Upload Figma frame screenshots as page attachments via `POST /rest/api/content/{pageId}/child/attachment` (cache the MCP asset locally first because the upstream URLs expire after 7 days).
 5. Reference attachments inside the page body via `<ac:image><ri:attachment ri:filename="frame-<nodeId>.png"/></ac:image>`.

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

@@ -0,0 +1,86 @@
+# Analysis document review (`/multi-agent:review-analysis`)
+
+> Reviews a written analysis the way `/multi-agent:review` reviews a diff. Loaded on demand. Read-only: no branch, no worktree, no commit, and the source document is never edited in place.
+
+`/multi-agent:review` answers "is this code right". This answers "could an implementer build the thing from this document, and does the document keep the promises its own contract makes". The two are different questions with the same failure mode: a reviewer who has opinions instead of rules produces findings nobody can act on. So this flow cites `Locked <n>` the way a code review cites a rule ID.
+
+## Phase 0 - Resolve the document
+
+`$ARGUMENTS` is one of:
+
+| Input | Resolution |
+|---|---|
+| A local path | Read it. |
+| A Confluence page URL or `pageId` | Fetch read-only through `$HOME/.claude/multi-agent-refs/channels/confluence.md`. Record `pageId` and page version - the review is about a specific version, and Confluence pages move under you. |
+| A Jira key | Fetch the issue, then follow its analysis link. If the issue carries the analysis in its description or a comment, review that text and say which it was. |
+| Nothing | Offer the most recent documents from `~/Desktop/multiAgentAnalysis/` and from `analysis/` in each selected repo, newest first, and single-select one. |
+
+Fetch failures are reported and stop the run. Reviewing a document you could not read is the one outcome worse than not reviewing it.
+
+## Phase 1 - Deterministic gates first
+
+Run the machine checks before the model reads anything, and report their output verbatim. A finding a script already proves does not need a model's opinion, and a model that reads the document first tends to argue with the script afterwards.
+
+```bash
+node "$HOME/.claude/scripts/validate-analysis-doc.mjs" "<doc>"
+# when the run's state JSON is available (a fresh analysis, or --state <path>):
+node "$HOME/.claude/scripts/build-references.mjs" "<state>" --check "<doc>"
+```
+
+`validate-analysis-doc.mjs` reads `profile` from the front-matter and applies the matching contract, so the corporate backbone and the global omission rule are each judged by their own rule. Its ERRORs are Blockers in this review, its WARNs are Important unless the document states why the warned-about thing is deliberate.
+
+**No state JSON, no references gate.** Say so in the report rather than passing silently: the coverage claim ("every source the run read is listed") is exactly the claim nobody can verify from the document alone, and marking it unchecked is the honest output.
+
+## Phase 2 - Rubric
+
+Parallel model review, same shape as `/multi-agent:review`: 2 models on Claude Code, 3 on Copilot CLI, then triage. Each reviewer answers the rubric below against the resolved profile and returns findings with `Locked <n>` or a rubric id, a quote from the document, and what a reader cannot do because of it.
+
+**A. Buildability** - could an implementer start from this alone?
+
+- Every screen, state and error path the feature needs is described somewhere, not assumed.
+- Each business requirement or rule is testable: two readers cannot disagree about whether it passed.
+- Nothing important is deferred to a conversation the reader was not in.
+
+**B. Evidence** (Locked 3, 4, 34)
+
+- Every quoted string, endpoint, status code and event name carries a citation.
+- Nothing in a forward-looking section is actually a description of the current code.
+- References carry their precision anchors, and a source that could not be fetched is listed as unreachable rather than dropped.
+
+**C. Spine** (Locked 31 global, Locked 33 corporate)
+
+- Global: every `BR-` id reaches an acceptance criterion and a test row.
+- Corporate: every `IG` is realised by a `UC`, every `FG` names a source that exists, and the traceability matrix agrees with the sections. The matrix half is already machine-checked in Phase 1; the reviewer judges whether the chain is *meaningful*, not merely present.
+
+**D. Altitude** - Part A carries no technology name, Part C carries no business rationale. A row that is unclear in two layers at once is two rows.
+
+**E. Gaps that were admitted** - every `EKLENECEK` and every unverified assumption has an open question naming who can answer it. A gap with an owner is a plan; a gap without one is a defect.
+
+**F. Contradiction** - the document does not say two different things in two places. This is the finding class a human reviewer misses most, because it needs the whole document held at once.
+
+## Phase 3 - Triage and verdict
+
+Fable triages the pooled findings exactly as in `/multi-agent:review`: drop duplicates, drop what the document already answers elsewhere, and keep the rest at one of three severities.
+
+| Severity | Meaning |
+|---|---|
+| Blocker | An implementer would build the wrong thing, or could not start. Deterministic-gate ERRORs land here. |
+| Important | The document is right but a reader will need a conversation to use it. |
+| Suggestion | Clarity and consistency. Never a style preference dressed as a defect. |
+
+The verdict names the profile it judged against, the counts per severity, and what was NOT checked (the references gate without a state file, anything the fetch could not reach). Follow the pipeline rule on claiming: state which findings are mechanically proven and which are judgement.
+
+## Phase 4 - Output
+
+Default is the chat report. Nothing is written anywhere without an explicit choice.
+
+| Target | Behaviour |
+|---|---|
+| Chat only | Default. |
+| Confluence comment | A comment on the reviewed page, never an edit of the page body. The document belongs to its author; a reviewer who rewrites it has removed the choice to disagree. |
+| Jira comment | Comment only, per `channels/issue-comment.md`. The description is never touched. |
+| Local file | `<doc-dir>/<doc-name>-review.md` beside the document, so the review travels with what it reviewed. |
+
+`/multi-agent:analysis-resolve` is the companion that acts on the findings: this command says what is wrong, that one walks the open questions and folds the answers back into the document. Say so in the report when the verdict has open questions, so the reader knows the next command rather than editing by hand.
+
+Non-negotiables: report body follows `prefs.global.outputLanguage`; humanizer punctuation policy (Locked 7) applies to anything posted to a channel; no AI attribution anywhere; no status change, no assignment, no page edit, no commit.

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

@@ -88,7 +88,7 @@ For each `platform` in `state.analysisSpec.platforms[]`:
    - `frontend` → `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. Frontend 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.
 3. **Resolve mode.** If user passed `--lite` → Lite. If user passed `--full` → Full. Otherwise use `state.analysisSpec.liteModeAuto`. Lite mode renders only Sections 1, 2, 4, 9, 13, 14, 21 plus optional 23.
-4. **Produce YAML front-matter header** (see `$HOME/.claude/multi-agent-refs/analysis-template.md`). Include `mode: full | lite`, plus `ui_tests: <state.analysisSpec.options.uiTests | false>` and `a11y_depth: <state.analysisSpec.options.a11yDepth | basic>` 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. **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 32) and recognises the stack-optional render (Locked 35), `mode: full | lite`, plus `ui_tests: <state.analysisSpec.options.uiTests | false>` and `a11y_depth: <state.analysisSpec.options.a11yDepth | basic>` 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).
 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.** Numbering stays sequential `1..N` over the rendered set (omitted sections do not create gaps).
 7. **Schema validation** on the per-platform spec object:

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

@@ -0,0 +1,436 @@
+---
+description: "Corporate profile template for /multi-agent:analysis. Requirements-first BA document: IG / UC / FG spine, three traceability matrices, current-to-target state with impact analysis, then Technical Analysis and Development Analysis. Selected at Phase 0 Step 1b when profile = corporate."
+---
+
+# Analysis Template - Corporate Profile
+
+The corporate profile renders a **requirements document**, not a development brief. Its spine is `IG -> UC -> FG`: a business requirement is realised by a use case, which is satisfied by functional requirements, which are served by services. Three matrices prove the chain closes.
+
+This is a sibling of `analysis-template.md` (the global profile), not a replacement. Both read the same `state.analysisSpec.evidence.*`; only the projection differs. Phase 0 Step 1b picks one (Locked 32).
+
+> **Language**: This file is read as a system prompt, so its prose stays English. Section headings carry TR / EN scaffolds; the renderer picks the column matching `prefs.global.outputLanguage`.
+
+> **Punctuation**: Locked 7 applies unchanged. No em-dash, en-dash, ellipsis, curly quotes, or section sign in emitted text.
+
+## What the corporate profile changes
+
+| Concern | Global profile | Corporate profile |
+|---|---|---|
+| Requirement spine | `BR-<slug>-NN` business rules with Gherkin acceptance criteria | `IG-NN` -> `UC-00N` -> `FG-NN`, plus three cross matrices |
+| 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 33) |
+| Version history | Section 22 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 33). Section 5 sub-numbering shifts with the use-case count, exactly as the source documents do.
+
+| Layer | Sections | Carries |
+|---|---|---|
+| header | `DOKÜMAN TARİHÇESİ` | version, date, author, change summary |
+| `# Bölüm A - Analiz` | 1 - 9 | the requirement document |
+| `# Bölüm B - Teknik Analiz` | 10 - 16 | what is technically true: design binding, tokens, keys, events, contracts |
+| `# Bölüm C - Geliştirme Analizi` | 17 - 19 | how to build it: architecture, files, tests |
+| footer | 20 - 21 | open questions, references |
+
+**Boundary rule** (inherited from the global template): remove a row, and ask what becomes unclear. Part A carries no technology name. Part C carries no business rationale. A row unclear in two layers at once is two rows.
+
+**Part C drops when no repo is selected** (Locked 35). Parts A and B always render.
+
+---
+
+# Header - DOKÜMAN TARİHÇESİ
+
+Never omitted. Renders above Section 1, before the Part A heading.
+
+```markdown
+Tarih: <DD.MM.YYYY>
+
+Versiyon: <n.n>
+
+# DOKÜMAN TARİHÇESİ   <!-- TR -->
+# DOCUMENT HISTORY    <!-- EN -->
+
+| Versiyon | Tarih | Hazırlayan | Açıklama |
+|---|---|---|---|
+| 1.0 | <DD.MM.YYYY> | <identity.name> | İlk sürüm |
+```
+
+On a revision, add a row rather than editing the last one, and raise the header `Versiyon`. A content correction takes a minor bump; a scope change takes a major one.
+
+**A cancelled requirement is never deleted.** Strike it through and state the decision beside it, in every place it appears: the requirement section, the FG table, and the traceability matrix. Losing the decision history is worse than a longer document.
+
+```markdown
+~~<eski gereksinim metni>~~ (<karar mercii> kararıyla iptal edildi)
+
+<yerine geçen gereksinim metni>
+```
+
+---
+
+# Bölüm A - Analiz / Part A - Analysis
+
+## 1. Amaç ve Kapsam / Purpose and Scope
+
+Never omitted.
+
+```markdown
+## 1. Amaç ve Kapsam   <!-- TR -->
+## 1. Purpose and Scope <!-- EN -->
+
+### 1.1 İşin Amacı
+
+<2-3 paragraphs: what problem this solves and why it is being done now. Business
+language only. No class name, no endpoint, no framework.>
+
+### 1.2 Çözüm Kapsamı
+
+<What is in scope, stated as a list of capabilities. Then what is explicitly out
+of scope, each naming what is excluded rather than a vague "out of scope".>
+
+| Kısaltma | Açıklama |
+|---|---|
+| <ABBR> | <expansion> |
+```
+
+The abbreviation table renders only when the document uses a term a new reader would not know. Terms are defined once here rather than repeated inline.
+
+## 2. İş Analizi / Business Analysis
+
+Never omitted. This section is what separates a requirements document from a feature brief: it states where the product is now, where it is going, and what the difference costs.
+
+```markdown
+## 2. İş Analizi        <!-- TR -->
+## 2. Business Analysis <!-- EN -->
+
+### 2.1 Mevcut Durum Analizi
+
+<What exists today, per channel. Sourced from the running product and from repo
+evidence, cited file:line. This is the ONE place where legacy is the subject
+rather than a footnote.>
+
+#### Mevcut Web / Mobil Web Fonksiyonları
+
+<numbered list of what the current surface does>
+
+#### Mevcut App Fonksiyonları
+
+<numbered list, or "Desktop ile aynı" plus the differences only>
+
+#### Sekme/İşlev Bazlı Matris
+
+| # | İşlev | Mevcut Destek | Açıklama |
+|---|---|---|---|
+| 1 | <capability> | Var / Yok / Kısmi | <detail> |
+
+### 2.2 Hedeflenen Durum Analizi
+
+<What the product will do once this work ships. Sourced from the design and the
+scope document, cited by Figma node id (Locked 12) or Confluence page and
+heading (Locked 3).>
+
+#### Desktop
+#### Mobile Web
+#### App
+
+<Per channel. When a channel is identical to another, say so in one line and
+list only the differences. Repeating an identical flow three times hides the
+one line that actually differs.>
+
+### 2.3 Değişiklik Etki Analizi
+
+<The diff between 2.1 and 2.2, and what it touches. This section is the whole
+reason 2.1 and 2.2 are separate; if it is empty, one of them was not done.>
+
+| Etkilenen Alan | Mevcut Davranış | Hedeflenen Davranış | Etki |
+|---|---|---|---|
+| <area> | <from 2.1> | <from 2.2> | <what has to change> |
+
+### 2.4 Kısıtlar, Varsayımlar, Bağımlılıklar
+
+| Tür | Madde | Kaynak |
+|---|---|---|
+| Kısıt | <constraint> | <citation> |
+| Varsayım | <assumption> | <citation or "doğrulanmadı"> |
+| Bağımlılık | <dependency> | <citation> |
+
+<An unverified assumption also emits a Section 20 row. An assumption nobody
+checked is a risk wearing a different hat.>
+
+### 2.5 Kullanıcılar ve Rolleri
+
+| Rol | Tanım | Bu akıştaki yetkisi |
+|---|---|---|
+| <role> | <who they are> | <what they may do here> |
+```
+
+## 3. İş Gereksinimleri / Business Requirements
+
+Never omitted. The `IG` half of the spine.
+
+```markdown
+## 3. İş Gereksinimleri       <!-- TR -->
+## 3. Business Requirements   <!-- EN -->
+
+| No | İş Gereksinimi | İlgili UC |
+|---|---|---|
+| IG-01 | <what the business requires, one sentence, no solution wording> | UC-001, UC-002 |
+```
+
+Rules the renderer enforces:
+
+- An `IG` states a requirement, not a screen. "Üye şifresini sıfırlayabilmelidir" is an IG; "Şifre sıfırlama ekranında Devam butonu bulunur" is an FG.
+- Every `IG` carries at least one `UC` in `İlgili UC`. An IG no use case realises is either a missing UC or an IG that does not belong.
+- Ids are stable across revisions. A cancelled IG keeps its number and is struck through; numbers are never reused.
+
+## 4. Yapay Zeka Gereksinimleri / AI Requirements
+
+Renders `N/A` when the feature has no model-backed behaviour (Locked 33). When it does, each row states the decision the model makes, the input it sees, and the fallback when it is unavailable.
+
+```markdown
+## 4. Yapay Zeka Gereksinimleri  <!-- TR -->
+## 4. AI Requirements            <!-- EN -->
+
+| No | Gereksinim | Girdi | Model / Servis | Belirsizlik davranışı |
+|---|---|---|---|---|
+| YZ-01 | <what it decides> | <inputs> | <service> | <fallback when unavailable or low confidence> |
+```
+
+## 5. Kullanım Senaryoları / Use Cases
+
+Never omitted. The `UC` and `FG` halves of the spine, plus the service binding and the three matrices.
+
+Sub-numbering shifts with the use-case count. For `N` use cases:
+
+```
+5.1 .. 5.N      UC-001 .. UC-00N   (each with an Ekranlar sub-block)
+5.(N+1)         Kullanım Senaryosu Diyagramları
+5.(N+2)         Kullanım Senaryosu - İş Gereksinimi Eşleştirme
+5.(N+3)         Fonksiyonel Gereksinimler
+5.(N+4)         Servis Detayları
+5.(N+5)         Servis - Fonksiyonel Gereksinim Eşleştirmesi
+5.(N+6)         Gereksinim İzlenebilirlik Matrisi
+```
+
+### Use-case table (5.1 .. 5.N)
+
+```markdown
+## 5.<i> UC-00<i>: <Senaryo Adı>
+
+| No | UC-00<i> |
+|---|---|
+| **Kullanım Senaryosu Adı** | <name> |
+| **Aktör** | <role from 2.5> |
+| **Kısa Açıklama** | <one or two sentences> |
+| **Ön Koşul** | <what must be true before the flow starts> |
+| **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> |
+| **İş Kuralları / Referans** | IG-01, IG-03 |
+
+### Ekranlar
+
+| Kanal | Tasarım |
+|---|---|
+| Desktop | [Tasarım Linki](<figma url with node-id>) |
+| Mobile Web | [Tasarım Linki](<figma url with node-id>) |
+| App | [Tasarım Linki](<figma url with node-id>) |
+```
+
+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.
+- **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.
+
+### 5.(N+2) Kullanım Senaryosu - İş Gereksinimi Eşleştirme
+
+```markdown
+| Kullanım Senaryosu | İlgili İş Gereksinimleri |
+|---|---|
+| UC-001: <name> | IG-01, IG-02 |
+```
+
+### 5.(N+3) Fonksiyonel Gereksinimler
+
+```markdown
+| No | Fonksiyonel Gereksinim | Kaynak UC | Kaynak IG |
+|---|---|---|---|
+| FG-01 | Sistem, <what the system does>. | UC-001 | IG-01 |
+```
+
+Every `FG` sentence starts with `Sistem,` in Turkish output and `The system shall` in English output. This is not a style preference: it forces the requirement to name a system behaviour rather than a user wish, which is what makes it testable.
+
+Every `FG` carries both a source `UC` and a source `IG`. An FG with no source IG is either an unrecorded business requirement or an invented feature; both are findings, not rows.
+
+### 5.(N+4) Servis Detayları
+
+One table per service. Contracts come from the live specification, never from prose (Locked 17: every status code the endpoint returns is listed, with an example body).
+
+```markdown
+| **Name** | <operation name> |
+|---|---|
+| **Path** | [<path>](<spec url>) |
+| **Method** | GET / POST / PUT / DELETE |
+| **Description** | <what it does> |
+| **Success and error codes** | **200** <meaning> **401** <meaning> **403** <meaning> |
+| **Request** | <example body, fenced> |
+| **Response** | <example body, fenced> |
+```
+
+A session-bound service states its token requirement in the `Request` cell. A service that does not exist yet is named with an explicit note rather than a guessed path.
+
+### 5.(N+5) Servis - Fonksiyonel Gereksinim Eşleştirmesi
+
+```markdown
+| Servis | Karşıladığı FG |
+|---|---|
+| <operation name> | FG-01, FG-04 |
+```
+
+### 5.(N+6) Gereksinim İzlenebilirlik Matrisi
+
+```markdown
+| İş Gereksinimi | Kullanım Senaryosu | Fonksiyonel Gereksinim | Servis |
+|---|---|---|---|
+| IG-01 | UC-001 | FG-01, FG-02 | <operation name> |
+```
+
+**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.
+
+`validate-analysis-doc.mjs` enforces one half of that mechanically, and it blocks dispatch: **every `IG`, `UC` and `FG` id defined anywhere in the document appears in the matrix, and every id in the matrix is defined somewhere else.** A row invented in the matrix and a requirement quietly missing from it both fail.
+
+The rest is the renderer's obligation, checked by reading rather than by a script. State it as an instruction, not as a guarantee:
+
+- 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
+
+## 6. Donanım ve Altyapı / Hardware and Infrastructure
+
+```markdown
+## 6. Donanım ve Altyapı              <!-- TR -->
+## 6. Hardware and Infrastructure     <!-- EN -->
+
+### 6.1 Donanım Gereksinimleri
+### 6.2 Altyapı Gereksinimleri
+```
+
+Both render `N/A` when the feature adds no hardware or infrastructure need, which is the common case for a UI feature.
+
+## 7. Kalite Gereksinimleri / Quality Requirements
+
+Requirement altitude, not implementation. The implementation of these lives in Part B.
+
+```markdown
+## 7. Kalite Gereksinimleri    <!-- TR -->
+## 7. Quality Requirements     <!-- EN -->
+
+### 7.1 Erişilebilirlik Gereksinimleri
+### 7.2 Performans Gereksinimleri
+### 7.3 Güvenlik Gereksinimleri
+### 7.4 Uyumluluk Gereksinimleri
+### 7.5 Bakım Gereksinimleri
+### 7.6 Entegrasyon Gereksinimleri
+```
+
+Each renders a measurable statement or `N/A`. "Sayfa hızlı açılmalıdır" is not a performance requirement; a stated budget is.
+
+## 8. Regülasyonel Gereksinimler / Regulatory Requirements
+
+```markdown
+## 8. Regülasyonel Gereksinimler   <!-- TR -->
+## 8. Regulatory Requirements      <!-- EN -->
+
+### 8.1 Mevzuat Gereksinimleri
+### 8.2 Yasal Gereksinimler
+```
+
+A regulatory claim carries its source. An uncited regulatory sentence is worse than an omission, because it will be believed.
+
+## 9. İçerik Gereksinimleri / Content Requirements
+
+Which user-facing copy this feature needs, who owns it, and where it comes from. The key-level detail belongs to Part B Section 12; this section is the ownership statement.
+
+```markdown
+## 9. İçerik Gereksinimleri   <!-- TR -->
+## 9. Content Requirements    <!-- EN -->
+
+| İçerik | Kanal | Sahibi | Kaynak | Durum |
+|---|---|---|---|---|
+| <copy item> | Desktop / Mobile Web / App | <owner> | CMS / repo / Figma annotation | hazır / EKLENECEK |
+```
+
+---
+
+# Bölüm B - Teknik Analiz / Part B - Technical Analysis
+
+Part B carries what is technically true. It reuses the global template's scaffolds verbatim, renumbered. Read `analysis-template.md` for each one; only the number changes.
+
+| Corporate | Global | Section |
+|---|---|---|
+| 10 | 5 + 6 | Tasarım Referansı ve Bileşen Envanteri / Design Reference and Component Inventory |
+| 11 | 7 + 8 | Tasarım Token'ları ve Asset Envanteri / Design Tokens and Asset Inventory |
+| 12 | 10 | Lokalizasyon Anahtarları / Localization Keys |
+| 13 | 11 | Analytics |
+| 14 | 12 | Deeplink ve Push Notification / Deeplink and Push |
+| 15 | 16 | Erişilebilirlik Uygulaması / Accessibility Implementation |
+| 16 | 17 | Güvenlik ve Gizlilik Uygulaması / Security and Privacy Implementation |
+
+**API contracts are not repeated here.** They live in Section 5.(N+4), bound to the functional requirements they serve. The global template's Section 9 has no corporate counterpart for that reason.
+
+Sections 15 and 16 are the implementation of the requirements stated in 7.1 and 7.3. State the requirement once, in Part A, and the implementation once, here. A sentence that appears in both is a sentence one of the two sections did not need.
+
+Part B follows the global omission table: a section with zero evidence drops. The corporate backbone guarantee (Locked 33) covers Part A and the References section, not Part B.
+
+---
+
+# Bölüm C - Geliştirme Analizi / Part C - Development Analysis
+
+Identical to the global template's Sections 13, 14 and 15, renumbered:
+
+| Corporate | Global | Section |
+|---|---|---|
+| 17 | 13 | Mimari Plan / Architecture Plan |
+| 18 | 14 | Eklenecek Dosyalar / Files to Add |
+| 19 | 15 | Test Planı / Test Plan |
+
+Part C is written against the conventions extracted at Phase 1c, and every projected cell carries its Pass B footnote (Locked 24).
+
+**Part C drops entirely when no repo was selected** (Locked 35). The document then ends after Part B, and Section 20 carries a row stating that the development analysis awaits a repo selection. Parts A and B are complete on their own; a requirements document does not need a target repository to be useful.
+
+**Traceability into Part C.** The `FG` ids are the join. Section 19's unit-test rows cite the `FG` they cover, the same way the global profile's rows cite `BR-` ids (Locked 31). An `FG` with no test row in Full mode fails the dispatch gate.
+
+---
+
+# Footer
+
+## 20. Riskler ve Açık Sorular / Risks and Open Questions
+
+Never omitted.
+
+```markdown
+## 20. Riskler ve Açık Sorular    <!-- TR -->
+## 20. Risks and Open Questions   <!-- EN -->
+
+| # | Konu | Neden açık | Kime sorulacak | Etkilediği bölüm |
+|---|---|---|---|---|
+| 1 | <question> | <what evidence is missing> | <role or team> | 2.3 |
+```
+
+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 row here is an unanswered question nobody owns. Every `EKLENECEK` and every unverified assumption in 2.4 emits a row (Locked 33).
+
+## 21. Referanslar / References
+
+Never omitted. Built deterministically by `~/.claude/scripts/build-references.mjs` from `state.analysisSpec.evidence.*`; the model does not hand-write this table. Shared with the global profile, where it is Section 21 as well.
+
+See `analysis-template.md` Section 21 for the column contract and the coverage gate.