@mmerterden/multi-agent-pipeline 20.11.1 → 20.13.0

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.

package/pipeline/multi-agent-refs/features/doctor.md

@@ -293,6 +293,16 @@ readiness, not correctness: a machine that fails all four still runs the
 pipeline perfectly well with someone watching it. What they catch is the
 failure mode of an unwatched run - stopping without saying so.
 
+
+### usage-report
+
+The outcome `usage-report.mjs` recorded for its last send attempt, read from
+`logs/multi-agent/usage-last-send.json`. SKIP when `usageLog.enabled` is off or
+nothing has been sent yet; OK when the last send was accepted; WARN for every
+other outcome (`redirected`, `rejected`, `not-accepted`, `failed`, `skipped`),
+with the status code or reason and the step that fixes it. The emitter runs
+detached from phase-tracker with its output discarded, so this record is the
+only surface on which a reporting path that stopped working shows up.
 ### unattended-contract
 
 Is `multi-agent-refs/unattended-contract.md` installed. It is the only place

package/pipeline/multi-agent-refs/features/model-fallback.md

@@ -132,6 +132,16 @@ evidence, and there is now one fewer of them. Triage also runs on `opus`, which
 makes it the same model as Reviewer 1; the Step 3 anonymisation requirement
 already covers that case and is not optional here.
 
+**Installed agents follow the switch.** Five personas declare
+`preferredModel: fable` (code-reviewer, plan-critic, and the iOS, Android and
+backend architects). A dispatch the router resolves passes its model explicitly,
+but an agent spawned without one runs on its frontmatter `model:`. So the
+installed copies are written from `fableEnabled`: `fable` while it is on, `opus`
+while it is off. `model-rung.sh` re-applies them on every flip and the installer
+on every install; sources keep `model: fable`, so `lint-personas.mjs` still holds
+`model === preferredModel` there. A `--symlink` install links the source tree and
+is left alone.
+
 **Commands without Phase 0 resolve it themselves.** `/multi-agent:review`,
 `/multi-agent:review-analysis` and the untracked-branch tail of
 `/multi-agent:resume` dispatch reviewers and triage without a Phase 0 Step 0, so

package/pipeline/multi-agent-refs/features/phone-api.md

@@ -303,4 +303,4 @@ Scripts: `contract-server.mjs` (phone branch, `isPhonePath`), `_phone-auth.mjs`
 `unattended-policy.json` (`publisherScripts`). Tests:
 `test/phone-api.test.mjs`, `test/contract-server.test.mjs`,
 `test/launch-request.test.mjs`, `test/redact.test.mjs`,
-`test/contract-kit.test.mjs`, `test/unattended-guard.test.mjs`.
+`test/contract-kit.test.mjs`, `test/unattended-guard.serial.mjs`.

package/pipeline/multi-agent-refs/features/unattended-security.md

@@ -35,7 +35,7 @@ the variable the same way.
 
 With the variable unset every hook behaves as it did without this feature:
 `smoke-unattended-redteam.sh` runs the same inputs both ways, and
-`test/unattended-guard.test.mjs` holds the attended verdicts.
+`test/unattended-guard.serial.mjs` holds the attended verdicts.
 
 ## The guard
 
@@ -722,7 +722,7 @@ Scripts: `agent-guard.sh`, `agent-guard.py`, `unattended_policy.py`,
 `lib/outbound-gate.mjs`, `lib/unattended-settings-location.mjs`,
 `install/_unattended-profile.mjs`. Data:
 `schemas/unattended-policy.json`, `schemas/unattended-profile.json`,
-`schemas/pr-request.schema.json`. Tests: `test/unattended-guard.test.mjs`,
+`schemas/pr-request.schema.json`. Tests: `test/unattended-guard.serial.mjs`,
 `test/pr-request.test.mjs`, `test/autopilot-publish.test.mjs`,
 the runner's tests, `test/outbound-gate.test.mjs`,
 `test/unattended-profile.test.mjs`, `test/agent-guard.test.mjs`; smokes

package/pipeline/multi-agent-refs/features/usage-reporting.md

@@ -147,6 +147,19 @@ reason, `unavailable` with the cause, `declined`, `registered`, `enabled`, `dry-
 "you turned it off" and "we could not reach the endpoint" are different facts
 about the same empty panel.
 
+Every send attempt past the on-switch overwrites
+`~/.claude/logs/multi-agent/usage-last-send.json` with its outcome: `accepted`,
+`not-accepted` (the server answered but did not keep the record), `rejected`
+(with the status code), `redirected` (with the host it pointed to; a redirect is
+never followed, because the token would ride along), `failed` (network or
+timeout), or `skipped` (`no-token`, `no-login`, `endpoint-not-allowed`). It
+carries the run id, the event and the endpoint host, never the token. The
+phase-tracker ping discards the emitter's output, so `/multi-agent:doctor`
+reads this file (check `usage-report`) and turns anything but `accepted` into a
+WARN with one step. `migrate-prefs.mjs` rewrites an endpoint on the platform
+host to the site's domain, so a stored redirecting endpoint does not outlive an
+update.
+
 `prefs.global.usageLog.endpoint` overrides where both calls go - the register URL
 is derived from it, so a self-hosted ingest gets its own registration rather than
 this one's. Absent means the shipped default, and every shipped default names the

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

@@ -57,6 +57,28 @@
       "default": "global",
       "description": "Analysis profile chosen at Phase 0 Step 1b (Locked 31). '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."
     },
+    "edgeCandidates": {
+      "type": "array",
+      "description": "Failure paths proposed from the evidence (refusals, error codes, timeouts, empty or expired states), shown at the Pass B preview. Only accepted ones enter the document; a candidate needs a source.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["target", "candidate", "source"],
+        "properties": {
+          "target": {
+            "type": "string",
+            "description": "Use case or rule group the candidate belongs to, e.g. UC-001 or BR-login."
+          },
+          "candidate": { "type": "string", "minLength": 1 },
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Where the evidence states it: a spec path, a page, a file:line."
+          },
+          "accepted": { "type": "boolean" }
+        }
+      }
+    },
     "options": {
       "type": "object",
       "additionalProperties": false,

package/pipeline/schemas/prefs.schema.json

@@ -948,7 +948,7 @@
                 },
                 "titleFormat": {
                   "type": "string",
-                  "description": "Page-title pattern, e.g. \"{prefix}{module}_{flow}_{suffix}\". Placeholders are resolved at emit time."
+                  "description": "Page-title pattern, e.g. \"{status}{prefix}{module}_{flow}_{suffix}\". Placeholders are resolved at emit time; {status} is the draft marker while the document is not final, and empty once it is. Without {status} the marker is prepended."
                 },
                 "titlePrefix": {
                   "type": "string",
@@ -2107,6 +2107,27 @@
               "type": "string",
               "default": "ma-analysis",
               "description": "Prefix of the identity label a created issue carries. The label is how a second run, on a second machine or by a second analyst, finds the tree it already made instead of opening a duplicate."
+            },
+            "epicLinkMode": {
+              "type": "string",
+              "enum": ["auto", "parent", "epicLinkField", "none"],
+              "default": "auto",
+              "description": "How a story joins an existing epic. auto: parent on Cloud, the epic-link field (found by its schema type) on Server and Data Center, nothing when neither exists."
+            },
+            "epicLinkFieldId": {
+              "type": ["string", "null"],
+              "default": null,
+              "description": "The epic-link custom field id, for epicLinkField mode or to skip discovery. Null means discover."
+            },
+            "cloneByChannel": {
+              "type": "boolean",
+              "default": false,
+              "description": "Create one linked story per channel in channelComponents, each carrying that channel's component."
+            },
+            "cloneLinkType": {
+              "type": "string",
+              "default": "Relates",
+              "description": "The link type between a story and its channel clones, by this site's name."
             }
           }
         },