@mmerterden/multi-agent-pipeline 16.4.0 → 16.6.0

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.

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

@@ -42,7 +42,8 @@ Every per-platform file starts with this YAML block:
 ```yaml
 ---
 feature: <FeatureName>
-platform: ios | android | backend | frontend
+platform: ios | android | backend | frontend | none
+profile: global | corporate
 language: tr | en
 mode: full | lite
 ui_tests: true | false
@@ -63,6 +64,8 @@ template_version: v3
 
 `ui_tests` and `a11y_depth` record the Phase 0 Step 5a opt-ins (defaults `false` / `basic`) so the coverage choice is auditable and the pre-dispatch validator can enforce it: `ui_tests: true` requires Section 15.6, `a11y_depth: full` requires the Section 16.2 walkthrough.
 
+`profile` names the template the document was rendered against (Locked 32) and `platform: none` marks the stack-optional render (Locked 35). Both are read by `validate-analysis-doc.mjs`, which applies a different contract per profile: without the key a corporate document would be judged against the global rules and its backbone would read as a pile of Locked 2 violations.
+
 Phase 1 compares `evidence_digest` against an existing document to decide whether to reuse it (Locked 27). Phase 3 reads `platform` to verify file match, `mode` to know which section set to expect, and both `evidence_digest` and `base_commit` to judge freshness: the digest says the evidence changed, `base_commit` says the repo moved. Phase 2 parses the block but gates only on `template_version`.
 
 ## Layer headings (A / B / C)
@@ -912,25 +915,40 @@ Auto-populated rows (Locked 11, 23): repo-evidence direct-match candidates that
 
 ## 21. Referanslar / References
 
-Never omitted. Locked 20 - at the bottom, not at the top.
+Never omitted (Locked 21 - at the bottom, not at the top). Shared verbatim by both profiles.
+
+**Built deterministically, not written by the model.** `~/.claude/scripts/build-references.mjs` reads `state.analysisSpec.evidence.*` and emits this table. A hand-written references table drifts from what the run actually read: it lists what the author remembers consulting, which is a different set from what the evidence gathering fetched. Every row here is a source the run touched.
 
 ```markdown
 ## 21. Referanslar   <!-- TR -->
 ## 21. References    <!-- EN -->
 
-| Tür / Type | Kaynak / Source | URL or Path | Rol / Role | Notlar / Notes |
-|---|---|---|---|---|
-| Standards | <name> | <url or path> | binding | <version> |
-| Wiki | <name> | <url> | binding | <pattern referenced> |
-| Figma | <design name> | <url> | UI design | <n variants, all screenshots embedded> |
-| Confluence | <spec name> | <url> | feature spec | <v<n>> |
-| Confluence | <api contract> | <url> | API contract | <endpoint summary> |
-| Jira | <ticket id> | <url> | ticket | <description> |
-| Firebase | events | <console url> | reference only | auth-gated |
-| OpenAPI | generated | <repo path> | DTO source | <regen plugin name> |
-| Repo | <module> | <repo path> | existing implementation | <reuse summary> |
+| Tür / Type | Kaynak / Source | URL / Yol | Sürüm / Ref | Rol / Role | Erişim / Access | Notlar / Notes |
+|---|---|---|---|---|---|---|
+| Figma | <design name> | <url> | node-id=<nodeId> | UI design | ok (Tier <n>) | <n frames> |
+| Confluence | <spec name> | <url> | pageId=<id> v<n> | feature spec | ok | - |
+| Confluence | <api contract> | <url> | pageId=<id> v<n> | API contract | ok | <endpoint summary> |
+| Jira | <ticket id> | <url> | - | ticket | ok | <summary> |
+| Swagger | <api name> | <url> | <spec version> | API contract | ok | <n endpoints> |
+| Repo | <module> | <repo path> | <commit sha> | existing implementation | ok | <reuse summary> |
+| Standards | <name> | <url or path> | <version> | binding | ok | <kind> |
+| Firebase | events | <console url> | - | reference only | erişilemedi (auth) | <n events> |
+| Doküman | <file name> | <local path> | <format> | scope document | ok | - |
+| Dış kaynak | <name> | <url> | <citation> | referans | ok | <claim> |
+| Serbest metin | kullanıcı notu | - | - | <what it settled> | - | "<verbatim quote>" |
+| Confluence | <unreachable page> | <url> | - | getirilemedi | erişilemedi (403) | - |
 ```
 
+These row types are exactly what `build-references.mjs` emits, and the example is kept in step with it deliberately: a shape shown here but never produced would send a reader hand-checking against a table that cannot exist. A wiki source arrives as a `Standards` row carrying `wiki` in its `kind` cell, and a generated OpenAPI client arrives as the `Repo` row of the module that holds it; neither has a row type of its own.
+
+**Column contract.**
+
+- **Sürüm / Ref** is the precision anchor: the node id for a Figma frame, `pageId` plus page version for Confluence, the commit SHA the repo was read at, the spec version for Swagger. Without it a reference points at a moving target, and a reader six weeks later cannot tell whether the document described what they are looking at.
+- **Erişim / Access** is `ok` or `erişilemedi (<reason>)`. A source that was declared but could not be fetched still gets a row. Dropping it hides the gap: the reader sees a document that never mentions the API contract and assumes there was none, rather than knowing it was unreachable.
+- **Serbest metin** rows carry what the user stated in conversation that no fetched source contains, quoted verbatim, with the decision it settled in the `Rol` column. Scope decisions made in chat are evidence; leaving them out is how a document loses the reason it excluded something.
+
+**Coverage gate (Locked 34).** Before the document is emitted, the validator compares this table against the evidence record. Every entry in `evidence.figma[]`, `evidence.confluence[]`, `evidence.jira[]`, `evidence.swagger[]`, `evidence.repo[]`, `evidence.standards[]`, `evidence.firebase[]`, `evidence.documents[]`, `evidence.outside[]`, `evidence.freeText[]` and every entry in `evidence.fetchErrors[]` must appear as a row. A source that shaped the document but is missing from References fails the dispatch gate, and a row with no matching evidence entry fails it too - an invented reference is worse than a missing one.
+
 ## 22. Sözlük / Glossary
 
 Footer. Optional in Lite mode. Alphabetical.

package/pipeline/multi-agent-refs/phases/phase-0-init.md

@@ -118,8 +118,8 @@ Run `bash $HOME/.claude/scripts/update-check.sh` (cached per `updateCheck.ttlHou
 
 **Advisory branch (never blocks).**
 
-- **Interactive**: log `→ update available: v<local> -> v<latest>`, ask ONE AskUserQuestion  -  **Update now** (recommended) / **Continue without updating**. On *Update now* (or `updateCheck.autoUpdate: true`, which skips the question): run the `/multi-agent:update` flow, log `→ updated to v<latest>`, continue the run (note in the log: already-loaded phase docs finish this run on the old version; full effect next session). On *Continue*: no re-ask until the TTL expires.
-- **Autopilot**: never ask (zero-interaction contract). Log `→ update available: ... (log-only; run /multi-agent:update)` and continue  -  unless `autoUpdate: true`, then update silently first.
+- **Interactive**: `updateCheck.autoUpdate` defaults to `true`, so do not ask  -  run the `/multi-agent:update` flow, log `→ updated to v<latest>`, continue (docs already loaded finish this run on the old version; full effect next run). Only `autoUpdate: false` makes it a question: log `→ update available: v<local> -> v<latest>`, ask ONE AskUserQuestion  -  **Update now** (recommended) / **Continue without updating**; on *Continue*, no re-ask until the TTL expires.
+- **Autopilot**: never ask (zero-interaction contract). On the default it updates first, logging `→ updated to v<latest>`; on `autoUpdate: false` it is log-only and continues.
 
 Both branches must run BEFORE Step 6 (worktree creation) so an accepted or forced update cannot mutate `~/.claude` under a mid-phase run.
 

package/pipeline/multi-agent-refs/website-deploy.md

@@ -0,0 +1,87 @@
+# Website deploy: why the commit author decides whether the site updates
+
+Loaded by `/multi-agent:sync` Step 4. Read it when a website sync pushed cleanly
+and the live site did not change.
+
+## The failure
+
+The deploy platform builds a commit only when its author is a contributor on the
+project. A commit carrying any other identity is accepted by `git push` and then
+never built:
+
+```
+vercel ls   ->  Status UNKNOWN   Duration ?   Builds: . [0ms]
+API         ->  readyState: "BLOCKED"
+                readyStateReason: "The Deployment was blocked because the commit
+                                   author does not have contributing access ..."
+                seatBlock: { blockCode: "TEAM_ACCESS_REQUIRED", gitProvider: "github" }
+```
+
+Nothing in the push output says so, the deployment exists, and the site keeps
+serving the previous version. Pipeline v16.4.0 and v16.5.0 were both pushed this
+way; neither was ever built, and both syncs reported the website as done.
+
+## The rule
+
+The identity is the one `prefs.global.identities[]` routes to the website owner
+through `platformIdentityRouting`, which is not always the account the current run
+is working under. A run driven from a work account, or an exported
+`GIT_AUTHOR_EMAIL`, is exactly how the wrong author gets recorded.
+
+`$HOME/.claude/scripts/website-deploy-commit.sh` applies the rule:
+
+1. Read the clone's own `user.name` / `user.email` and write only on a mismatch.
+   The website clone is usually already configured correctly; overwriting it with
+   the caller's identity is the defect, not the fix.
+2. Commit only when something is staged.
+3. Read the author back off the commit with `git log -1 --format=%ae`. Setting
+   `git config` is not proof: an exported `GIT_AUTHOR_EMAIL` outranks it. On a
+   mismatch the script halts before pushing, so the bad commit stays local.
+4. Push, then wait for a Ready production build. A push is not a deploy.
+
+Exit codes: `0` committed and pushed (or nothing to do), `1` wrong author and
+nothing pushed, `2` usage or environment, `3` pushed but no Ready build.
+
+Env: `WEBSITE_SYNC_NO_PUSH=1` (local only), `WEBSITE_SYNC_NO_VERIFY=1` (skip the
+deployment check), `WEBSITE_SYNC_WAIT=<sec>` (default 45).
+
+## Recovery when a deployment is already blocked
+
+History does not need rewriting, and `main` is never force-pushed. The platform
+checks the HEAD commit of each new deployment, so a fresh commit under the right
+identity is enough:
+
+```bash
+git commit --allow-empty -m "chore(site): redeploy under the maintainer identity"
+git push origin main
+```
+
+Or deploy from the CLI, which attaches no rejected author:
+
+```bash
+cd "$WEBSITE_DIR" && vercel --prod --yes
+```
+
+Blocked deployments can be left in place; they hold no alias.
+
+## Diagnosing
+
+The CLI prints `UNKNOWN` and hides the reason; the API gives it:
+
+```
+GET https://api.vercel.com/v13/deployments/<dpl_id>?teamId=<team_id>
+    -> readyState, readyStateReason, seatBlock
+```
+
+Read the CLI token out of its own auth file into a variable. Never into argv, a
+log or a reply.
+
+## Verifying the live site
+
+- The repo directory name is not the domain. Check the domain the project
+  actually serves, not `$HOME/{website-host}`.
+- Version strings and counts are server-rendered and appear in the initial HTML.
+  Feature prose and lazily-loaded components do not: grep the JS chunks for those.
+- A `curl` on the HTML can return 403 bot mitigation (`x-vercel-mitigated:
+  challenge`) rather than the page, which reads like content that never shipped.
+  Static assets are not challenged.

package/pipeline/schemas/analysis-spec.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/{owner}/multi-agent-pipeline/pipeline/schemas/analysis-spec.schema.json",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "title": "Multi-Agent Pipeline - /multi-agent:analysis spec output (v3 template)",
   "description": "Contract for the feature-spec analysis document generated by /multi-agent:analysis. Platform-agnostic concept layer + Pass B per-platform render with repo-driven conventions. 23 sections in Full mode; 8 of them in Lite mode. Sections may be absent - omission is the policy when no evidence exists.",
   "type": "object",
@@ -49,6 +49,12 @@
       "default": "v3",
       "description": "Template version emitted. v3 is the platform-agnostic + Pass B render template (Locked 22)."
     },
+    "profile": {
+      "type": "string",
+      "enum": ["global", "corporate"],
+      "default": "global",
+      "description": "Analysis profile chosen at Phase 0 Step 1b (Locked 32). 'global' renders analysis-template.md (23-section development handoff); 'corporate' renders analysis-template-corporate.md (IG/UC/FG requirements document). Both read the same evidence; only the projection differs."
+    },
     "options": {
       "type": "object",
       "additionalProperties": false,
@@ -523,6 +529,20 @@
             }
           }
         },
+        "freeText": {
+          "type": "array",
+          "description": "User statements made in conversation that no fetched source carries, recorded so Section 21 can cite the decisions they settled (Locked 34).",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["text"],
+            "properties": {
+              "label": { "type": "string" },
+              "text": { "type": "string" },
+              "role": { "type": "string" }
+            }
+          }
+        },
         "fetchErrors": {
           "type": "array",
           "description": "Phase 1 access failures (401/403/login-redirect). Surfaced as warnings, not blockers.",