@mmerterden/multi-agent-pipeline 16.27.0 → 16.28.0

package/CHANGELOG.md

@@ -14,7 +14,77 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ---
 
-## [Unreleased]
+## [16.28.0] - 2026-09-10
+
+### Added
+
+- **The analysis sub-task the pipeline never read.** A development sub-task is usually filed with no description of its own. The fetcher already read the parent when that happened; it never read the siblings, so a board that keeps its analysis in a separate sub-task handed the pipeline an empty task and nothing said so. `issue-fetcher.sh` now reads the parent's other sub-tasks into `descriptor.relatedIssues[]`.
+
+  One search request buys all of them with their descriptions, and only when the issue has a parent, because an issue with no parent has no siblings. That cost claim is measured by `smoke-jira-context.sh` rather than asserted: it counts the requests the fetcher actually issues. The issue's own `subtasks` field lists ITS children, and the parent's lists siblings without descriptions, so either of those shapes would have cost one GET per sibling.
+
+  The payload never touches the `\x1f`-delimited parse the rest of the descriptor travels through - it arrives as one JSON argv - so the eight-field parse, its trailing-newline strip and its unfetched fallback are byte-for-byte what they were. The parent key is re-validated against an anchored pattern before it reaches the query: it comes from the API, but it goes into a URL.
+
+  It reaches `agent-state.json`, unlike the parent feature it sits next to. `/multi-agent:resume` rebuilds context from durable artefacts and never from the conversation, so an intake-only enrichment would be gone by the first resume. The task's own description and maturity are still not persisted; that asymmetry is now written into the schema so the next reader does not mistake it for an oversight.
+
+  `description_empty_sibling_available` fires only when the issue's description AND the parent's are both empty AND a sibling has content, downgrading what is today a hard blocker. The narrowness is the point: `score` loses ten points per warning and the picker only continues silently at `score >= 90`, so a warning that fired whenever an issue merely HAD siblings would turn every parented intake into a question.
+
+- **How many reviewers actually saw a finding.** Phase 4 anonymizes findings so the judge cannot mark its own homework, but the merge stayed a pure judgement call: `validate-triage.mjs` surfaced a repeated fingerprint as a warning and left it there. `anonymize-findings.mjs` now stamps `corroboration: {count, of}` - distinct reviewers per fingerprint - computed where the whole panel is already in one payload, so it costs nothing.
+
+  It is context, not a rule. `docs/adr/0001-three-model-triage.md` rejected majority voting because the same hallucination shows up in two of three same-family reviewers, and that decision stands: the triage hedge now covers corroboration in the same sentence it covers prior art. The reading that pays is the other end - a count of 1 is the finding only one reviewer saw.
+
+- **`council-view.mjs`** renders what each reviewer found and what triage did with it. Everything it needs was already on the state and nothing displayed it; `run-metrics.mjs` reduced it to a ratio and the rows behind the ratio were invisible. De-anonymization is safe here because it runs after triage has ruled, and the gate pins that the map reaches no prompt. `/multi-agent:log` renders it; exit 2 means the run never reached Phase 4.
+
+
+- **A validator summary that says which checks ran.** `validate-analysis-doc.mjs --report` prints every check by name with a verdict each: `ok`, a finding count, or `skipped: <reason>`. The gap it closes is specific - the traceability matrix only runs in the corporate profile, so on a global document it never executed and the output was byte-identical to "ran, found nothing". Attribution is positional and reconciles by construction, so a check added without its mark misnames a finding but can never lose one; the gate asserts the printed set equals the set the file defines. Default output is unchanged for gate callers.
+
+- **Provenance in the reports a human reads.** `evidence_digest` and `base_commit` were already in the document front-matter, on the side only a machine reads. The analysis Phase 5 report, the `review-analysis` verdict and `--report` now carry them too: a timestamp cannot separate two reports made the same day, and the first question anyone asks of an older verdict is which version of the document it judged.
+
+- **A verdict prints its empty classes.** `review-analysis` now names all six rubric classes and every deterministic gate whether or not they fired, with `none` where the count is zero. A verdict that lists only what it found cannot be told apart from one that never looked.
+
+- **The uncertainty marker, in both profiles.** The two-way `AS-NN` pairing between the body and Section 20 ran only under `profile: corporate`, which made the global profile the one place an inline marker could point at nothing. Two documents already said otherwise - Locked 36 makes an unstamped gap fail the dispatch gate with no profile clause, and `analysis/render.md` routes an external-dependency gap to `AS-NN` for every run - so the check was the only side that disagreed. A document carrying no markers is unaffected: every loop is empty.
+
+- **Every open question names an owner.** "A gap with an owner is a plan; a gap without one is a defect" lived in `analysis/review.md`, which is a model's judgement. It is now a validator error. The owner column is located from the table header rather than by index, because the two profiles order Section 20 differently and an index would silently read the wrong cell in one of them.
+
+- **`status: draft | final`, the closure gate.** Nothing stopped a document with open questions from being published. Under `final` an unresolved `AS-NN` or an open Section 20 row is now an ERROR; under `draft` it is counted and nothing blocks. The key is optional and absent means `draft`, so no document written before it starts failing. `/multi-agent:analysis-resolve` flips it at the end of a run, with a confirmation - `final` is a publication claim, and that command is built on one question per decision.
+
+- **`not-for:` frontmatter, and a warning that shrinks.** `lint-skills.mjs` reported nine trigger-vocabulary collisions every run and the list never moved: an author read it, had nothing to do about it, and stopped reading. A skill may now name the siblings it must not be chosen for, which the model sees on the routing surface itself and the lint consumes to drop the pair. Suppression is never silent - settled pairs are counted - and a name that resolves to no sibling on the same surface is an error, because a typo would otherwise leave the pair unanswered while the author believes it is handled. `review-issue`/`review-jira` and `issue`/`jira` are tagged; the list is five.
+
+- `ANALYSIS_CEILING` 154500 -> 155000. The report shape is defined only in `analysis/render.md` and a front-matter key is documented only where the front-matter block is, so those two additions had to land inside the count; everything else in this pass stayed outside it. Both were compressed once before measuring, and 295 bytes of headroom against 213 still owed left no way to avoid the raise.
+
+- **Redesign mode.** `options.redesign` is an intake opt-in that adds three artefacts to the document, all of them claims about v1 rather than plans for v2: current behaviour with `CB-<slug>-NN` ids and `repo/file:line` citations, the v1 to v2 endpoint mapping, and a difference list over a closed status vocabulary (`Moved / Partial / Missing / New / Out of scope`). Every `Missing` and `Partial` owes a Section 20 row by `AS-NN` - a behaviour v2 drops with no decision is the thing a redesign loses and production finds.
+
+  It is an option, not a third `mode` value. `mode` says how many sections, `redesign` says which content, and since `mode === "full"` branches in four places inside the validator, a `mode: redesign` would have switched off the traceability matrix, the Test Plan requirement and the rule-to-test cross-check in exactly the documents that need them most. A small screen can also have a lite redesign.
+
+  Eight validator checks, of which two are worth naming: a `CB-` id present in one table and absent from the other fails in **both** directions, and the three sections must exist before any row check is trusted, because row checks over a missing section pass over nothing and show the gate green. Evidence and certainty are derived by the renderer from `repoEvidence`, never graded by the writer, which is Locked 24 applied to a second table. `options.redesign` is an `evidence_digest` input: without that one line, a redesign started within a day of a normal run on the same feature would reuse that cache, skip Phase 1b and render an empty behaviour table that all eight checks then pass over.
+
+  The contract, its reasoning and the check table live in `analysis/redesign.md`, which `analysis/SKILL.md` does not name and which therefore loads only on a redesign run.
+
+- `ANALYSIS_CEILING` 155000 -> 158500, the largest single raise it has taken. What could not be moved out is the argument: the section skeletons belong in `analysis-template.md`, where every other conditional section (15.6, 16.2) is already defined; Locked 37 belongs in `analysis/locked.md`, because a decision recorded only where it is implemented is not locked; and the intake question belongs in `analysis/intake.md`, because the option is chosen before anything knows the run is a redesign. 5.9 kB stayed outside the count. Everything was compressed twice before the number was picked.
+### Fixed
+
+- `learn-from-transcripts.mjs` called `process.exit(0)` on the line after writing its `--json` result, so a large mining result was cut at the 64 KB pipe buffer - the exact defect the gate added in 16.27.0 exists to prevent, in the file that motivated it. The gate caught it; the two sites it named are now a `main()` with a return.
+
+- `skill-siblings.mjs` resolved its trees from the script's own location with no fallback, so from an install (`~/.claude/scripts`) it looked for `~/pipeline/commands/multi-agent`, found nothing, and exited 1. `observations.mjs` caught that and wrote the note `"<target>: not a skill surface"` about files that are skill surfaces - a friction log silently keeping a false record. Resolution is now two-candidate, repo first then the install, and from an install the authored surfaces are reported as not applicable rather than absent: `--audit` says the authored side was not checked instead of borrowing the repo's verdict.
+
+- The stdout-exit detector in `smoke-consumer-smoke-surface.sh` only matched a literal `process.stdout.write` on the line, so `console.log` and any one-line helper wrapping either (`emit()`) were invisible to it. It now resolves same-file helpers one level, skips declaration lines and stops the lookahead at a control-flow terminator. The three analysis validators are on the watch list and converted to `process.exitCode`.
+
+- `smoke-install-layout.sh` fixture regenerated: `council-view.mjs` and `features/jira-context.md` moved the installed counts.
+
+- **The phase widget could not render on a Claude Code build without the tile API.** `TaskCreate` and `TaskUpdate` are not in every build, and `phase-tracker.sh` cannot see the model's tool list, so both the bootstrap and every phase boundary named a tool the host does not have and neither named what to do instead. The tracker state was written correctly, every phase advanced, and the screen stayed empty for the whole run. Both outputs now carry the fallback on the same line - the bordered card IS the widget on such a build, reprinted inside the reply at every boundary, which is what Copilot has always done - and `tiles` renders the card itself so the fallback content is already on screen. The branch is taken where the information lives: the model knows which tools it has, the shell does not.
+
+- **The closure gate read the wrong row, and then read it wrongly.** `status: final` decided whether an `AS-NN` was still open by taking the first table row in the document that mentioned the id. The corporate template writes `| **Request** | EKLENECEK (AS-NN) |` in the body, so that row won and a final document shipped with live placeholders. Openness now comes from the Section 20 row only, and from its status CELL located by header - and where there is no status column (the corporate Section 20 has none) an `EKLENECEK` still stamped with the id is itself the signal.
+
+  The second half of the same line was a substring search: `açıklama` contains `Açık`, so a correctly closed Turkish row reading `Karar verildi / Decided` whose question text said "hata açıklaması" was reported as open and blocked. The status vocabulary is now matched per token across the bilingual `/`, never as a substring. English had the same trap in "reopened".
+
+- **A finding that arrived inside a skipped check vanished from `--report`.** `mark()` printed the skip label whenever one was passed, so a malformed `status` value (caught by the closure gate, which then reports "draft document") and the redesign drift warning (raised by the branch that reports "not a redesign") were both on stderr and absent from the report. A count now outranks a skip label, which is what makes the registry's own claim - that a finding can be misnamed but never lost - true.
+
+- **`council-view.mjs` rendered every ruled-out finding as `unruled`.** `triage-output.schema.json` defines a deferred or rejected item as `{finding, reason}` - the reason is the point of those buckets - while `accepted[]` is a flat finding. The view read the id off the wrapper. Its own fixture used the flat shape, so the gate passed; the fixture is now checked against the schema it represents.
+
+- `council-view.mjs --iteration` with no value made the filter compare against `NaN` and exited 2 on a state full of iterations. `/multi-agent:log` reads exit 2 as "the run never reached Phase 4" and omits the section, so a usage error looked like an empty run. It is now exit 64.
+
+- The endpoint-mapping column check counted raw `|` segments, so a valid GFM row without the optional trailing pipe was reported as short.
+
+- The redesign drift warning fired on prose that merely used the words. `sectionBody` matches its keyword as a raw substring of the heading, deliberately, because Locked 2 re-flows section numbers - so `### 4.9 Notes on the old Current Behaviour audit process` matched, and Phase 4 runs `--strict`, which turned that warning into a blocked document. The rendered artefact is the honest signal: a current-behaviour table always carries `CB-<slug>-NN` ids and a paragraph using the words never does.
 
 ## [16.27.0] - 2026-09-10
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "16.27.0",
+  "version": "16.28.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",
@@ -101,10 +101,10 @@
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "c8": "^12.0.0",
-    "eslint": "^10.8.0",
+    "eslint": "^10.10.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-n": "^18.2.2",
+    "eslint-plugin-n": "^18.3.0",
     "prettier": "^3.9.6",
-    "publint": "0.3.22"
+    "publint": "0.3.24"
   }
 }

package/pipeline/commands/multi-agent/SKILL.md

@@ -203,7 +203,7 @@ When the user supplies an ID/URL/free-text:
 2. **Pick account**  -  always asked (autopilot picks default)
 3. **Fetch issue**  -  `lib/issue-fetcher.sh "$INPUT"` (Jira/GitHub fetch + maturity)
 4. **Repo picker**  -  only for `gh-num` (e.g. `316`) when repo is ambiguous, multi-select
-5. **Maturity check**  -  blocker halts (autopilot too), warning prompt/log. For a Jira input specifically, an empty own description with a non-empty parent surfaces as `description_empty_parent_available` (warning, not blocker)  -  ask the tailored parent-description question from `jira/SKILL.md`'s maturity section instead of the generic "Continue?" prompt.
+5. **Maturity check**  -  blocker halts (autopilot too), warning prompt/log. For a Jira input specifically, an empty own description with a non-empty parent surfaces as `description_empty_parent_available` (warning, not blocker)  -  ask the tailored parent-description question from `jira/SKILL.md`'s maturity section instead of the generic "Continue?" prompt. When the parent is empty too, `description_empty_sibling_available` says a sibling sub-task carries the content; `descriptor.relatedIssues[]` holds them either way.
 6. **Dev context**  -  always runs, empty submit allowed
 7. → Interactive Launcher → Phase 0
 

package/pipeline/commands/multi-agent/issue/SKILL.md

@@ -2,6 +2,7 @@
 description: "List unassigned GitHub issues, pick one, auto-assign, and launch the multi-agent pipeline. Use when a GitHub issue should be picked up and started without knowing its number in advance."
 description-tr: "Atanmamış GitHub issue'larını listeler, birini seçtirir, otomatik atar ve multi-agent pipeline'ı başlatır."
 argument-hint: "[autopilot]  -  optional: run the pipeline without confirmations"
+not-for: jira
 ---
 
 # multi-agent issue  -  4-Step Picker (Account → Repos → Issue → Dev Context)

package/pipeline/commands/multi-agent/jira/SKILL.md

@@ -85,11 +85,14 @@ After issue selection, inspect `maturity` from `~/.claude/lib/issue-fetcher.sh`:
 > - **Accept** → set the working `description` to `parentDescription` for every later phase (analysis/dev/review all read this one substituted value); log the substitution (source issue + parent key) to `agent-log.md`.
 > - **Decline** → same as a `description_empty` blocker: halt, advise fixing the issue's own description.
 > - **Autopilot**: auto-accepts "Use parent's description" (same "warnings auto-continue" rule as any other warning), logs the auto-accept + parent key to `agent-log.md`.
+>
+> **Sibling sub-tasks**: the fetcher also reads the parent's other sub-tasks into `descriptor.relatedIssues[]`. Show them as their own labelled block, never substituted into `description`. When the issue's description and the parent's are both empty but a sibling has content, `description_empty_sibling_available` replaces the `description_empty` blocker  -  same question, sibling key. Contract: `$HOME/.claude/multi-agent-refs/features/jira-context.md`.
 
 | Outcome | Behavior |
 |---|---|
 | `blockers` non-empty | **Halt** (autopilot too): show summary, advise "fix the issue first" |
 | `warnings` contains `description_empty_parent_available` | Tailored parent-description question above (not the generic one) |
+| `warnings` contains `description_empty_sibling_available` | Same question, sibling key substituted for the parent's |
 | other `warnings` only | AskUserQuestion: show summary + "Continue?". Autopilot auto-continues; warnings logged to `agent-log.md` |
 | both empty (score ≥ 90) | Continue silently |
 

package/pipeline/commands/multi-agent/log/SKILL.md

@@ -29,4 +29,10 @@ Show the task's detailed agent-log.md report.
    ```
    Exit 2 means no tracker data exists  -  say so in one line (`cost unavailable: no token telemetry recorded`) instead of leaving the section out silently.
 
-5. **Provide a summary**  -  when the log is long, show only the Timeline table + Review Consensus + the cost block, and give the file path for the full log.
+5. **Council view**  -  the log records the verdict, not who found what. Render the panel from the state:
+   ```bash
+   node $HOME/.claude/scripts/council-view.mjs "<artifacts>/agent-state.json"
+   ```
+   Exit 2 means the run never reached Phase 4  -  omit the section rather than reporting an error. The `Seen by` column is how many distinct reviewers raised that finding; it is information, not a verdict.
+
+6. **Provide a summary**  -  when the log is long, show only the Timeline table + Review Consensus + the cost block, and give the file path for the full log.

package/pipeline/commands/multi-agent/review-issue/SKILL.md

@@ -2,6 +2,7 @@
 description: "Assess whether a GitHub issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as an issue comment. Read-only on code. Use when deciding whether a GitHub issue is specified well enough to hand to development."
 description-tr: "Bir GitHub issue'sunun multi-agent geliştirmeye hazır olup olmadığını değerlendirir: getirir; kapsam / kabul kriterleri / repro / tasarım / API / stack hazırlığını puanlar, sonra (onay sonrası) eksikleri issue yorumu olarak gönderir. Kodda salt-okunur."
 argument-hint: "[#N | repo#N | GitHub issue URL]  -  optional; with no argument, pick from open issues"
+not-for: review-jira
 ---
 
 # multi-agent review-issue  -  GitHub issue readiness review

package/pipeline/lib/issue-fetcher.sh

@@ -123,8 +123,11 @@ branch_for() {
 # token never appears in argv (argv is visible to `ps` / process audit).
 jira_auth_cfg() { printf 'header = "Authorization: Bearer %s"\n' "$1"; }
 
-fetch_jira() {
-  local key="$1"
+# Resolve the credential helper once and issue one authenticated GET. Split
+# out of fetch_jira so the sibling search reuses the same resolution instead
+# of duplicating thirty lines of it.
+jira_curl() {
+  local path="$1"
   if [ -z "$JIRA_HOST" ] || [ -z "$JIRA_TOKEN_KEY" ]; then
     echo "ERR: ACCOUNT_JIRA_HOST and ACCOUNT_JIRA_TOKEN_KEY must be set" >&2
     return 1
@@ -160,11 +163,28 @@ fetch_jira() {
     echo "ERR: Jira token not found in credential store ($JIRA_TOKEN_KEY)" >&2
     return 1
   fi
-  curl -sf -K <(jira_auth_cfg "$token") \
-    "https://$JIRA_HOST/rest/api/2/issue/$key?fields=summary,status,issuetype,description,priority,resolution,fixVersions,parent" \
+  curl -sf -K <(jira_auth_cfg "$token") "https://$JIRA_HOST$path"
+}
+
+# The field list is a parameter because the related-issue lookup wants a
+# narrow one; the default is the set every caller needed before it existed.
+fetch_jira() {
+  local key="$1"
+  local fields="${2:-summary,status,issuetype,description,priority,resolution,fixVersions,parent}"
+  jira_curl "/rest/api/2/issue/$key?fields=$fields" \
     || { echo "ERR: Jira fetch failed for $key" >&2; return 1; }
 }
 
+# One request returns every sibling WITH its description. The issue's own
+# `subtasks` field lists ITS children, not its siblings, and the parent's
+# lists siblings without descriptions  -  either shape costs one GET each.
+# Failure is soft: the caller falls back to an empty list and the run goes on.
+jira_search() {
+  local jql="$1" fields="$2" maxr="$3"
+  jira_curl "/rest/api/2/search?jql=$jql&fields=$fields&maxResults=$maxr" \
+    || { echo "WARN: Jira search failed  -  related issues unavailable" >&2; return 1; }
+}
+
 fetch_github() {
   local owner="$1" repo="$2" num="$3"
   if ! command -v gh >/dev/null 2>&1; then
@@ -207,6 +227,16 @@ priority_weights = {
 }
 priority_weight = priority_weights.get(priority.lower(), 0)
 
+# relatedIssues arrives as one JSON argv rather than through the \x1f channel,
+# so the delimited parse below stays exactly eight fields wide. Anything
+# unparseable degrades to an empty list; a fetcher must not die on context.
+try:
+    related = json.loads(fields.get("relatedIssues") or "[]")
+except Exception:
+    related = []
+if not isinstance(related, list):
+    related = []
+
 descriptor = {
     "kind":        fields.get("kind"),
     "key":         fields.get("key") or None,
@@ -225,6 +255,7 @@ descriptor = {
     "owner":       fields.get("owner") or None,
     "repo":        fields.get("repo") or None,
     "branchHint":  fields.get("branchHint") or None,
+    "relatedIssues": related,
 }
 extra = {}
 if fields.get("needsRepoPicker"):
@@ -238,6 +269,8 @@ itype = (descriptor.get("type") or "").lower()
 
 parent_desc = (descriptor.get("parentDescription") or "").strip()
 parent_key = descriptor.get("parentKey") or ""
+sibling_key = next((r.get("key") or "" for r in related
+                    if isinstance(r, dict) and (r.get("description") or "").strip()), "")
 
 blockers, warnings = [], []
 closed = {"done","closed","cancelled","canceled","resolved"}
@@ -253,6 +286,11 @@ if not desc.strip():
     # No parent / an equally-empty parent keeps the hard blocker as before.
     if parent_desc:
         warnings.append("description_empty_parent_available")
+    elif sibling_key:
+        # Same shape one level out: the analysis sibling is where the content
+        # actually is on some boards. Only fires when the parent has none, so
+        # it never costs a point on an issue that reads fine.
+        warnings.append("description_empty_sibling_available")
     else:
         blockers.append("description_empty")
 elif len(desc.strip()) < 80:
@@ -273,6 +311,7 @@ labels_tr = {
     "already_resolved":      "Issue zaten resolved/merged ({})".format(resolution or " - "),
     "description_empty":     "Açıklama boş",
     "description_empty_parent_available":"Açıklama boş ama parent'ta ({}) içerik var  -  oradan devam edilsin mi?".format(parent_key or " - "),
+    "description_empty_sibling_available":"Açıklama boş, parent da boş, ama kardeş maddede ({}) içerik var  -  oradan devam edilsin mi?".format(sibling_key or " - "),
     "short_description":     "Açıklama çok kısa (<80 karakter)",
     "short_title":           "Başlık çok kısa (<10 karakter)",
     "no_repro_steps":        "Bug için repro adımları yok",
@@ -283,6 +322,7 @@ labels_en = {
     "already_resolved":      "Issue already resolved/merged ({})".format(resolution or " - "),
     "description_empty":     "Description is empty",
     "description_empty_parent_available":"Description is empty but the parent ({}) has content  -  continue from there?".format(parent_key or " - "),
+    "description_empty_sibling_available":"Description is empty and so is the parent, but a sibling issue ({}) has content  -  continue from there?".format(sibling_key or " - "),
     "short_description":     "Description too short (<80 chars)",
     "short_title":           "Title too short (<10 chars)",
     "no_repro_steps":        "Bug missing reproduction steps",
@@ -383,13 +423,102 @@ sys.stdout.write((f.get("description") or "").replace("\x1f", " "))
         fi
       fi
     fi
+    # A development sub-task's siblings under the same parent carry the rest of
+    # the picture: the analysis sub-task is often the one with content while the
+    # dev task has none. One search returns all of them WITH their descriptions,
+    # so this costs exactly one extra request, and none at all on an issue with
+    # no parent. Gated on parentkey alone, not on an empty own description  -
+    # the analysis sibling is worth reading even when the dev task is filled in.
+    # Read prefs only once parentkey is known non-empty: an issue with no parent
+    # is the common case and should not pay for an interpreter start. Env wins,
+    # which is what lets the offline gate drive every branch without a prefs file.
+    prefs_jiraContext_enabled="${JIRA_CONTEXT_ENABLED:-}"
+    prefs_jiraContext_maxItems="${JIRA_CONTEXT_MAX_ITEMS:-}"
+    prefs_jiraContext_maxCharsPerItem="${JIRA_CONTEXT_MAX_CHARS:-}"
+    if [ -n "${parentkey:-}" ] && { [ -z "$prefs_jiraContext_enabled" ] || \
+         [ -z "$prefs_jiraContext_maxItems" ] || [ -z "$prefs_jiraContext_maxCharsPerItem" ]; }; then
+      _jc=$(python3 - <<'PY' 2>/dev/null || true
+import json, os
+p = os.path.expanduser("~/.claude/multi-agent-preferences.json")
+c = {}
+try:
+    c = ((json.load(open(p, encoding="utf-8")).get("global") or {}).get("jiraContext") or {})
+except Exception:
+    c = {}
+print("%s %s %s" % (
+    "false" if c.get("enabled") is False else "true",
+    int(c.get("maxItems", 6)),
+    int(c.get("maxCharsPerItem", 1200)),
+))
+PY
+)
+      # Parameter expansion, not `set --`: the positional parameters belong to
+      # the script and the jira-url branch re-execs with them.
+      _jc="${_jc:-true 6 1200}"
+      _jc_rest="${_jc#* }"
+      [ -n "$prefs_jiraContext_enabled" ] || prefs_jiraContext_enabled="${_jc%% *}"
+      [ -n "$prefs_jiraContext_maxItems" ] || prefs_jiraContext_maxItems="${_jc_rest%% *}"
+      [ -n "$prefs_jiraContext_maxCharsPerItem" ] || prefs_jiraContext_maxCharsPerItem="${_jc_rest##* }"
+      unset _jc _jc_rest
+    fi
+    : "${prefs_jiraContext_enabled:=true}"
+    : "${prefs_jiraContext_maxItems:=6}"
+    : "${prefs_jiraContext_maxCharsPerItem:=1200}"
+    relatedjson="[]"
+    if [ -n "${parentkey:-}" ] && [ "$prefs_jiraContext_enabled" = "true" ] && [ "$prefs_jiraContext_maxItems" -gt 0 ]; then
+      # parentkey is API-supplied but goes straight into a URL query, so it is
+      # re-validated against the same anchored pattern detect_kind uses. That
+      # makes the encoding trivial and closes the JQL-injection path.
+      if printf '%s' "$parentkey" | grep -qE '^[A-Z][A-Z0-9]*-[0-9]+$'; then
+        sraw=$(jira_search "parent%3D%22$parentkey%22" \
+                 "summary,issuetype,status,description" 20) || sraw=""
+        if [ -n "$sraw" ]; then
+          relatedjson=$(printf '%s' "$sraw" | SELF_KEY="$KEY" \
+            RELATED_MAX="$prefs_jiraContext_maxItems" RELATED_CHARS="$prefs_jiraContext_maxCharsPerItem" python3 -c '
+import json, os, sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.stdout.write("[]"); raise SystemExit(0)
+self_key = os.environ.get("SELF_KEY", "")
+cap = int(os.environ.get("RELATED_MAX") or 0)
+chars = int(os.environ.get("RELATED_CHARS") or 0)
+out = []
+for i in d.get("issues") or []:
+    key = i.get("key") or ""
+    if not key or key == self_key:
+        continue
+    f = i.get("fields") or {}
+    desc = (f.get("description") or "").replace("\x1f", " ")
+    truncated = False
+    if chars and len(desc) > chars:
+        desc = desc[:chars] + "..."
+        truncated = True
+    out.append({
+        "key": key,
+        "relation": "sibling",
+        "type": ((f.get("issuetype") or {}).get("name") or ""),
+        "status": ((f.get("status") or {}).get("name") or ""),
+        "summary": (f.get("summary") or ""),
+        "description": desc,
+        "truncated": truncated,
+    })
+# Siblings that carry content come first, so the cap keeps the useful ones.
+out.sort(key=lambda r: 0 if r["description"].strip() else 1)
+sys.stdout.write(json.dumps(out[:cap], ensure_ascii=False))
+') || relatedjson="[]"
+        fi
+      fi
+    fi
+    [ -n "$relatedjson" ] || relatedjson="[]"
     branch=$(branch_for "$KEY" "$itype" "$title")
     emit_descriptor \
       "kind=jira" "key=$KEY" "title=$title" "type=$itype" "status=$status" \
       "description=$description" "host=$JIRA_HOST" \
       "url=https://$JIRA_HOST/browse/$KEY" "branchHint=$branch" \
       "priority=$priority" "resolution=$resolution" "fixVersions=$fixversions" \
-      "parentKey=$parentkey" "parentDescription=$parentdesc"
+      "parentKey=$parentkey" "parentDescription=$parentdesc" \
+      "relatedIssues=$relatedjson"
     ;;
 
   jira-url)

package/pipeline/lib/multi-repo-pipeline.sh

@@ -18,6 +18,7 @@
 #     "branch":"feature/PROJ-1",
 #     "baseBranch":"develop",
 #     "issueRef":{"kind":"jira","key":"PROJ-1","title":"...", ...},
+#                       (may carry relatedIssues[] from issue-fetcher.sh)
 #     "primary":   {"name":"my-ios-app","cloneUrl":"...","provider":"github"},
 #     "extras":   [{"name":"common","cloneUrl":"...","provider":"github"}, ...],
 #     "worktreeRoot":".worktrees/PROJ-1-20260427",
@@ -300,6 +301,13 @@ agent_state = {
     "projects":      [repo_entry(r, i == 0) for i, r in enumerate(all_repos)],
 }
 
+# Written only when non-empty, so a GitHub or free-text bridge produces the
+# same bytes it always did. Phase 1 and Phase 2 read it; without it here the
+# context would be intake-only and every resume would start without it.
+related = issue.get("relatedIssues") or []
+if isinstance(related, list) and related:
+    agent_state["relatedIssues"] = related
+
 logs_dir = os.path.expanduser(os.path.join("~/.claude/logs/multi-agent", primary["name"], state["taskId"]))
 os.makedirs(logs_dir, exist_ok=True)
 out_path = os.path.join(logs_dir, "agent-state.json")

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

@@ -202,7 +202,7 @@ Phase 2 Section 20 Risks reads this list and emits one open question per entry.
 
 **Fallback source**: when `confidence == "none"` AND `evidence.standards[]` does not contain an explicit rule for that field, the renderer reads `$HOME/.claude/multi-agent-refs/conventions-defaults.md` and applies the platform default.
 
-**Caching (Locked 27)**: compute `evidence_digest = sha256(featureName || sorted(platforms) || hash(evidence.repoEvidence) || hash(evidence.conventions))`. Cache key on disk: `/tmp/multi-agent-analysis-cache/<digest>.json` with mtime <= 24h. Cache hit skips Phase 1b and Phase 1c. `--no-cache` flag forces re-run.
+**Caching (Locked 27)**: compute `evidence_digest = sha256(featureName || sorted(platforms) || options.redesign || hash(evidence.repoEvidence) || hash(evidence.conventions))`. `options.redesign` is a digest input: without it a redesign within a day of a normal run on the same feature reuses that cache, skips Phase 1b, and renders an empty current-behaviour table every redesign check then passes over. Cache key on disk: `/tmp/multi-agent-analysis-cache/<digest>.json` with mtime <= 24h. Cache hit skips Phase 1b and Phase 1c. `--no-cache` flag forces re-run.
 
 Phase 1d is deliberately absent from the digest inputs. Community signal changes by the hour, so folding it in would produce a new digest on every run, invalidate the cache every time, and re-run the two expensive repo phases the cache exists to skip. The consequence is worth stating plainly: a cache hit reuses yesterday's signal rows. That is the correct trade for an advisory tier, and `--no-cache` is the way to refresh them.
 

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

@@ -239,9 +239,9 @@ Firebase question  -  Auto-detect mode probe order (option 2):
 2. Generated `AnalyticsEvents/*.swift` / `AnalyticsEvents/*.kt` if present (treat each public struct conforming to `AnalyticsEvent` as one event)
 3. Repo-level `firebase-events.json` / `analytics/events.json` files
 
-#### Step 5a - Coverage options (opt-in, 2 questions)
+#### Step 5a - Coverage options (opt-in, 3 questions)
 
-One `AskUserQuestion` call with 2 parallel yes/no questions  -  or 1 when
+One `AskUserQuestion` call with 3 parallel questions  -  or 2 when
 `state.analysisSpec.platforms[]` is empty, since `uiTests` only gates a section the
 development layer would have carried (see the gating table in Step 5). These are opt-INs, not source intake: an empty answer is NOT consent (per `feedback_no-inferred-defaults-from-empty-answer`) - re-ask on empty rather than defaulting silently once the picker is shown.
 
@@ -257,12 +257,21 @@ Q2: header="A11y depth"
     options:
       - label: "Basic checklist"       -> state.analysisSpec.options.a11yDepth = "basic" (default)
       - label: "Full walkthrough"      -> state.analysisSpec.options.a11yDepth = "full"
+
+Q3: header="Redesign"
+    question: <localized: "Does this replace something that already exists? A redesign also records what v1 does today and where each behaviour goes.">
+    options:
+      - label: "New work"  -> state.analysisSpec.options.redesign = false (default)
+      - label: "Redesign"  -> state.analysisSpec.options.redesign = true
 ```
 
 `options.uiTests` gates Section 15.6 (UI test flows), which lives in the development
 layer; `options.a11yDepth` gates the Section 16 VoiceOver / TalkBack walkthrough, which
 does not. Both default to the lighter choice so the doc stays lean unless the user opts in.
 
+`options.redesign` gates Sections 4.5, 4.6 and 9.5 and loads `analysis/redesign.md`, read
+on no other run (Locked 37).
+
 #### Step 5b - Repo-evidence collector (automatic, no prompt)
 
 Runs after Step 5a submits and before Phase 1 begins. Reads from `state.analysisSpec.repos[]`. For each repo, walks the platform whitelist and produces a 13-bucket evidence catalogue. No user interaction. Output: `state.analysisSpec.evidence.repoEvidence[<repo>]`. See Phase 1b for the bucket list and tagging rules.

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

@@ -57,3 +57,4 @@ When citing a Locked decision in code or docs, prefer `Locked <n> (<short label>
 34. **References are built from the evidence record, not written.** Section 21 is emitted by `$HOME/.claude/scripts/build-references.mjs` from `state.analysisSpec.evidence.*` in both profiles. Each row carries a precision anchor in its `Sürüm / Ref` column - Figma node id, Confluence `pageId` plus page version, the commit SHA a repo was read at, the Swagger spec version - because a reference with no anchor points at a moving target. Each row carries an `Erişim / Access` cell: a declared source that could not be fetched still gets a row reading `erişilemedi (<reason>)`, since a silently dropped source reads to the next person as a source that never existed. User statements from the conversation that no fetched source contains are recorded as `Serbest metin` rows, quoted verbatim, with the decision they settled. **Coverage gate**: every entry in `evidence.figma[]`, `confluence[]`, `jira[]`, `swagger[]`, `repo[]`, `standards[]`, `firebase[]`, `documents[]`, `outside[]`, `freeText[]` and every entry in `evidence.fetchErrors[]` must appear as a row, and every row must map to an evidence entry. A source that shaped the document but is missing from References fails the dispatch gate; so does an invented row with no evidence behind it.
 35. **Stack-optional render.** Platform and repo selection are optional. When `state.analysisSpec.platforms[]` is empty, the run still completes: the analysis layers that do not need a target repository render in full - Part A and Part B in the corporate profile, Sections 1-12 and 16-17 in the global profile - and only the development layer is dropped (corporate Part C; global Sections 13, 14, 15) along with the Pass B projection, since there are no conventions to project onto. A Section 20 row records that the development analysis awaits a repo selection. **The channel split survives the missing repo.** Channels are derived from the evidence instead of repo stack tags (`intake.md` Step 3 carries the signal table) and one document is emitted per derived channel - `mobile`, `web`, or both. A phone screen and a browser screen carry different requirements before anyone has picked a repository; the split (Locked 9) exists to carry that difference and only its *projection* half needs conventions. `mobile` stays one channel rather than iOS plus Android, since without conventions nothing tells the two apart. Evidence with no interface at all yields a single channel-agnostic `<feature>.md`. Files land under `~/Desktop/multiAgentAnalysis/<feature-name>/`, named `<feature>-<channel>.md` (or `<feature>.md` for the channel-agnostic case): the repo-relative `analysis/` path has nothing to be relative to without a repo, and the current working directory is never used, since for a repo-less run it is arbitrary. Desktop rather than a hidden directory because the document is a deliverable somebody is meant to open and hand over, and `multiAgentAnalysis` rather than a bare `Analysis` because a generic word collides with whatever else is on a desktop while the producer name groups every run this command ever writes. The Phase 3.5 picker shows the resolved path and takes an override through its Other input. A requirements document is useful before anyone has decided which repository will hold the code, and refusing to produce one until that decision exists inverts the order the work actually happens in.
 36. **The document is reviewed before it is published.** An analysis run used to go from draft straight to dispatch behind a deterministic validator, so nothing read what it was about to publish: one run put a channel it never searched for, an open question about a frame it never opened, and twenty-three unowned `EKLENECEK` markers onto a live page. Every one is what a reader catches on the first pass. Phase 3.2 runs `phases/phase-4-review.md` Step 0 (strict validator, the host's three-reviewer set, triage) on the draft before the destination is chosen: a finding is cheap while nothing is written. Reviewers are subagents holding `analysis/review.md`, never the context that wrote the document, which cannot notice a search it never thought to run. A blocking finding returns to Phase 2b with dispatch closed and never becomes an open question, since "the document is wrong" is not something to ask the reader; capped at two returns. Phase 3.3 sorts every remaining gap into searched-and-closed, asked-and-answered, or `AS-NN`; an unstamped gap fails the dispatch gate. Autopilot runs both; only the asking degrades, into rows stamped `autopilot: could not ask`.
+37. **A redesign records v1 before it plans v2.** `options.redesign` is an opt-in on the `options.uiTests` axis, never a third `mode` value: `mode` says how many sections, `redesign` says which content, and a `mode: redesign` would switch off the Full-mode traceability, Test Plan and rule-to-test gates in exactly the documents that need them. It adds three sub-sections and no top-level section: current behaviour with `CB-<slug>-NN` ids and `repo/file:line` citations, the v1 to v2 endpoint mapping, and a difference list over a closed status vocabulary. Every `Missing` and `Partial` owes a Section 20 row by `AS-NN`, and a `CB-` id in one table but not the other fails in both directions - a behaviour that is in the code and on nobody's difference list is what a redesign loses and production finds. Evidence and certainty are derived from `repoEvidence`, never graded by the writer (Locked 24, same reason), and `options.redesign` is an `evidence_digest` input. Contract and the eight checks: `analysis/redesign.md`, loaded only on a redesign run.

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

@@ -0,0 +1,112 @@
+# Redesign mode - the contract
+
+Loaded only when `state.analysisSpec.options.redesign` is true, the same way
+`analysis/review.md` is loaded only by a reviewer subagent. A run that is not a
+redesign never pays for this file.
+
+## What the mode is for
+
+A redesign is not a feature. The thing already exists, somebody is going to
+replace it, and the question a reader has is not "what should v2 do" but "what
+does v1 do that v2 must not lose". A normal analysis answers the first question
+and is silent on the second, so the losses surface in production: a validation
+rule nobody wrote down, an error state only the old screen had, a query
+parameter one caller still sends.
+
+So the mode adds exactly three artefacts, and every one of them is a claim about
+v1 rather than a plan for v2.
+
+## Why it is an option and not a mode
+
+`mode` says how many sections the document carries. `redesign` says which
+content is required. They are different axes, and collapsing them costs real
+checks: `mode === "full"` branches in four places inside
+`validate-analysis-doc.mjs`, so a `mode: redesign` value would silently switch
+off the traceability matrix, the Test Plan requirement and the business-rule to
+test-scenario cross-check - in the documents that need them most. A small screen
+can also have a lite redesign, and that is a real thing to want.
+
+The shape therefore matches `options.uiTests` and `options.a11yDepth` exactly: an
+intake opt-in, written into the front-matter, enforced by the validator's
+"front-matter says so, the section must exist" rule.
+
+## The three artefacts
+
+Section numbers are per profile. The global profile uses sub-sections of existing
+sections (4.5, 4.6, 9.5) and the corporate profile uses 2.1, 2.3 and 5.N+4; no
+new top-level section is introduced in either, because section numbers are quoted
+in 172 places and renumbering them to add a mode is a worse trade than nesting.
+
+### 1. Current behaviour
+
+Every behaviour v1 has that a reader could otherwise only find by reading v1.
+One row per behaviour, with a stable `CB-<slug>-NN` id and a `repo/file:line`
+citation.
+
+| Column | Contract |
+|---|---|
+| Id | `CB-<slug>-NN`, `<slug>` the same feature slug the `BR-` ids use |
+| Behaviour | one sentence, present tense, no v2 language |
+| Evidence | `<repo>/<path>:<line>`, or the evidence label when no line can be named |
+| Certainty | `confirmed` or `uncertain` |
+
+`Evidence` and `Certainty` are **derived by the renderer** from
+`state.analysisSpec.evidence.repoEvidence`, never asked of the author and never
+written by the model from its own impression. A `direct-match` or `same-domain`
+hit yields `confirmed` with its path and line; a `cross-cutting` hit yields
+`uncertain` with the module name. Letting the writer grade its own evidence is
+the failure Locked 24 already refuses for the concept table, and it is the same
+failure here.
+
+### 2. Endpoint mapping
+
+The v1 call and the v2 call side by side, one row per endpoint, plus what
+changed in the shape. A redesign that keeps the same paths still gets the table,
+with the rows saying so: "unchanged" is an answer, and its absence is not.
+
+### 3. Difference list
+
+Where each v1 behaviour went. One row per `CB-` id, and the status comes from a
+closed five-value vocabulary:
+
+| Status | Meaning |
+|---|---|
+| `Moved` | v2 keeps the behaviour, in a different place; the row names where |
+| `Partial` | v2 keeps part of it; the row names what is dropped |
+| `Missing` | v2 does not have it, and nobody has decided that yet |
+| `New` | v2 behaviour with no v1 counterpart |
+| `Out of scope` | deliberately dropped, with the decision recorded |
+
+The cell is bilingual in the same shape Section 20 uses for `Açık / Open`, so a
+Turkish document reads as Turkish while the machine-checked half stays a fixed
+English token.
+
+`Missing` and `Partial` are the two that mean work is unfinished, so each owes a
+Section 20 row by `AS-NN`. That is the reason the mode exists: a behaviour that
+v2 drops without a decision is exactly the thing that gets found in production.
+
+## The eight checks
+
+All in `validate-analysis-doc.mjs`, all live only when the front-matter says
+`redesign: true`.
+
+| Check | Severity | What it catches |
+|---|---|---|
+| the three sections exist | ERROR | Without the sections the row checks below pass over nothing, which is the defect that shows a gate green |
+| a row has no `file:line` and is not marked `uncertain` | ERROR | An unmarked guess. Prose can only ask an author to mark it; this finds the row that was not marked |
+| evidence is `cross-cutting` only, yet `confirmed` | WARN | A legitimate rule in a shared module reads this way, so it must not block - but Phase 4 runs `--strict`, so it blocks in review |
+| a status value outside the vocabulary | ERROR | A controlled vocabulary decaying into free text |
+| a `Missing` or `Partial` row with no Section 20 counterpart | ERROR | The reason the mode exists |
+| a `CB-` id in one table and not the other, both directions | ERROR | A behaviour that is in the code and on nobody's difference list: the thing that disappears in a redesign and is found in production |
+| the endpoint table's column count, then a half-written row | ERROR | A renderer that adds a column silently disabling the row checks |
+| the sections are present but the front-matter does not say `redesign` | WARN | Drift |
+
+## The cache, and the silent failure to avoid
+
+`evidence_digest` (Locked 27) summarises `featureName || platforms ||
+repoEvidence || conventions`, with a 24-hour TTL. `options.redesign` **is a
+digest input**. Without it, a redesign started within a day of a normal run on
+the same feature hits that run's cache, skips Phase 1b entirely, and renders a
+redesign document whose current-behaviour table is empty - at which point all
+eight checks above pass over nothing. This is the most likely quiet failure in
+the whole mode, and one digest input is the whole fix.

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

@@ -191,8 +191,13 @@ Outputs:
       https://{CONFLUENCE_HOST}/pages/viewpage.action?pageId=...    (Android)
       https://{CONFLUENCE_HOST}/pages/viewpage.action?pageId=...    (Backend)
   - Jira: {JIRA_KEY}-12345 (description updated with 3 platform sections)
+
+Provenance:
+  evidence_digest: sha256:1f3a9c2   base_commit: 4c1b2de
 ```
 
+**Provenance line.** Print the front-matter's `evidence_digest` and `base_commit` in the report too. A timestamp cannot separate two reports made the same day; these two say which side moved.
+
 **Stop. Do not chain into a dev run. Do not open a worktree. Do not create a branch.**
 
 **Open-question follow-up**: when any rendered file's Section 20 (Risks and Open Questions) has rows with status `Acik / Open`, append one line to the report: `<localized: "Section 20 has <N> open rows. Run /multi-agent:analysis-resolve to resolve them interactively before dispatching to dev.">`. This is a suggestion line only - never auto-invoke the resolver.

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

@@ -71,6 +71,7 @@ For each open row in source order:
 1. **Sibling propagation** (only if front-matter `siblings[]` is non-empty AND at least one resolved row's question text appears verbatim with an open status in a sibling file on disk): one AskUserQuestion, `header: "Siblings"`, question `<localized: "N resolved rows also appear open in sibling file(s) <list>. Apply the same resolutions there?">`, options `Apply to all listed` / `Skip siblings`. On apply: repeat the Phase 2 apply step per matching row per sibling, then give each touched sibling its own changelog row. Platform-specific classes (`convention-fallback`, `reuse-vs-new`) are excluded from matching (New Locked 9).
 2. **Changelog**: append one row to the Changelog section of every touched file: next version (integer scheme `v1 -> v2`; dotted scheme bumps the minor), today's date, author `analysis-resolve`, change `Resolved <N> of <M> Section 20 rows; <K> deferred`.
 3. **Punctuation gate**: run the Locked 7 verification grep over every touched file; fix any hit before reporting.
+3b. **Closure**: when a touched file has zero rows left at `Acik / Open` or `Girdi bekleniyor / Pending input` AND no `AS-NN` survives in its body, ask once per file - `header: "Publish"`, question `<localized: "<file> has no open questions left. Mark it status: final?">`, options `Mark final` / `Keep as draft`. On `Mark final`, set front-matter `status: final`; otherwise leave the key alone. Never flip it without the answer: `final` is a publication claim, and this command is built on one question per decision. `status: final` with anything still open is an ERROR in `validate-analysis-doc.mjs`, so the flip is what makes the closure gate real rather than advisory. Nothing flips back to `draft` here - reopening a question is a new run's decision.
 4. **Report** (in `outputLanguage`, max 12 lines): doc path(s) + new version, counts (resolved / deferred / follow-ups created / still open), `design-gap` rows that need a `/multi-agent:analysis` re-run (list inputs to re-supply), and - if open rows remain - a reminder that re-running this command resumes where it left off (state is the doc itself; no separate state file).
 
 **Stop. No commit, no branch, no dispatch.** The user reviews the diff and commits manually (Locked 6).