@mmerterden/multi-agent-pipeline 20.33.0 → 20.34.0

package/pipeline/multi-agent-refs/channels/generator.md

@@ -0,0 +1,146 @@
+# Channels - Generator (Step 5 section bodies)
+
+> Loaded by `channels/SKILL.md` Step 5. The SKILL keeps the Jira-vs-PR body rule, the section-order rule and the target length rule; this file carries the content-option table, the aggregated output template, the store-compliance augmentation, and the work-summary and cost-summary generators. Read it before generating any section body.
+
+## Content options
+
+| Content option | Generated section |
+|---|---|
+| Normal analiz | `### Analysis`  -  impact summary from Phase 1, risks from Phase 4 (pipeline-log source, high-level only) |
+| Teknik analiz | `### Technical Details`  -  Changes (what/why per file group), Architecture (structural decisions, pattern changes), Dependencies (new imports/frameworks/packages). Source: Phase 1 planning + Phase 2 dev log + `git diff --stat`. **PR and Confluence only** - never rendered into a Jira comment. |
+| Test senaryoları | `### Test Scenarios`  -  precondition / steps / expected table (4-8 rows), user perspective |
+| Test Koşumu (Xray) | `### Test Koşumu`  -  Xray Test Execution of the task's UI scenario run (`channels/test-run.md`) |
+| Auto-diff | Old enrich Output Template verbatim  -  Root Cause / Solution / Changed Files / Test Scenarios |
+| Manuel not | `### Notes`  -  user-provided paragraph, or LLM-split into subsections if `--message` is plain text and long |
+| Cost özeti | `### Cost Summary`  -  per-phase token tally + est. USD table. Source: `phase-tracker.sh` phase status + optional OTel spans. See "Cost summary generation" below. |
+| Yapılan iş özeti | `### Work Summary`  -  executive one-screen summary: task + branch + base + PR, scope delivered (done/[pending] per Phase 2 task), changed files with +/- counts (capped at 20 rows), review outcome (accepted/deferred/rejected + approved), phase tick strip. Source: `agent-state.json` + `phase-tracker.json` + `git diff --numstat base...HEAD`. See "Work summary generation" below. |
+
+## Output template
+
+**Output template (aggregated across selected content options):**
+
+```markdown
+### Analysis                        ← if "Normal analiz" selected
+{impact summary, risks  -  from pipeline log, high-level}
+
+### Technical Details               ← if "Teknik analiz" selected
+#### Changes
+{Per changed-file-group, what changed + why  -  from Phase 2 dev log}
+#### Architecture
+{Structural decisions, pattern changes, new file layouts  -  from Phase 1 plan}
+#### Dependencies
+{New imports / frameworks / packages  -  from git diff --stat, or "None"}
+
+### Root Cause                      ← if "Auto-diff" selected
+{single paragraph  -  from diff}
+
+- `path/to/File.ext → funcName`: {why it broke}
+
+### Solution                        ← if "Auto-diff" selected
+- `path/to/File.ext:LINE-LINE`  -  {change, one line}
+
+### Changed Files                   ← if "Auto-diff" selected
+| File | +/- |
+|------|-----|
+| `path/to/File.ext` | +N / -M |
+
+### Test Scenarios                  ← if "Test senaryoları" OR "Auto-diff" selected
+**1. {what this scenario exercises}**
+1. {step the tester performs}
+2. **Expected:** {what they should see}
+
+**2. {regression scenario}**
+1. {step}
+2. **Expected:** {what should still behave as before}
+
+### Test Koşumu                     ← if "Test Koşumu (Xray)" selected
+
+### Notes                           ← if "Manuel not" selected
+{user message}
+
+### Work Summary                    ← if "Yapılan iş özeti" selected
+{executive scope + files + review + phases block  -  see "Work summary generation" below}
+
+### Cost Summary                    ← if "Cost özeti" selected
+{per-phase token + USD table  -  see "Cost summary generation" below}
+
+### Store compliance                ← auto-appended if cached compliance report exists
+{summary line  -  see below}
+
+Ref: {jiraId}
+```
+
+**Store compliance auto-augmentation:**
+
+After the content-selected sections are generated, check for a recent compliance report cached from `/multi-agent:test "store-ready"`:
+
+```bash
+# Cache locations (newest wins; expire after 6h to avoid stale cross-branch reports)
+find /tmp -maxdepth 1 -name 'archiveguard-*.json' -o -name 'play-compliance-*.json' \
+  -newermt "-6 hours" -print 2>/dev/null | head -1
+```
+
+If a cached report exists AND any of the selected channels is PR / Jira / Confluence, append an auto-summary section:
+
+| Blocker count | Appended line |
+|---|---|
+| `errors > 0` | `### Store compliance` + `{N} blocker(s), {M} warning(s)  -  run /multi-agent:test "store-ready" for the full report.`  -  per-blocker: `- \`{ruleID}\`  -  {Apple ITMS / Play ref}: {message}` (capped at 5 rows, rest collapsed to `+N more`) |
+| `errors == 0, warnings > 0` | `### Store compliance` + `[done] No blockers. {M} warning(s)  -  see /multi-agent:test "store-ready" for detail.` |
+| `errors == 0, warnings == 0` | Skip section entirely  -  don't pollute PR body |
+
+The section references `ruleID` + policy ref from the compliance skill catalogs (`apple-archive-compliance` / `google-play-compliance`) verbatim. No translation  -  global identifiers stay as-is.
+
+If no cached report exists, skip silently  -  this is augmentation, not a gate.
+
+**Work summary generation:**
+
+Emitted only when `reportContent.workSummary === true` and at least one of (`agent-state.json`, `--branch` flag) is available. The shell adapter is `$HOME/.claude/scripts/render-work-summary.sh <taskId>`, and that script's own header is the spec for what it emits - task header, scope delivered, changed files, review outcome, phase strip - including the caps and the hidden-when-empty rules. Exit 2 means the state was unreadable: skip the section, do not substitute a hand-written one.
+
+**Output template:**
+
+```markdown
+### Work Summary
+**Task**: `PROJ-1099`  |  **Branch**: `bugfix/PROJ-1099-dark-mode`  |  **Base**: `develop`  |  **PR**: #104
+
+#### Scope delivered
+- [done] T1 Add failing dark-mode snapshot test
+- [done] T2 Replace Color.white with design token
+
+#### Changed files (3 files · +48 / -12)
+- `Sources/Auth/LoginView.swift` (+24 / -8)
+- `Sources/Auth/LoginViewTests.swift` (+22 / -4)
+- `Sources/DesignSystem/Color+Tokens.swift` (+2 / -0)
+
+#### Review outcome
+- 1 accepted · 0 deferred · 0 rejected · approved=true
+
+#### Phases
+- 0 Init [done] · 1 Plan [done] · 2 Dev [done] · 3 Review [done] · 4 Commit [done] · 5 Report active
+```
+
+**Post-hoc invocation** (task already finished, agent-state.json may be archived): pass `--branch` + `--base-branch` explicitly  -  the script still emits task header + changed-files + phases sections (scope + review outcome are state-dependent and will be absent if state is gone).
+
+**Cost summary generation:**
+
+Emitted only when `reportContent.costSummary === true` and tracker data is available. Source of truth is `phase-tracker.sh`:
+
+1. **Token tallies per phase**  -  `render-cost-summary.sh <taskId>` resolves the tracker JSON itself: worktree candidates (`.worktrees/{taskPath}/phase-tracker.json`) first, then the standard location `$HOME/.claude/logs/multi-agent/{taskId}/tracker-state.json` that `phase-tracker.sh` actually writes. Each phase row carries `{tokens_in, tokens_out}`.
+2. **Fallback to OTel spans**  -  if tracker JSON has no token columns but `otel-spans.jsonl` exists (set `MULTI_AGENT_OTEL_SPANS=1` beforehand), aggregate `phase.tokens` spans by phase ID.
+3. **USD estimate**  -  uses a static price table in `$HOME/.claude/scripts/cost-table.json` (model → $/Mtok_in, $/Mtok_out). Missing model → show ` - ` for USD, never block.
+
+**Output template:**
+
+```markdown
+### Cost Summary
+| Phase | Model | Tokens in | Tokens out | Est. USD |
+|-------|-------|-----------|------------|----------|
+| 1. Analysis | opus   | 12,480 | 3,210 | $0.42 |
+| 2. Planning | opus   | 18,904 | 5,120 | $0.66 |
+| 3. Dev      | sonnet | 42,310 | 9,880 | $0.27 |
+| 4. Review   | opus   | 21,050 | 4,720 | $0.66 |
+| **Total**   |        | **94,744** | **22,930** | **$2.04** |
+```
+
+Generated by `$HOME/.claude/scripts/render-cost-summary.sh <task-id>` using prices from `$HOME/.claude/scripts/cost-table.json`. The channels adapter shells out to this renderer  -  doc table is illustrative only, runtime is authoritative.
+
+**Precision rules:** tokens as thousand-separated integers. USD rounded to 2 dp (`printf '$%.2f'`). Rows with zero tokens dropped. If total USD is ` - ` (no price for any model), replace the total row USD cell with ` - ` and add a one-line footnote: `*USD unavailable  -  add model to cost-table.json*`.

package/pipeline/multi-agent-refs/channels/menu.md

@@ -0,0 +1,55 @@
+# Channels - Menu (Step 2 sources, Step 3a preview, Step 3b picker rules)
+
+> Loaded by `channels/SKILL.md` Step 2. The SKILL keeps the step order and the autopilot rule; this file carries the context-source table, the summary-first preview logic, the greyed-out rules and the first-run defaults. Read it before Step 2.
+
+## Step 2  -  Context sources
+
+Automatic. The generator picks the best-available source:
+
+| Source | Available when | Used for |
+|---|---|---|
+| **Pipeline log** | `$HOME/.claude/logs/multi-agent/<project>/<task-id>/agent-log.md` exists AND matches `jiraId` | "Normal analiz" + "Test senaryoları" content options  -  uses Phase 1/2/4 output verbatim |
+| **PR diff** | PR exists, diff fetchable (`gh pr diff` or Bitbucket `/diff?contextLines=5`) | "Auto-diff summary" content option  -  old enrich behavior |
+| **Manual message** | `--message` / `--message-file` provided | Replaces both sources  -  user text is canonical |
+
+## Step 3a  -  Work Summary preview (summary-first flow)
+
+**Runs only when** (a) `agent-state.json` exists for the task AND (b) a Work Summary can be generated (same availability rule as the "Yapılan iş özeti" content row). Purpose: give the user an instant "what did this ship?" answer BEFORE they pick channels. They see the outcome first, then decide where to route it  -  instead of the reverse.
+
+```bash
+preview=$(bash $HOME/.claude/scripts/render-work-summary.sh "$TASK_ID" 2>/dev/null || true)
+[ -n "$preview" ] && {
+  printf '%s\n\n' "$preview"
+  # Auto-tick workSummary content row when preview was shown.
+  # Users can still untick it in 3b if they don't want to re-send the same
+  # block to remote channels (useful when preview was enough for a look).
+  content_defaults.workSummary=true
+}
+```
+
+When the preview renders:
+- **workSummary** row in 3b is **auto-ticked** (user can still uncheck).
+- Previous `prefs.global.reportContent.workSummary` value is respected  -  if the user had explicitly unticked in a prior run, the auto-tick is **suppressed** and the ticked state matches the pref.
+
+When the preview does NOT render (no state, or pref explicitly off at global level with no override):
+- Skip 3a silently, go straight to the channels picker. The workSummary row in 3b stays at its pref default (`false`).
+
+After the preview prints, 3b renders the two pickers: **Channels** (PR description, Jira comment, Confluence page, Wiki, Board; each unavailable one greyed with its reason) and **Content** (normal analysis, technical analysis, test scenarios, test run, PR auto-diff, manual note, cost summary, work summary).
+
+**Why auto-tick:** the user just saw the summary and is most likely sending it; the explicit pref still wins.
+
+## Step 3b  -  Channel + content picker
+
+**Greyed-out rules:**
+- "Wiki" unselectable unless `state.taskType === "component"` AND `figmaConfig.wiki.enabled === true`. If greyed, show reason: `"(no figma-config or taskType != component)"`.
+- "Board" unselectable unless `figmaConfig.board.enabled === true` AND `figmaConfig.board.provider === "github-projects-v2"` AND `figmaConfig.github.projectV2Id` set. If greyed, show reason: `"(no figma-config.board or projectV2Id missing)"`. Default target column: `inReview`.
+- "Normal analiz" + "Test senaryoları" unselectable if no pipeline log found. Reason: `"(no pipeline log for PROJ-12345)"`.
+- "Teknik analiz" unselectable if no Phase 1 planning log AND no PR diff available. Reason: `"(no technical source  -  need Phase 1 plan or PR diff)"`.
+- "Auto-diff" unselectable if no PR found. Reason: `"(no PR linked to this target)"`.
+- "Manuel not" always available. "Test Koşumu (Xray)": `channels/test-run.md`.
+- "Cost özeti" unselectable if `phase-tracker.sh cost total` prints `-` (no priced token tallies; there is no `status` action) AND no `otel-spans.jsonl` exists for the task. Reason: `"(no tracker data  -  set MULTI_AGENT_OTEL_SPANS=1 or enable token tracking)"`.
+- "Yapılan iş özeti" unselectable if no `agent-state.json` exists for the task (post-hoc call with `--branch` + `--base-branch` flags restores partial availability). Reason: `"(no agent-state.json for {taskId})"`. **Auto-ticked** when Step 3a preview was shown  -  user can still uncheck before confirming the menu.
+
+**Defaults (first run):** PR + Jira ticked, Confluence + Wiki unticked. Content: auto-diff if pipeline log missing; otherwise normal-analiz + test-senaryoları.
+
+Saved to `prefs.global.reportChannels` and `prefs.global.reportContent`  -  next run uses these as defaults.

package/pipeline/multi-agent-refs/channels/multi-repo.md

@@ -13,3 +13,9 @@
 **Target enumeration:** `channels-multi-repo.sh targets <state>` returns a JSON array `[{repoName, prUrl, prNumber, isPrimary, crossLinks}]` for the dispatch loop. Single-repo tasks return one entry with empty `crossLinks`  -  every render-* call falls through to the body unchanged, so the loop is uniform across single-repo and multi-repo paths.
 
 **Logging hint:** `channels-multi-repo.sh summary <state>` produces a one-line autopilot log entry (`1 primary (foo) + 2 extras: <url> <url>` or `single-repo task`).
+
+## Target resolution (Step 1)
+
+**Multi-repo:** when `agent-state.json` `projects[].length > 1`, Step 1 builds **one target per project**. Each project's PR is resolved via `pr` field in its projects[] entry; if missing, the Jira/Issue link query returns multiple PRs (one per repo)  -  all are added to `targets[]`. The project at `projects[0]` (or whose name matches `state.project`) is marked `isPrimary: true`; others are `isPrimary: false`.
+
+For single-repo tasks, `targets` has exactly one entry. The rest of the flow is target-aware: Step 5 generates one body, Step 7 dispatches to each target, with cross-links (see the dispatch table above).

package/pipeline/multi-agent-refs/channels/preview.md

@@ -0,0 +1,25 @@
+# Channels - Preview render (Step 6)
+
+> Loaded by `channels/SKILL.md` Step 6. The SKILL keeps the approval gate, its skip cases, its options and the byte-identical rule; this file carries the per-channel markup conversion, the preview block layout and the secondary-artifact intents. Read it before rendering the Step 6 preview.
+
+Conversion is per-channel; two channels have none:
+
+| Channel | Conversion after approval | Table |
+|---|---|---|
+| PR description | **none**  -  posted as Markdown, verbatim | GitHub / Bitbucket / GitLab all render Markdown; see `channels/pr.md` "Markup dialect" |
+| GitHub issue comment | **none**  -  posted as Markdown, verbatim |  -  |
+| Jira comment | markdown → Jira wiki markup | `channels/jira.md` "Wiki markup conversion" |
+| Confluence page | markdown → storage format | `channels/confluence.md` "Body conversion" |
+
+The Jira table is the only *text* markup table in the doc set and never applies to the PR body: `h2.`, `{{code}}` or `#`-numbered lists render there as raw wiki markup.
+
+```
+── PR description  ({repoName} #{prNumber}, replace) ─────────
+{body}
+── Jira comment  ({jiraId}) ──────────────────────────────────
+{body}
+── Confluence page  ("{title}" under {parentUrl}) ────────────
+{body}
+```
+
+Secondary artifacts ride along as one-line intents at the bottom of the preview: Wiki page list, wiki → Jira triad comment (when Wiki is selected and the triad is active per `$HOME/.claude/multi-agent-refs/issue-jira-triad.md`), Board status move (`{from} → {to}`), GitHub issue comment + Progress-flag sync (Phase 5 Step 1.5  -  same gate, see `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md`), test-run candidates to untick (`channels/test-run.md`), the Jira body's `--measure` (`render-jira-evidence.mjs`).

package/pipeline/multi-agent-refs/channels/reference.md

@@ -0,0 +1,98 @@
+# Channels - Input forms, flags, summary format, error handling, cross-CLI parity, examples
+
+> Loaded by `channels/SKILL.md`. Read the flag table and the error-handling table before Step 1 and whenever a target, a token or a precondition fails; the parity notes and examples are for orientation.
+
+## Input forms
+
+```
+/multi-agent:channels                                         # cwd + current branch
+/multi-agent:channels PROJ-12345                            # Jira ID
+/multi-agent:channels #42                                     # GitHub issue/PR number
+/multi-agent:channels https://github.com/<org>/<repo>/pull/N
+/multi-agent:channels https://<bitbucket-host>/projects/.../pull-requests/N
+/multi-agent:channels https://<jira-host>/browse/PROJ-12345
+
+/multi-agent:channels PROJ-12345 --channels jira,confluence # non-interactive channel
+/multi-agent:channels PROJ-12345 --content auto-diff        # non-interactive content
+/multi-agent:channels PROJ-12345 --message "root: ..."      # manual source
+/multi-agent:channels PROJ-12345 --message-file notes.md    # manual, long
+/multi-agent:channels PROJ-12345 --dry-run                  # preview, no POST
+```
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| `--channels pr,jira,confluence,wiki` | Non-interactive channel selection (comma list). Skips channel menu. |
+| `--content normal,technical,test,auto-diff,note,test-run` | Non-interactive content selection. Skips content menu. |
+| `--flow-run <runId>[,<runId>...]` | Runs for the test run block (`channels/test-run.md`). |
+| `--message "..."` | Manual mode  -  use user text as source, no diff read. Forces `content=note`. |
+| `--message-file path` | Manual mode, long message from file. |
+| `--append` | PR description: append instead of replace. |
+| `--dry-run` | Generate, print to stdout, do not POST. |
+| `--lang=tr\|en\|both` | Output language override (default: `en`; `promptLanguage` is locked to `en`). |
+| `--ready` | If PR draft, promote to READY after channels dispatch. |
+
+## Step 8 summary format
+
+```
+channels dispatch complete
+  PR description  ✓   version 3→4, reviewers 23 preserved
+  Jira comment    ✓   posted → <jira-url>?focusedCommentId=2484780
+  Confluence      -   skipped: user declined
+  Wiki            ✓   3 files via github-wiki adapter
+  Board           ✓   In Develop → In Review (project #4)
+```
+
+## Error handling
+
+| Condition | Behavior |
+|-----------|----------|
+| No target resolvable | Error, exit 1 |
+| PR not found + Jira selected | Proceed Jira-only, log reason |
+| PR merged/closed | Warn, confirm continue |
+| Author bot / dependabot | Skip entire run |
+| Diff > 2 MB | Ask: skip / top-20-files / cancel |
+| No pipeline log + "Normal analiz" selected | Greyed out at menu; if forced via `--content`, error |
+| Bitbucket PR version mismatch | Refetch once, retry; fail on second mismatch |
+| Jira token missing/expired | Token Save Flow inline; skip on user-skip |
+| Wiki preconditions not met | Case B menu per `$HOME/.claude/multi-agent-refs/wiki-capture.md` |
+
+## Cross-CLI parity
+
+| CLI | Command name | Invocation |
+|---|---|---|
+| Claude Code | `/multi-agent:channels` | Slash namespace (colon) |
+| Copilot CLI | `multi-agent-channels` | Top-level command (dash-separated, no namespace support) |
+
+Both installations read the same source file (`$HOME/.claude/commands/multi-agent/channels/SKILL.md`)  -  `install.js --all` copies to:
+- `~/.claude/commands/multi-agent/channels/SKILL.md`
+- `~/.copilot/commands/multi-agent-channels.md`
+
+Prompts MUST be byte-identical. `smoke-cross-cli-behavior.sh` asserts this  -  spacing, brackets, numbering, log-line format.
+
+Progress emission on Copilot (no native TaskCreate UI): `bash ~/.copilot/scripts/phase-tracker.sh sub 5 <N> "<step>" <status>`  -  same shape as Phase 5.
+
+## Examples
+
+```
+/multi-agent:channels
+  → resolves from cwd+branch → PROJ-12345 + PR #3433
+  → menu: PR ✓ Jira ✓ / Normal analiz ✓ Test senaryoları ✓
+  → PR description replaced (v3→4, 23 reviewers preserved)
+  → Jira comment posted (id 2484780)
+  → Confluence -  Wiki -
+
+/multi-agent:channels PROJ-12345 --channels confluence --content note --message-file notes.md
+  → non-interactive: only Confluence, content from notes.md
+  → asks: parent page URL (or recent [1] / [2])
+  → page created → https://<host>/pages/12345
+
+/multi-agent:channels https://<bitbucket>/.../pull-requests/42 --dry-run
+  → resolves → PROJ-67890
+  → prints Jira + PR body preview to stdout, no POST
+
+/multi-agent:channels --message "root: order id empty, UI silent. fix: length>0 guard in HomeVC.m"
+  → auto-diff from cwd+branch PR + user note combined
+  → posts to default channels (PR + Jira)
+```

package/pipeline/multi-agent-refs/features/autopilot-circuit-breaker.md

@@ -32,7 +32,7 @@ Trigger 2 is the key addition over the plain build-retry cap: a build can "fail
 | Trigger | Evaluated by | Status |
 |---|---|---|
 | 2, finding half | `review-delta.mjs` exit 3 at Phase 3 Step 3.8: a blocking/important finding whose `fingerprint` (finding-fingerprint.mjs) stays in the accepted set for `identicalFindingCycles` consecutive rounds | **code** (v16.20.0) |
-| 3 | Phase 3 re-entry item 6: the `retryCount === 3` hard-kill records the trip | **code** (v16.20.0) |
+| 3 | Phase 3 re-entry item 6: at `retryCount === 3`, `rework-rulings.mjs` rules on every open finding; the hard-kill, and the trip, happen only when a ruling is `escalate`. All parked: no trip, the run continues to Phase 4 with them as follow-ups | **code** (v16.20.0, rulings 20.34.0) |
 | 2, build-error half | needs a build-log signature normaliser | documented behaviour, no script yet |
 | 1 | needs checkpoint-to-checkpoint artifact diffing | documented behaviour, no script yet |
 | 4 | belongs to `cost-budget-check.mjs` | documented behaviour, no script yet |

package/pipeline/multi-agent-refs/features/code-graph.md

@@ -4,6 +4,7 @@
 - [Phase 1 Step 2.6  -  query before dispatching Explore](#phase-1-step-26---query-before-dispatching-explore)
 - [Impact of a change, not of a name](#impact-of-a-change-not-of-a-name)
 - [Who implements this](#who-implements-this)
+- [How two symbols connect](#how-two-symbols-connect)
 - [Confirming with a language server](#confirming-with-a-language-server)
 - [Phase 5 Step 3  -  refresh after the branch changed code](#phase-5-step-3---refresh-after-the-branch-changed-code)
 - [What the report answers that a file-level view cannot](#what-the-report-answers-that-a-file-level-view-cannot)
@@ -93,6 +94,17 @@ them with every other dependency. Production code never gains an edge to a
 type a test file declares, so a fake named after a framework type cannot turn
 into a hub.
 
+### How two symbols connect
+
+`graph-query.mjs --path <from> <to>` answers with the shortest chain of edges
+between two symbols or files, given by id or by name. An ambiguous name is
+refused with its candidate ids and an unknown one gets its nearest names (exit
+3), so the answer is never a guess. A module node (an import the repository
+does not declare) can end a path but is never walked through, since it joins
+every file that imports it. On Android, a capitalised `fun` (in practice a
+Compose UI function) is a symbol of kind `composable`, so screens and
+components take part like types.
+
 ### Confirming with a language server
 
 The graph joins by name, so a direct dependent can be a file that only uses
@@ -134,6 +146,21 @@ node $HOME/.claude/scripts/validate-code-graph.mjs "$GRAPH_PATH"
 node $HOME/.claude/scripts/graph-report.mjs --graph "$GRAPH_PATH"
 ```
 
+The report adds three whole-graph views (`_graph-analysis.mjs`): import cycles
+(files that import each other, directly or around a loop), clusters of files
+more connected to each other than to the rest (label propagation over imports
+and references, with cohesion = the share of a cluster's edges that stay
+inside), and a short list of questions worth asking before a change, drawn
+from the hubs, the cycles and the strongest links between clusters. All three
+are deterministic, so a changed report means changed code. `graph-report.mjs
+--diff <older graph>` lists what changed between two builds.
+
+A run across several repositories (dev-context extras, submodules) joins their
+graphs with `graph-links.mjs build --projects <a,b,...>`: an import of a name
+one repository does not declare is matched against what the others export,
+and `graph-links.mjs affected --project <b>` lists the files elsewhere that
+import b. The graphs are not merged (ADR-0018).
+
 The rebuild costs no API tokens, so it runs every task rather than on a staleness
 heuristic. A non-zero validator exit keeps the previous graph and logs
 `knowledge.graph_invalid`; it never fails the run  -  a stale graph is a degraded

package/pipeline/multi-agent-refs/features/office-threat-model.md

@@ -50,7 +50,7 @@ not mitigated here.
 | T4 | Secret exposure through a response | Transcripts are read through `_transcript-tail.mjs`, which never parses api-request records and drops thinking blocks; every string passes the credential redactor and the scrubber; the finished office and chat documents are checked by the outbound gate; seat labels come from allow-listed fields (tool name, file basename, sidecar description), never a command line; credentials are read only by the service scripts and never returned | `smoke-office-privacy.sh`, `smoke-office-security.sh` T4, `test/office-activity.test.mjs` "carries no credential" |
 | T5 | Path traversal into arbitrary files | Session, agent, run, routine, tool and evidence ids are matched against safe character sets after decoding; transcripts are looked up by name under the projects root only; a screenshot must resolve (real path) inside the run's evidence directory; an analysis document named in run state is read only when its real path is inside the run's log directory, its artifacts or a worktree git lists under the state's projectRoot, and only when it is Markdown or HTML | `smoke-office-security.sh` T5, `test/office-work.test.mjs` "nothing outside its directory", "analysis documents are read only inside the run's roots", "a worktreePath counts only when git lists it" |
 | T6 | Oversized or malformed input | Bodies are capped at 64 KiB and validated against the route's schema; tool arguments are checked against the tool's inputSchema; launch input goes through `launch-request.mjs` validation only; chat paging is capped at 500 | `smoke-office-security.sh` T6, `office-work.test.mjs` "refuses an unknown tool, invalid arguments and an oversized body" |
-| T7 | Resource exhaustion | At most four event streams and 64 connections; a phone request has five seconds to send its body before any signature work; at most 256 confirm tokens, the oldest dropped first; service clients, the work list and autopilot control run as child processes, never blocking the event loop, one at a time per service (429 `busy` for a second one); one snapshot is computed per poll from bounded tail reads; the session list is cached for ten seconds; a server started on its own exits after its idle time and after 8 hours in any case, the one `office-on` starts runs until `office-off`, and both stop on SIGTERM | `smoke-office-security.sh` T7; `office-routes.test.mjs` "connections past the cap are dropped", "never sends its body", "confirm tokens are capped"; `office-work.test.mjs` "a slow service read neither blocks other routes nor runs twice at once" |
+| T7 | Resource exhaustion | At most four event streams and 64 connections; a phone request has five seconds to send its body before any signature work; at most 256 confirm tokens, the oldest dropped first; service clients, the work list and autopilot control run as child processes, never blocking the event loop, one at a time per service (429 `busy` for a second write or service read; a second `GET /v1/prs`, `GET /v1/autopilot` or maturity read of the same issue shares the run in flight, and at most two maturity reads for different issues run at once); one snapshot is computed per poll from bounded tail reads; the session list is cached for ten seconds; a server started on its own exits after its idle time and after 8 hours in any case, the one `office-on` starts runs until `office-off`, and both stop on SIGTERM | `smoke-office-security.sh` T7; `office-routes.test.mjs` "connections past the cap are dropped", "never sends its body", "confirm tokens are capped"; `office-work.test.mjs` "a slow service read neither blocks other routes nor runs twice at once", "maturity checks for different issues run at most two at a time" |
 | T8 | XSS from hostile transcript or issue text | The panel renders every server string with `textContent` or canvas text; markdown is shown as plain text; server images only as `data:` URLs of image types; the office sprites are same-origin PNGs from `/office/assets/`, which answers only a plain file name (no separator or escape) whose real path is a PNG directly in the installed assets directory, and 404 otherwise; the page language the server stamps comes from a two-value set (`en`, `tr`), whatever the preferences file holds; the page's CSP allows only its per-response nonce for script and style, `connect-src 'self'`, no framing, no base URI, no form action | `smoke-office-page.sh`, `office-routes.test.mjs` "stamps the page language from outputLanguage", "serves a sprite and nothing else under /office/assets/", `office-build.test.mjs`, `smoke-office-runtime.sh` |
 | T9 | Clickjacking | `frame-ancestors 'none'` on the page and on every API response | `office-routes.test.mjs` "serves the page without a token, with a nonce CSP" |
 | T10 | An action nobody can account for | Every write leaves one line (who, route, step, status; never a body or token) in `office-actions.jsonl` | `office-routes.test.mjs` "every write leaves a line" |

package/pipeline/multi-agent-refs/features/plan-critic.md

@@ -53,8 +53,11 @@ CRITIC_RUNG=$(bash "$HOME/.claude/lib/model-dispatch.sh" subagent --persona plan
 ```
 
 It reads the plan, the analysis document(s), the constitution and the worktree,
-and writes objections under four lenses: `scope`, `feasibility`, `security`,
-`alternative` (a cheaper plan with the same result). Each objection has an id
+and writes objections under six lenses: `scope`, `feasibility`, `security`,
+`alternative` (a cheaper plan with the same result), `unstated-input` (an
+input the spec implies that no task's tests exercise) and `underspecified` (a
+decision a task leaves to its implementer that the analysis or the user should
+make). Each objection has an id
 (`OBJ-NN`), a lens, a claim, at least one evidence anchor and, when the plan
 breaks one, a constitution rule id. The orchestrator writes the output to
 `$WORKTREE/.pipeline/plan-critique.json` (`schemas/plan-critique.schema.json`)

package/pipeline/multi-agent-refs/features/review-delta.md

@@ -39,7 +39,8 @@ Phase 2 Step 3.7 wrote `$WORKTREE/.pipeline/scope-check.json` (contract: `featur
 ```bash
 SCOPE_JSON="$WORKTREE/.pipeline/scope-check.json"
 SCOPE_GATE=$(git -C "$WORKTREE" diff --name-only "origin/$BASE_BRANCH"...HEAD \
-  | node $HOME/.claude/scripts/scope-check-gate.mjs --check "$SCOPE_JSON" --diff-files - --advisory 2>/dev/null)
+  | node $HOME/.claude/scripts/scope-check-gate.mjs --check "$SCOPE_JSON" --diff-files - --advisory \
+      --repo "$WORKTREE" --patch-range "origin/$BASE_BRANCH...HEAD" 2>/dev/null)
 ```
 
 ```
@@ -48,6 +49,8 @@ Files and the reason the dev gave for touching each:
 {jq -r '.files[] | "- \(.path): \(.reason)"' "$SCOPE_JSON"}
 Files in the diff with no stated reason (flag as scope drift if the change is not obviously required):
 {jq -r '.unjustified[]' <<< "$SCOPE_GATE"}
+Layout-only hunks (whitespace the task did not need; a suggestion at most):
+{jq -r '.formatOnly[]? | "- \(.file) \(.hunk)"' <<< "$SCOPE_GATE"}
 Deliberately not done (do not raise these as findings; they are known):
 {jq -r '.notDone[] | "- \(.what) (\(.why))"' "$SCOPE_JSON"}
 </scope-self-check>

package/pipeline/multi-agent-refs/features/scope-check.md

@@ -29,7 +29,16 @@ git -C "$WORKTREE" diff --name-only "origin/$BASE_BRANCH"...HEAD \
   | node $HOME/.claude/scripts/scope-check-gate.mjs --check "$WORKTREE/.pipeline/scope-check.json" --diff-files -
 ```
 
-Output `{ok, justified, unjustified[], unlisted[], notDone}`. Exit 1 lists `unjustified[]` (in the diff, no reason or an empty one); `unlisted[]` (in the record, not in the diff) is reported and never fatal. Complete the record once and re-run. A second exit 1 does not block: log `dev.scope_check=incomplete unjustified=<n>` and hand off; Phase 4 receives the gate output inside `<scope-self-check>`, so reviewers see which files arrived without a stated reason. `--advisory` (used by Phase 4) always exits 0. Progress line: `    → checking scope self-check ({n} files, {m} not done)`.
+Output `{ok, justified, unjustified[], unlisted[], notDone}`, plus `formatOnly[]` with `--patch` / `--patch-range` (`patchError` when the diff could not be read). With `--patch <unified diff>` (or `--repo <dir> --patch-range <a>...<b>`, which reads that diff itself), `formatOnly[]` lists hunks whose removed and added lines differ only in whitespace: a reformat of lines the task did not need to touch. It is reported, never fatal, and reviewers see it in `<scope-self-check>`. Exit 1 lists `unjustified[]` (in the diff, no reason or an empty one); `unlisted[]` (in the record, not in the diff) is reported and never fatal. Complete the record once and re-run. A second exit 1 does not block: log `dev.scope_check=incomplete unjustified=<n>` and hand off; Phase 4 receives the gate output inside `<scope-self-check>`, so reviewers see which files arrived without a stated reason. `--advisory` (used by Phase 4) always exits 0. Progress line: `    → checking scope self-check ({n} files, {m} not done)`.
+
+## Known limits in the code
+
+A limit accepted on purpose is marked at the line, in the file's comment
+style: `shortcut: <the limit>, <when to replace it>`. `notDone[]` says what the
+change left out; the marker says what the code that shipped does not handle
+yet. `debt-ledger.mjs` collects the markers a diff adds into the repo's debt
+list, reviewers do not re-raise a marked limit unless it breaks a requirement
+or a security rule, and the PR description lists them.
 
 ## Consumers
 

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

@@ -81,6 +81,8 @@ Knowledge files grow over time. Maintenance rules:
   and a rebuild is seconds, so age is the wrong question to ask of it.
 - `product-context.jsonl` is written by runs of OTHER repositories of the same product (`features/product-context.md`) and keyed by the remote sha it was read at; `product-context.mjs recall` returns a row only while that sha is current, so it needs no age rule
 - Stale entries are added to the prompt with a "STALE  -  verify before relying" tag
+- A ledger entry earns or loses weight from the outcomes recorded against it: Phase 5 runs `learnings-ledger.mjs feedback --id <L:id> --outcome useful|dead_end|corrected` for each injected entry the run relied on or found wrong. Corrected, or a dead end at least twice and more often than useful, drops it from `brief` and `profile`; useful at least twice adds a strength that fades with age (`_memory-policy.mjs`). A new entry that repeats an existing one in other words (TF-IDF cosine 0.9 or more, same numbers, same negations) is not added
+- `prefs.global.memory.excludeProjects` lists repo slugs whose ledger, triage corpus and debt list are never written
 - `prune-logs` does not touch knowledge  -  only deletes logs and state
 - `purge` does not touch knowledge either. Today the only removal path is `/multi-agent:uninstall --all-data`, which drops every project's knowledge at once; there is no per-project clear yet
 
@@ -113,6 +115,13 @@ node "$HOME/.claude/scripts/triage-memory.mjs"    timeline --anchor T:<id> --bef
 node "$HOME/.claude/scripts/learnings-ledger.mjs" timeline --anchor L:<id> --before 3 --after 3
 ```
 
+A store too large to rank in one pass (thousands of triage rows) goes through
+the toolkit's full-text index instead of a whole-file read: `context_index` on
+the store's path (`learnings-ledger.mjs path`, `triage-memory.mjs path`), then
+`context_search` for ranked snippets and `context_get` for one passage. The
+index is owner-only and re-indexing an unchanged file is a no-op, so this is
+layer 1 and 3 again over the same rows, not a second copy to keep in step.
+
 ## Skill Injection Strategy
 
 When calling sub-agents, inject task-specific context from previous phases: