@mmerterden/multi-agent-pipeline 14.1.1 → 14.2.2

package/pipeline/multi-agent-refs/payload-contracts.md

@@ -0,0 +1,67 @@
+---
+description: "Canonical required-reading list for outward-facing payloads (PR body, Jira comment, closing report) plus the markup dialect per surface. Loaded by every mode that runs Phase 6 or Phase 7."
+---
+
+# Outward-facing payload contracts
+
+> Every mode that opens a PR, comments on a tracker, or closes out a run reads this file first. It does not restate the contracts  -  it names them, so no mode has to carry its own copy and drift from the others.
+
+## Read before Phase 6
+
+| Read | Before | Governs |
+|---|---|---|
+| [`channels/pr.md`]($HOME/.claude/multi-agent-refs/channels/pr.md) | assembling the PR body | fixed section set (`summary` → `changes` → `architecture` cond. → `verification` → `dependencies` cond. → `related`), Markdown-only rule, reviewer-preserving Bitbucket PUT payload |
+| [`phases/phase-6-commit.md`]($HOME/.claude/multi-agent-refs/phases/phase-6-commit.md) | committing | commit convention, default-reviewer fetch, draft/ready prompt, push-must-succeed loop |
+| [`rules.md`]($HOME/.claude/multi-agent-refs/rules.md) "External System Outputs" | any REST payload | real newlines, no HTML entities, no hand-rolled JSON, markup dialect per surface |
+
+## Read before Phase 7
+
+| Read | Before | Governs |
+|---|---|---|
+| [`channels/jira.md`]($HOME/.claude/multi-agent-refs/channels/jira.md) | posting the Jira comment | fixed section set incl. **Test Scenarios** (Given/When/Then, always present), markdown→wiki conversion table |
+| [`channels/confluence.md`]($HOME/.claude/multi-agent-refs/channels/confluence.md) | writing a Confluence page | storage-format conversion, endpoint flavor |
+| [`phases/phase-7-report.md`]($HOME/.claude/multi-agent-refs/phases/phase-7-report.md) | closing out | Timeline + Agent Activity + Cost Breakdown tables, missing-telemetry disclosure |
+| [`tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md) | every phase boundary | per-phase token narration, completion tile suffix |
+
+## Markup dialect per surface
+
+Language is not the only axis an external payload has. Every surface also has a markup dialect, and they are not interchangeable  -  the same body shipped to the wrong dialect renders as visible garbage, not as a slightly-off style.
+
+| Surface | Dialect | Converter | Section set owned by |
+|---|---|---|---|
+| PR description (GitHub / Bitbucket / GitLab) | **Markdown**, no conversion | none  -  post the assembled markdown verbatim | `channels/pr.md` |
+| GitHub issue body + comment | **Markdown**, no conversion | none | `channels/issue-comment.md` |
+| Jira comment + issue description | **Jira wiki markup** | the table in `channels/jira.md`, applied by the model  -  no program exists | `channels/jira.md` |
+| Confluence page body | **storage format** (XHTML) | `lib/md2confluence-v3.py` | `channels/confluence.md` |
+| Wiki pages (`.md` files in a git repo) | **Markdown** | none | `channels/wiki.md` |
+| Commit message | plain text | none | `rules/git-conventions.md` |
+
+Assemble every body once in Markdown, then convert **only** on the branches that require it. The recurring defect is the reverse: the Jira wiki table is the only text-markup table in the doc set, so it reads like the default and gets applied to a PR body. In a Markdown target, `h2. Title` renders as literal text, `{{identifier}}` keeps its braces, `#` starts an H1 instead of a numbered list, and `*bold*` comes out italic. In a Jira target the mirror-image failure applies: `## Heading` and `**bold**` render literally.
+
+A payload that is in the right language but the wrong dialect is a defect of the same severity as one that never posted. Both need a fix, not a follow-up ticket.
+
+## Closing report (required)
+
+The run ends with the phase tracker glyph block **and** the numbers behind it  -  per-phase duration and token spend, plus totals.
+
+- Record spend as you go: `phase-tracker.sh tokens <N> <in> <out> [cached]` after **every** LLM call, including each Phase 4 reviewer subagent and each Phase 3 chunk. Counts are additive and nothing reconstructs them after the fact.
+- Tag the model once per phase (`phase-tracker.sh model <N> <name>`) or the cost helper cannot price it and prints `-`.
+- Durations come from the phase timestamps and survive a missed `tokens` call; token spend does not.
+- If any phase has no token data, name those phases and say their cost is unavailable. Never print a report whose cost section is simply absent  -  the reader cannot tell "cheap run" from "nobody recorded it".
+
+### Missing-telemetry disclosure (Phase 7, required)
+
+Before composing the report, compute which phases carry no token data:
+
+```bash
+STATE="$HOME/.claude/logs/multi-agent/$TASK_ID/tracker-state.json"
+UNTRACKED=$(jq -r '[.phases[] | select((.tokens_in // 0) + (.tokens_out // 0) == 0) | .id] | join(", ")' "$STATE")
+```
+
+Non-empty `UNTRACKED` → both the agent-log report and the closing chat summary carry one line in `outputLanguage` naming those phase ids as cost-unavailable. Durations come from the phase timestamps and are reported either way.
+
+`smoke-tracker-tokens-invocation.sh` only lints that the phase docs *mention* `phase-tracker.sh tokens`. It cannot observe a run that read the doc and skipped the call, so this run-time disclosure is the only thing between a dropped `tokens` call and an invisible failure.
+
+## Fast modes are not exempt
+
+`--dev`, `--dev --local`, and the autopilot variants skip Analysis, Planning, and the interactive test gate. They run Phase 6 and Phase 7 **unchanged**. A short pipeline is not a licence for an improvised payload shape, a missing Test Scenarios section, or a report without numbers.

package/pipeline/multi-agent-refs/phases/modes.md

@@ -105,6 +105,26 @@ No separate task breakdown  -  the agent handles scope autonomously.
 
 **Combinable with autopilot**: `--dev autopilot` = fastest path. Init -> Dev -> Review (auto-fix) -> auto-commit -> auto-PR -> Report (Phase 5 skipped). Zero user interaction (except build failures after 3 retries, and review findings that survive 3 rework cycles).
 
+### Intake warnings shared by the whole `--dev` family
+
+These apply to `--dev`, `--dev autopilot`, `--dev local`, and `--dev local autopilot` alike. A mode entry doc may not carry its own copy  -  it points here.
+
+**An analysis document was supplied.** Because Phase 1 and Phase 2 are skipped, no phase turns that document into a task breakdown. The doc becomes raw context for one Dev pass, and work comes out ordered by whatever the model read first: the bottom of the dependency chain lands, the screen wiring does not.
+
+Say so before starting, once, and offer the choice:
+
+```
+This mode skips Analysis and Planning, so the analysis document will not be turned
+into a task breakdown. For analysis-driven screen work, /multi-agent or
+/multi-agent:local run both phases.
+  1. Continue with --dev (doc as context only)
+  2. Switch to the full pipeline
+```
+
+Autopilot picks 1 and logs the warning rather than asking.
+
+**The branch already carries the work.** When the change was developed outside the pipeline, or by hand, the `--dev` family is the wrong entry point: it will try to develop again. `/multi-agent:ship` puts the existing diff through the same review, adds a build+test success gate, opens the PR, and posts the Jira technical-analysis + test-scenario comment  -  without re-developing. Offer it when the working tree or branch is already ahead of the base with the task's changes.
+
 ---
 
 ## Local Mode (`--local`)

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

@@ -35,7 +35,7 @@ Read preferences: `PREFS_FILE="$HOME/.claude/multi-agent-preferences.json"` (if
 OUTPUT_LANG=$(jq -r '.global.outputLanguage // "en"' "$PREFS_FILE" 2>/dev/null || echo en)
 ```
 
-From this point on, every assistant-authored conversational line (status updates, findings, phase headers, summaries, error explanations) renders in `$OUTPUT_LANG`. `AskUserQuestion` payloads stay English. External payloads stay English. See `$HOME/.claude/multi-agent-refs/rules.md` "Language Application" for the full contract. Skipping this step is the failure mode where the user sees an English wall of text in a Turkish session.
+From this point on, everything the user reads renders in `$OUTPUT_LANG`: conversational lines, `AskUserQuestion` `question`/`description`, and external payload bodies (PR/Jira/Confluence). English stays only on `label`/`header`, commit messages, branch names, PR titles, identifiers. Full matrix: `rules.md` "Language Application". Skipping this step is why a Turkish session gets an English wall of text  -  or an English picker.
 
 **Model fallback date gate** (same step, once per run): read `prefs.global.modelFallback`. If `premiumTierUntil` is set and in the past, apply the date-gate trigger from `$HOME/.claude/multi-agent-refs/features/model-fallback.md` - `preferredModel` personas dispatch on `fallbackModel` for this run, with the one-line WARN. Dispatch-error and budget triggers in that contract apply per-dispatch later; nothing else to do here.
 
@@ -406,7 +406,7 @@ git -C $PROJECT_ROOT config user.email "{identity.email}"
 
 `worktreePath` = `$PROJECT_ROOT`, `localMode` = `true`.
 
-**If normal mode** (worktree  -  default): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. **Heal stale admin state first** (see "Worktree stale-lock heal" below) and **apply the residue guard** (see "Worktree residue guard" below), then `git -C $PROJECT_ROOT worktree add {path} -b {branch} origin/{baseBranch}` (if exists: enter, pull) 4. Set identity: `git -C {worktree-path} config user.name/email` 5. Create log dir + `agent-log.md` + `agent-state.json`:
+**If normal mode** (worktree  -  default): 2. Worktree path: Jira → `.worktrees/{jiraId}/`, GitHub → `.worktrees/GH{issueNo}/`, free-text → `.worktrees/task-{shortId}/` 3. **Heal stale admin state first** (see "Worktree stale-lock heal" below) and **apply the residue guard** (see "Worktree residue guard" below), then `git -C $PROJECT_ROOT worktree add {path} -b {branch} origin/{baseBranch}` (if exists: enter, pull) 4. Set identity: `git -C {worktree-path} config user.name/email` 5. Create log dir + `agent-log.md` + `agent-state.json` at `$HOME/.claude/logs/multi-agent/{project}/{task-id}/`, never inside the worktree:
 
 **Worktree stale-lock heal (required before every `worktree add`):** a run killed mid-`worktree add` (OOM, SIGTERM, disk full) leaves a locked or broken admin entry under `.git/worktrees/{id}/`, so the retry fails with `fatal: '<path>' already exists`. Always run the heal first  -  it is a no-op on a clean repo:
 

package/pipeline/multi-agent-refs/phases/phase-6-commit.md

@@ -106,6 +106,8 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
 
 #### Step 3  -  PR Description (technical detail for reviewers)
 
+**Section set + markup dialect: `channels/pr.md`  -  read it first.** Phase 7 channels replaces this body with that section set, so build to it. Required reading: `payload-contracts.md`.
+
 Generate a structured PR description based on task type. The PR body targets **code reviewers**  -  it should be technical: what changed, why, architecture decisions, how to verify.
 
 **required**: Run all generated text (PR body, commit message) through the `humanizer` skill before posting. This removes AI-generated patterns (inflated language, filler phrases, repetitive structure) and makes the output sound like a developer wrote it.
@@ -116,49 +118,15 @@ Generate a structured PR description based on task type. The PR body targets **c
 - Bitbucket: similar patterns
 - Use `Ref: #N`, `Related: #N`, or `See: {jiraId}` instead
 
-**Default Reviewers**: If `prefs.projects[{project}].defaultReviewers` exists, add `--reviewer` flags. If not, ask on first PR and save to preferences:
-
-```
-Default reviewers for this project? (comma-separated GitHub usernames, or skip):
-```
-
-Save to `prefs.projects[{project}].defaultReviewers: ["user1", "user2", "user3", "user4"]`
+**Default Reviewers**: use `prefs.projects[{project}].defaultReviewers` when set; otherwise ask once ("Default reviewers for this project? comma-separated, or skip") and persist the answer there. Per-remote resolution rules are in "Default reviewers (required on every PR)" below  -  this is the prefs half only.
 
-**Standard PR (bug fix, feature, refactor):**
+**Standard PR (bug fix, feature, refactor)**  -  invocation shape; body comes from a file so newlines survive:
 
 ```bash
 REVIEWERS=$(jq -r '.projects["'$PROJECT'"].defaultReviewers // [] | map("--reviewer " + .) | join(" ")' "$PREFS_FILE")
 gh pr create --base {baseBranch} --head {branch} $REVIEWERS \
   --title "{type}({scope}): {summary} [{jiraId}]" \
-  --body "$(cat <<'EOF'
-## Summary
-{1-3 bullet points: what changed and why}
-
-## Jira
-{jiraId}  -  {jira summary or link}
-
-## Technical Details
-### Changes
-{For each changed file group, explain WHAT changed and WHY}
-
-### Architecture
-{Any structural decisions: new files, moved code, pattern changes}
-
-### Dependencies
-{New imports, framework changes, package updates  -  or "None"}
-
-## How to Test
-1. {Step-by-step manual test instructions}
-2. {Verify specific behavior}
-
-## Checklist
-- [ ] Build passes (0 errors, 0 warnings)
-- [ ] Tests pass
-- [ ] No hardcoded values (tokens used)
-- [ ] Accessibility verified
-- [ ] Dark mode verified
-EOF
-)"
+  --body-file /tmp/pr-body-$TASK_ID.md
 ```
 
 **UI Component PR (when SwiftUI component detected):**
@@ -175,9 +143,9 @@ Same `gh pr create` pattern with component-specific body sections:
 
 CRITICAL: PR description **MUST** preserve real newlines. Never embed `\n` literally  -  Bitbucket saves it verbatim. Never use HTML entities. Pattern: heredoc → `jq --rawfile` → `curl --data-binary @file`.
 
-Required payload fields: `title`, `description` (via rawfile), `fromRef` (id + repo slug + project key), `toRef` (same structure), `state: "OPEN"`, `open: true`, `closed: false`, `locked: false`, `reviewers: []`.
+Required payload fields: `title`, `description` (via rawfile), `fromRef` (id + repo slug + project key), `toRef` (same structure), `state: "OPEN"`, `open: true`, `closed: false`, `locked: false`, `reviewers` (the fetched list  -  `[]` only if that endpoint really returned empty).
 
-To **update** an existing PR: fetch `version`, PUT with same rawfile pattern (version +1). GitHub: prefer `--body-file` over inline `--body`.
+To **update** an existing PR: use the `channels/pr.md` PUT payload  -  required, not illustrative. It carries `reviewers`/`fromRef`/`toRef`/`draft` (a PUT clears omitted fields) and the GET's `version` unmodified (`version + 1` → 409). Refetch after, assert the reviewer count held. GitHub: `--body-file`.
 
 **Default reviewers (required on every PR)**
 
@@ -307,7 +275,7 @@ update_sibling_links "${PR_URLS[@]}"
 
 **Then finalize each repo's worktree**, serially and only now  -  `update_sibling_links` updates one PR per repo and the loop `cd`s per repo, so removing repo 1's worktree mid-loop breaks 2..N. Run `worktree-finalize.sh` once per repo with that repo's `--worktree` / `--project-root` / `--project`; each skips or removes independently.
 
-`update_sibling_links` does an UPDATE call per PR (Bitbucket: PUT with `version+1`; GitHub: `gh pr edit --body-file`). Idempotent: re-running with the same set is a no-op.
+`update_sibling_links` does an UPDATE call per PR (Bitbucket: the `channels/pr.md` PUT payload, current `version`; GitHub: `gh pr edit --body-file`). Idempotent.
 
 ##### GitHub issue body  -  list all PRs
 

package/pipeline/multi-agent-refs/phases/phase-7-report.md

@@ -153,8 +153,8 @@ Skipped sections: when `planTodos.enabled` is false or no `plan.todos[]` was emi
 
 ## Timeline
 
-| #   | Phase | Model | Duration | Status | Detail |
-| --- | ----- | ----- | -------- | ------ | ------ |
+| #   | Phase | Agent | Model | Duration | Tokens (in/out) | Status | Detail |
+| --- | ----- | ----- | ----- | -------- | --------------- | ------ | ------ |
 
 ## Agent Activity Report
 
@@ -200,7 +200,7 @@ $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 7 task.completed \
 
 **Per-run outcome metrics (evidence corpus):** also emit `run-metrics.mjs --state <agent-state.json>` and append/persist its JSON. It records the numbers that actually answer "did this run go well" - review iterations (rework loops), first-pass-clean, reviewer signal-to-noise (accepted / raw findings), consensus verdict, build outcome. Accumulating these across real runs is the real-world validation that golden tasks + benchmarks only approximate; keep the corpus so the pipeline's quality can be measured, not asserted.
 
-**Cost Breakdown emission (mandatory):** as part of agent-log compose, append the per-task cost block produced by `render-agent-log-cost.sh`. Best-effort  -  exit 2 (no tracker data) silently skipped:
+**Cost Breakdown emission (mandatory):** as part of agent-log compose, append the per-task cost block produced by `render-agent-log-cost.sh`:
 
 ```bash
 COST_BLOCK=$(bash $HOME/.claude/scripts/render-agent-log-cost.sh "$TASK_ID" 2>/dev/null) && \
@@ -209,6 +209,8 @@ COST_BLOCK=$(bash $HOME/.claude/scripts/render-agent-log-cost.sh "$TASK_ID" 2>/d
 
 This is independent of the channels-side `reportContent.costSummary` (which gates the PR-body Cost Summary). agent-log always carries the breakdown when telemetry is present.
 
+**Missing-telemetry disclosure (required).** Name untracked phase ids as cost-unavailable in the report and closing summary. Mechanic: `payload-contracts.md`.
+
 **Triage memory ingest (mandatory):** after Phase 4 produces a final triage output, persist the accepted/deferred/rejected rows into the per-repo triage corpus so Phase 1 enrichment and Phase 4 prior-art lookup can recall them on future tasks. Idempotent  -  re-running on the same task writes 0 rows.
 
 ```bash

package/pipeline/multi-agent-refs/phases.md

@@ -63,6 +63,12 @@ $HOME/.claude/scripts/phase-tracker.sh update <N> failed         # phase failed
 $HOME/.claude/scripts/phase-tracker.sh update <N> skipped        # --dev mode etc.
 ```
 
+After every LLM call (counts are additive; skipping this is why runs end with durations but no cost  -  nothing reconstructs spend afterwards):
+
+```bash
+$HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
+```
+
 For sub-phase progress (e.g. Phase 1's parallel Explore agents, Phase 4's reviewer dispatch + triage + validator gate, Phase 6's commit + push + PR sub-steps):
 
 ```bash

package/pipeline/multi-agent-refs/rules.md

@@ -122,6 +122,8 @@ This is the single source of truth. When a contributor or model is unsure where
 
 4. **Terminal output, log lines, and `echo`/`printf` calls** also use real newlines  -  never `\n` literals. For multi-line messages, prefer heredoc.
 
+5. **Markup dialect is a second axis beyond language.** Markdown: PR body, GitHub issue, wiki files. Jira: wiki markup. Confluence: storage format. Wrong dialect renders literally. Table: `payload-contracts.md`.
+
 ## Issue Management
 
 - **NEVER auto-close** GitHub issues or Jira tickets. Closure requires team review (configurable, typically 4 approvals).

package/pipeline/schemas/prefs.schema.json

@@ -184,7 +184,7 @@
             },
             "appstore_connect_key_id": {
               "type": ["string", "null"],
-              "description": "App Store Connect API key ID. Tier 1 of the App Store Connect access chain, used by /multi-agent:testflight-validation Gate 2. An identifier rather than a secret; mapped anyway so every credential is read through the same layer. Creating an API key needs an Admin or App Manager role, which is why Tier 2 exists."
+              "description": "App Store Connect API key ID. Tier 1 of the App Store Connect access chain, used by /multi-agent:store-ready Gate 2 (and its iOS alias /multi-agent:testflight-validation). An identifier rather than a secret; mapped anyway so every credential is read through the same layer. Creating an API key needs an Admin or App Manager role, which is why Tier 2 exists."
             },
             "appstore_connect_issuer_id": {
               "type": ["string", "null"],
@@ -670,7 +670,7 @@
           "type": "string",
           "enum": ["en", "tr"],
           "default": "en",
-          "description": "Language used for user-facing INTERACTIVE pipeline copy: pickers (account, project, dev-context, base branch, branch name, maturity ack, channels), Phase 5 test prompt, Phase 6 local-checkout prompt, Phase 6 commit/PR confirmations, TaskCreate card subjects, and phase-banner.sh headers (`PHASE_LANG` resolves from this field via the `auto` sentinel). Canonical label table lives in `pipeline/skills/shared/multi-agent/SKILL.md`. External payloads stay English regardless of this setting: reviewer/triage system prompts, commit messages, PR titles/bodies, Jira comments, wiki content, agent-log.md payloads. Set via `/multi-agent:language prompt <en|tr>` or answered on first run by `/multi-agent:setup`."
+          "description": "Locked to 'en': the language of LLM-facing instructions (spec files, agent system prompts, reviewer/triage prompts) and picker structural chrome (AskUserQuestion label/header). What humans read is governed by outputLanguage instead - picker question/description, conversational lines, and external payload bodies (PR description, Jira comment, Confluence/Wiki). Always English regardless of either pref: commit messages, branch names, PR titles, code identifiers, agent-log.md. Canonical matrix: multi-agent-refs/rules.md 'Language Application'. Set via /multi-agent:language or /multi-agent:setup."
         },
         "outputLanguage": {
           "type": "string",

package/pipeline/scripts/audit-log-rotate.sh

@@ -80,6 +80,16 @@ if [ -s "$AUDIT_FILE" ]; then
   if [ -f "$ROTATED" ] && command -v gzip >/dev/null 2>&1; then
     gzip -f "$ROTATED" 2>/dev/null || true
   fi
+
+  # gzip preserves the source file's mtime by default, so an archive rotated
+  # from log content already older than KEEP_DAYS would carry that same old
+  # mtime - and the retention sweep below deletes anything past KEEP_DAYS,
+  # so a just-created archive could be purged in this very run before ever
+  # being read. Retention has to count from rotation time, not from the age
+  # of the content it archived. gzip -f removes the plain file on success, so
+  # only touch whichever of the two actually exists.
+  [ -f "$ROTATED.gz" ] && touch "$ROTATED.gz"
+  [ -f "$ROTATED" ] && touch "$ROTATED"
 fi
 
 # Drop archives older than KEEP_DAYS

package/pipeline/scripts/build-stack-plugins.mjs

@@ -61,6 +61,7 @@ const COMMON_SKILLS = [
   "agent-introspection-debugging",
   "skill-creator",
   "backlog",
+  "localization-reuse-map",
 ];
 
 // Apple/Xcode-only skills that match no stack pattern → iOS plugin only.
@@ -134,7 +135,13 @@ function treeFingerprint(dir) {
 // --- 1. enumerate authoring source ---------------------------------------
 if (!existsSync(EXTERNAL)) {
   console.error(`source not found: ${EXTERNAL}`);
-  process.exit(0);
+  // --check-routing exists so CI can gate routing correctness without a
+  // checkout of the plugins repo, reading only this authoring source. Exiting
+  // 0 here regardless of --check-routing meant a misconfigured/missing
+  // source (wrong --pipeline path, an incomplete CI checkout) reported the
+  // gate as passing having audited nothing - the exact silent-green failure
+  // the gate exists to prevent elsewhere.
+  process.exit(args.includes("--check-routing") ? 1 : 0);
 }
 const allSkills = listDirs(EXTERNAL);
 

package/pipeline/scripts/check-derived-drift.mjs

@@ -38,6 +38,18 @@ const CACHE = process.env.DERIVED_DRIFT_CACHE || join(homedir(), ".claude", "plu
 
 const expandHome = (p) => p.replace(/^\$HOME\b|^~/, homedir());
 
+// Array.prototype.sort() with no comparator sorts these lexicographically
+// ("10.0.0" < "9.0.0" as strings), so a directory listing with both would
+// treat 9.0.0 as newer.
+function semverCompare(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] - pb[i];
+  }
+  return 0;
+}
+
 function readJson(path) {
   try {
     return JSON.parse(readFileSync(path, "utf-8"));
@@ -116,7 +128,7 @@ function fromCache(entry) {
   if (!existsSync(dir)) return null;
   const versions = readdirSync(dir)
     .filter((d) => /^\d+\.\d+\.\d+$/.test(d))
-    .sort();
+    .sort(semverCompare);
   const newest = versions[versions.length - 1];
   return newest
     ? { version: newest, source: "plugin cache", authoritative: false, behind: null }

package/pipeline/scripts/diff-explain.mjs

@@ -117,6 +117,44 @@ function resolveBase() {
   die("no base ref found (tried origin/main, main, origin/master, master)  -  pass --base");
 }
 
+// git quotes a `diff --git` path (core.quotePath, on by default) whenever it
+// has a non-ASCII byte or other unusual character - e.g. a Turkish filename
+// renders as `diff --git "a/\303\226deme.swift" "b/\303\226deme.swift"`, not
+// the bare a/...b/... form. The plain regex this replaced never matched that
+// line at all, so every non-ASCII-named file dropped out of the explanation.
+const DIFF_GIT_QUOTED_RE = /^diff --git "a\/((?:[^"\\]|\\.)*)" "b\/((?:[^"\\]|\\.)*)"$/;
+const DIFF_GIT_UNQUOTED_RE = /^diff --git a\/(.+?) b\/(.+)$/;
+
+function unquoteGitPath(s) {
+  const bytes = [];
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "\\") {
+      const octal = s.slice(i + 1, i + 4);
+      if (/^[0-7]{3}$/.test(octal)) {
+        bytes.push(parseInt(octal, 8));
+        i += 3;
+        continue;
+      }
+      const simple = { "\\": 92, '"': 34, t: 9, n: 10, r: 13 };
+      const next = s[i + 1];
+      if (next in simple) {
+        bytes.push(simple[next]);
+        i += 1;
+        continue;
+      }
+    }
+    bytes.push(s.charCodeAt(i));
+  }
+  return Buffer.from(bytes).toString("utf-8");
+}
+
+function matchDiffGitHeader(line) {
+  const q = line.match(DIFF_GIT_QUOTED_RE);
+  if (q) return unquoteGitPath(q[2]);
+  const u = line.match(DIFF_GIT_UNQUOTED_RE);
+  return u ? u[2] : null;
+}
+
 /**
  * Parse unified diff into a map of {path: [{ oldStart, newStart, lines: [...] }]}
  * Each hunk's `lines` retains the leading +/- /space prefix.
@@ -127,9 +165,9 @@ function parseDiff(raw) {
   let currentHunks = null;
   let currentHunk = null;
   for (const line of raw.split("\n")) {
-    const fileMatch = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
-    if (fileMatch) {
-      currentPath = fileMatch[2];
+    const fileMatch = matchDiffGitHeader(line);
+    if (fileMatch !== null) {
+      currentPath = fileMatch;
       currentHunks = [];
       files[currentPath] = currentHunks;
       currentHunk = null;

package/pipeline/scripts/diff-risk-score.mjs

@@ -104,9 +104,9 @@ function loadNumstat() {
     const map = new Map();
     let cur = null;
     for (const line of text.split("\n")) {
-      const m = line.match(/^diff --git a\/(.+?) b\/(.+)$/);
-      if (m) {
-        cur = m[2];
+      const p = matchDiffGitHeader(line);
+      if (p !== null) {
+        cur = p;
         if (!map.has(cur)) map.set(cur, { added: 0, removed: 0 });
         continue;
       }
@@ -122,7 +122,7 @@ function loadNumstat() {
   return out.split("\n").map((line) => {
     const [a, r, ...rest] = line.split("\t");
     return {
-      path: rest.join("\t"),
+      path: unquotePathIfNeeded(rest.join("\t")),
       added: a === "-" ? 0 : Number(a) || 0,
       removed: r === "-" ? 0 : Number(r) || 0,
     };
@@ -162,6 +162,60 @@ const TEST_PATH_GLOBS = [
   /\.spec\.(ts|tsx|js|mjs|py)$/i,
 ];
 
+// git quotes a path in a `diff --git` header (core.quotePath, on by default)
+// whenever it contains a non-ASCII byte or other unusual character -
+// "diff --git \"a/\\303\\226deme.swift\" \"b/\\303\\226deme.swift\"" for a
+// Turkish filename, not the bare `a/`/`b/` form. `/^diff --git a\/(.+?)
+// b\/(.+)$/` doesn't match a line starting with a quote at all, so every
+// non-ASCII-named file was silently dropped from risk scoring.
+const DIFF_GIT_QUOTED_RE = /^diff --git "a\/((?:[^"\\]|\\.)*)" "b\/((?:[^"\\]|\\.)*)"$/;
+const DIFF_GIT_UNQUOTED_RE = /^diff --git a\/(.+?) b\/(.+)$/;
+
+// Reverse git's C-style quoting: octal byte escapes (\NNN, one per raw byte -
+// a multi-byte UTF-8 character is several consecutive \NNN triplets) plus
+// the standard \\ \" \t \n \r escapes.
+function unquoteGitPath(s) {
+  const bytes = [];
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "\\") {
+      const octal = s.slice(i + 1, i + 4);
+      if (/^[0-7]{3}$/.test(octal)) {
+        bytes.push(parseInt(octal, 8));
+        i += 3;
+        continue;
+      }
+      const simple = { "\\": 92, '"': 34, t: 9, n: 10, r: 13 };
+      const next = s[i + 1];
+      if (next in simple) {
+        bytes.push(simple[next]);
+        i += 1;
+        continue;
+      }
+    }
+    bytes.push(s.charCodeAt(i));
+  }
+  return Buffer.from(bytes).toString("utf-8");
+}
+
+// `git diff --numstat` quotes a non-ASCII/unusual path the same C-style way
+// as the `diff --git` header line (e.g. `"\303\226deme.swift"`), just
+// without the surrounding "diff --git a/...b/..." context to detect it by.
+function unquotePathIfNeeded(s) {
+  if (s.length >= 2 && s[0] === '"' && s[s.length - 1] === '"') {
+    return unquoteGitPath(s.slice(1, -1));
+  }
+  return s;
+}
+
+// Returns the b/-side path from a `diff --git` header line, or null if the
+// line isn't one. Handles both the quoted and unquoted forms.
+function matchDiffGitHeader(line) {
+  const q = line.match(DIFF_GIT_QUOTED_RE);
+  if (q) return unquoteGitPath(q[2]);
+  const u = line.match(DIFF_GIT_UNQUOTED_RE);
+  return u ? u[2] : null;
+}
+
 function matchesAny(path, regexes) {
   return regexes.some((r) => r.test(path));
 }
@@ -170,6 +224,16 @@ function isTestPath(path) {
   return matchesAny(path, TEST_PATH_GLOBS);
 }
 
+// pairedTestPaths only knows how to derive a test-file name for these
+// extensions; for anything else (README.md, package.json, .yaml configs,
+// lockfiles, ...) it falls back to the untouched filename as `base` with an
+// empty `ext`, producing candidates like "README.mdTests." that can never
+// match a real path. Gating no_test_change on this is what "source touched"
+// in the comment above actually means - without it, the signal fired on
+// every non-test file in a diff, README included, which made HIGH_STAKES in
+// review-scope.mjs unavoidable for almost any real-world diff.
+const PAIRABLE_SOURCE_EXT_RE = /\.(swift|kt|ts|tsx|js|mjs|py)$/;
+
 function pairedTestPaths(srcPath) {
   // Return likely test path candidates for a source file.
   const parts = srcPath.split("/");
@@ -189,9 +253,9 @@ function parseHunks(diffText) {
   const perFile = new Map();
   let cur = null;
   for (const line of diffText.split("\n")) {
-    const m = line.match(/^diff --git a\/(.+?) b\/(.+)$/);
-    if (m) {
-      cur = m[2];
+    const p = matchDiffGitHeader(line);
+    if (p !== null) {
+      cur = p;
       if (!perFile.has(cur)) perFile.set(cur, []);
       continue;
     }
@@ -271,7 +335,7 @@ function buildRow(stat, addedLines, allChangedPaths) {
   }
 
   // No-test-change: source touched + no matching test file in the changed set.
-  if (!isTestPath(path)) {
+  if (!isTestPath(path) && PAIRABLE_SOURCE_EXT_RE.test(path)) {
     const candidates = pairedTestPaths(path).map((c) => c.toLowerCase());
     const anyTest = allChangedPaths.some((p) => {
       if (!isTestPath(p)) return false;

package/pipeline/scripts/gen-mode-dispatch.mjs

@@ -145,7 +145,7 @@ bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
 bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
 
 # After every LLM call (every CLI):
-bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out>
+bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
 \`\`\`
 
 ### Visual channel  -  Claude Code (native TaskList widget, required)

package/pipeline/scripts/learning-curve.mjs

@@ -78,8 +78,14 @@ for (const e of events) {
   }
   if (e.ts && (!t.firstTs || e.ts < t.firstTs)) t.firstTs = e.ts;
   const d = e.details || {};
-  if (e.event === "review.completed" && d.review_cycles != null)
-    t.reviewCycles = num(d.review_cycles);
+  // phase-4-review.md's actual review.completed emission (raw_count=/
+  // accepted=/deferred=/rejected=/approved=/duration_ms=) carries no
+  // review_cycles field - that name only appears on Phase 7's task.completed
+  // summary event, which this never matched. Phase 4 re-runs (and logs its
+  // own review.completed) once per rework cycle, so the cycle count for a
+  // task is how many review.completed events share its task_id - the same
+  // derivation aggregate-metrics.mjs already uses for this metric.
+  if (e.event === "review.completed") t.reviewCycles = (t.reviewCycles ?? 0) + 1;
   if (e.event === "rework.started") t.rework += 1;
   t.tokensIn += num(d.tokens_in);
   t.tokensOut += num(d.tokens_out);

package/pipeline/scripts/output-quality-check.sh

@@ -80,11 +80,22 @@ if [ -f "$PR_BODY" ]; then
   else
     ok "PR body free of HTML entities"
   fi
-  for sec in "## Summary" "## How to Test"; do
-    grep -q "$sec" "$PR_BODY" \
-      && ok "PR body has '$sec' section" \
-      || warn "PR body missing '$sec' section"
+  # Canonical section set is channels/pr.md's: summary -> changes ->
+  # architecture (cond.) -> verification -> dependencies (cond.) -> related.
+  # Headings render in outputLanguage, so match the always-required three by
+  # either language rather than pinning English. "## How to Test" was the old
+  # phase-6 template's heading and is not part of the canonical set.
+  for sec in "Summary|Özet" "Changes|Değişiklikler" "Verification|Doğrulama"; do
+    label="${sec%%|*}"
+    grep -qE "^## ($sec)" "$PR_BODY" \
+      && ok "PR body has '$label' section" \
+      || warn "PR body missing '$label' section (canonical set: channels/pr.md)"
   done
+  if grep -qE '^h[1-6]\. |\{\{[A-Za-z_]' "$PR_BODY"; then
+    bad "PR body contains Jira wiki markup (h2./{{code}}) - PR bodies are Markdown"
+  else
+    ok "PR body free of Jira wiki markup"
+  fi
 else
   warn "no .pr-body.md in task dir (skipped PR-body check)"
 fi