@mmerterden/multi-agent-pipeline 20.30.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

@@ -1,5 +1,13 @@
 # Office routes: threat model
 
+<!-- toc -->
+- [Assets](#assets)
+- [Attackers](#attackers)
+- [Threats and controls](#threats-and-controls)
+- [Residual risks](#residual-risks)
+- [Later, with a remote carrier](#later-with-a-remote-carrier)
+<!-- /toc -->
+
 The office routes of `scripts/contract-server.mjs` let a client watch the
 agents on this machine, read what they said, answer and steer runs, and change
 what runs here (autopilot, stacks, routines). A browser panel may be served at
@@ -20,6 +28,8 @@ not mitigated here.
 | Run state | `agent-state.json`, `tracker-state.json` | an answer or steer written here changes what a run does |
 | Machine configuration | autopilot `config.json` and launchd jobs, a repo's `.claude/settings.json`, routine commands | widening any of them changes what runs unattended |
 | PR verdicts | posted to GitHub or Bitbucket with the user's own credential | an approval in the user's name |
+| Learning stores | `~/.claude/memory/multi-agent/<repo>/` and `~/.claude/knowledge/<repo>/` | statements a run wrote down, which can quote code or a pasted secret |
+| Run logs | `~/.claude/logs/multi-agent/<project>/<task>/` | deleting the wrong folder loses a live run's state |
 
 ## Attackers
 
@@ -36,20 +46,28 @@ not mitigated here.
 |---|---|---|---|
 | T1 | DNS rebinding: a page on an attacker host resolves to 127.0.0.1 and calls the API under its own name | Every request, `/office` and the event stream included, must carry `Host: 127.0.0.1:<port>` or `localhost:<port>`; anything else is 403 before routing | `smoke-office-security.sh` T1, `test/office-routes.test.mjs` "403 under a rebound Host" |
 | T2 | CSRF: a page posts to a write route | Writes (POST, DELETE) accept no `Origin` but the server's own, even an origin allowed with `--allow-origin`; a foreign preflight is 403 and no CORS header is ever sent to a foreign page; writes that widen what runs here take a second request with a single-use, route-bound confirm token | `smoke-office-security.sh` T2, `office-routes.test.mjs` "a write from a foreign page is refused" |
-| T3 | Token theft or replay | The token is read from the `Authorization` header only (never a cookie or a query parameter), compared in constant time over digests, never written into a response, an error or a log line. It never appears in a URL: `office-on` opens the page with a one-time code in the fragment (10 seconds, one use, minted by the bearer holder at `POST /office/code` with no Origin), and the page trades it at `POST /office/exchange`, which accepts only the server's own Origin; a second use, an expired or an unknown code is 401. The code never reaches a command line, which every local user can read (`ps`): the browser is opened on a 0600 launcher page in the 0700 state directory that carries the code and forwards with `location.replace`, under a CSP that allows only its own script by hash; the launcher is removed after 15 seconds. An Origin header can be forged by a non-browser client, so the code's secrecy and its 10 second, single-use life are what protect the exchange. The page keeps the token in memory and strips the fragment. The server exits after 8 hours however busy it is, so a token cannot outlive a working day | `office-control.test.mjs` "the opener's argv carries no code", "the launcher page has a strict CSP", "the launcher is deleted"; `office-routes.test.mjs` "a panel code trades for the token once", "a code is refused from a foreign page", "an expired code is 401", "exits at its absolute lifetime"; `smoke-office-page.sh` "the code trades once" |
+| T3 | Token theft or replay | The token is read from the `Authorization` header only (never a cookie or a query parameter), compared in constant time over digests, never written into a response, an error or a log line. It never appears in a URL: `office-on` opens the page with a one-time code in the fragment (10 seconds, one use, minted by the bearer holder at `POST /office/code` with no Origin), and the page trades it at `POST /office/exchange`, which accepts only the server's own Origin; a second use, an expired or an unknown code is 401. The code never reaches a command line, which every local user can read (`ps`): the browser is opened on a 0600 launcher page in the 0700 state directory that carries the code and forwards with `location.replace`, under a CSP that allows only its own script by hash; the launcher is removed after 15 seconds. An Origin header can be forged by a non-browser client, so the code's secrecy and its 10 second, single-use life are what protect the exchange. The page keeps the token in memory and strips the fragment. A server started by `contract-server.mjs` alone exits after 8 hours however busy it is; the panel's own server (`office-on`) runs until `office-off`, because a person keeps it open beside their work. Its token lives only in the server's memory, the page's memory and a 0600 file, is never on a command line or in a URL, and is replaced each time `office-on` starts a server | `office-control.test.mjs` "the opener's argv carries no code", "the launcher page has a strict CSP", "the launcher is deleted"; `office-routes.test.mjs` "a panel code trades for the token once", "a code is refused from a foreign page", "an expired code is 401", "exits at its absolute lifetime"; `smoke-office-page.sh` "the code trades once" |
 | 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; the server exits after its idle time, after 8 hours in any case, and 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" |
-| T11 | The panel widening the machine silently | Autopilot on, stack changes and routine removal are tagged `local-only` and `high`, take two requests, and run the same scripts as the terminal commands | `smoke-office-routes.sh`, `smoke-office-single-source.sh` |
+| T11 | The panel widening the machine silently | Autopilot on, stack changes, routine removal and adding or removing a launch repository are tagged `local-only` and `high`, take two requests, and run the same scripts as the terminal commands where one exists (removing a launch repository has none). A repository is added only as a git checkout that is neither the home directory nor the root; a suggestion is named by an opaque id and resolved again on the server, so a page never sends or sees a path it did not type | `smoke-office-routes.sh`, `smoke-office-single-source.sh`, `office-repos.test.mjs`, `smoke-office-ui.sh` |
 | T12 | A toolkit tool used as a reader of local files or services (a path, a `file://` or loopback URL, a shared browser page, an index of files) | Tool calls are denied by default: only a tool that declares readOnlyHint, is not destructive, is not in the `web` or `context` family and whose inputSchema takes no location (a property named for a path, URL, file, directory, output, project, root and similar, or a uri format, at any depth) is callable; everything else is 403 `tool-not-allowed` and never reaches the server. A `confirm` argument is refused, so a tool's own preview is never skipped. The toolkit child always runs with `MULTI_AGENT_UNATTENDED=1` and `MCP_TOOLKIT_URL_POLICY=strict`, applied after the registration's own environment. An `@latest` registration is pinned to a configured version or refused. The route is `local-only`, and its audit line names the tool and carries a SHA-256 of the arguments, never the arguments | `office-work.test.mjs` "refuses every tool outside the allowlist with 403 and never runs it", "refuses a confirm argument", "runs unattended with the strict URL policy", "pinned to a known version or refused", "the audit line names the tool and hashes the arguments" |
 | T13 | A steer instruction injected into an unattended run | Steering is tagged `launch` and `high` and takes two requests: the first shows the text, the run's phase and the unread instruction it replaces, and returns a token bound to that run and exactly that text; the second carries only the token. A finished run cannot be steered | `office-routes.test.mjs` "previews first, then queues on confirm", "a steer token is single use, bound to its run and cannot carry new text" |
 | T14 | A review verdict posted from a stale or unfinished review | A verdict is previewed only for a finished review whose every finding is accepted, rejected or deferred (409 `review-incomplete` otherwise); the confirm token is bound to the decision and a digest of the findings, and a confirmation after either changed is 409 `confirm-mismatch` | `office-work.test.mjs` "a running review or one with an untriaged finding cannot be previewed", "refused when the findings changed after the preview" |
 | T15 | A service read pointed at another host | A Confluence URL is accepted only on the configured Confluence host, and with no host configured only a page id is accepted (409 `host-not-allowed`), before the client script runs; Crashlytics takes only a Firebase console URL | `office-work.test.mjs` "a Confluence URL on another host is refused before the client runs", "only a page id is accepted" |
 | T16 | Machine paths leaking through errors, or `office-off` signalling a reused pid | Error bodies name no absolute path (the launchd refusal and the unreadable settings message say what failed, not where); `office-off` sends SIGTERM only when the recorded pid's token file still names it, its command is `contract-server.mjs` and its start time matches the token file's | `office-routes.test.mjs` "refused without naming its path", "reported without the plist path"; `smoke-office-control.sh` "off never signals a pid that is not its server" |
+| T17 | A reload code minted for another page, or a stale server outliving an update | `POST /office/reload` and `GET /office/version` need the bearer token and refuse any Origin other than the panel's own (a request with no Origin, a terminal client, is accepted); the reload code is the same 10 second, single-use code `office-on` uses, so a page that already holds the token gains nothing it did not have. A server whose code changed on disk is reported stale and `office-on` replaces it instead of reusing it | `office-repos.test.mjs` "/office/version reports the installed build", "/office/reload mints a one-time code"; `smoke-office-ui.sh` |
+| T18 | The panel starting work nobody asked for, or work wider than asked | `POST /v1/jobs` takes only a job named in `schemas/office-jobs.json`, each parameter checked by its kind (a pull request URL or `repo#N`, a Jira key, a run id the index knows, a branch name, a path that stays inside the repository, an enumerated value; a pipeline run's work item goes through the launch request rules). Two requests: the preview names the role, the repository, the exact prompt and what the job writes outside the machine (a branch and PR for a pipeline run; review and clarify jobs report locally, since agent-guard keeps GitHub writes to the runner), and the token is bound to that payload. At the confirmation the repository must still be allowed, the unattended profile installed, the workspace trusted, agent-guard.sh registered for every tool and the autopilot runner's sandbox check passing; the session runs `claude --bg` with no permission prompts under that profile, without a shell, and claude's own output stays in the server's log, not the page. The unattended profile denies reading the server's token directory, so a session it starts cannot pick up the bearer. A team job is refused while a run is live in the same repository, from the moment its session starts. Tagged `local-only`/`high`: no phone route reaches it. Every start is recorded under `logs/multi-agent/office/jobs/` and in `office-actions.jsonl` | `office-jobs.test.mjs`, `smoke-office-ui.sh` |
+| T19 | The key cabinet leaking a credential, or the panel becoming a place to enter one | `GET /v1/credentials` runs `lib/credential-inventory.sh`, whose probe reads each credential through the credential store with its output discarded, so no value reaches the server process. The route keeps the logical name, a state and a probe verdict from fixed vocabularies and a capability line cut to 160 characters; anything else in the script's output is dropped. Tagged `local-only`: not even the state goes to a phone. There is no write route: renewing a credential stays in the terminal (`/multi-agent:setup`), so a secret never passes through the browser | `office-routes.test.mjs` "GET /v1/credentials names each credential and its verdict, never a value" |
+| T20 | A learned statement carrying a secret or a machine path to the page | `GET /v1/memory` returns counts, the code graph's age and size, and the five newest learning statements per repository, each passed through the transcript redactor (provider credential rules, paths and addresses) and cut to 120 characters. Repository names are matched against a safe character set before any file is opened. Read only; `local-only` | `office-routes.test.mjs` "GET /v1/memory reports every shelf, redacted" |
+| T21 | Machine details through the resource panel | `GET /v1/system` returns numbers only (cores, load, memory, free disk, process counts, log folder size) and two fixed warnings; no path, process argument, user or host name. The schema allows nothing else. The measurement runs as child processes off the event loop, concurrent requests share one measurement, and the log folder size is reused for a minute. Readable from a phone, since it names nothing | `office-routes.test.mjs` "GET /v1/system returns numbers only: no path, user or host name" |
+| T22 | Old run logs deleted wider than asked, or a live run's log removed | `POST /v1/prune-logs` takes only an age from a fixed set (7, 30 or 90 days) and runs `prune-logs.sh`, the script `/multi-agent:prune-logs` runs: the dry run is the preview; the confirmed step lists the folders again, refuses with `changed` when they differ, and then prunes only the previewed list through `--only-from`, under a token bound to that age and list. The script never touches the audit trail, the metrics corpus or the task counters, refuses a log root that is `/`, the home folder or a git checkout, and spares a folder written in the last minutes and a run that can still be resumed. Tagged `local-only`/`high` | `office-routes.test.mjs` "POST /v1/prune-logs previews, then prunes only on the token" |
+| T23 | Pull request listing exposing a token, or the native task mirror writing into another run | Each GitHub account gh is logged in to is asked with `gh auth token` for that host and login; the token travels in `GH_TOKEN` (and `GH_ENTERPRISE_TOKEN` for an Enterprise Server host) for the child process only, never on a command line, in a response or a log. Bitbucket Server is read over https only (a plain-http host is refused unless it is the loopback), redirects are not followed, and the token, read from the credential store with a deadline, travels in the `Authorization` header only; an unreachable host is a reason on that source, not a failure of the list. A redacted answer drops URLs and logins, numbering the accounts instead. The task-mirror hook (PostToolUse on TaskCreate and TaskUpdate) writes only into the run whose recorded session is the calling session, skips phase tiles, never prints, and exits 0 on any input it cannot read | `work-items-prs.test.mjs`, `task-mirror.test.mjs` |
+| T24 | The panel changing a preference wider than the terminal would, or posting addresses to a phone | `POST /v1/settings` takes one of three settings and one of its two values, previews the change and runs, under a token bound to that setting and value, what `/multi-agent:language`, `/multi-agent:model` or `/multi-agent:route-on`/`route-off` runs; route on passes the saved strategy back so only the switch changes, nothing the panel sends can add rules or a free provider, and two changes never run at once. Tagged `local-only`/`high`. Report links: `channelResults` URLs must be https, travel only in the run record's `channelUrls` (local, dropped from a redacted answer) and are shown as text, never followed | `office-routes.test.mjs` "POST /v1/settings changes a switch only on the token, through its script", `runs-index.test.mjs` |
 
 ## Residual risks
 
@@ -64,9 +82,9 @@ not mitigated here.
   nothing local does.
 - **A page on the server's own origin** is trusted. Only the page this server
   serves can be there, and its CSP keeps other code out.
-- **Starting a session**: the server returns the launch plan and never starts
-  a host process, so a panel without a local process to run the plan cannot
-  start work by itself. That is a deliberate boundary of the contract.
+- **Starting a session**: `POST /v1/launch` returns the launch plan for a
+  client to start. `POST /v1/jobs` starts a session itself, because the office
+  is that client; it is bounded by T18 and is never reachable from a phone.
 - **Host permission prompts** are not forwarded: the host records none where
   another process can read them (`GET /v1/permissions` says `available:
   false`).

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/features/unattended-security.md

@@ -566,7 +566,7 @@ protected paths (`~/.claude/**`, `~/.copilot/**`, `~/.codex/**`,
 `~/.config/gh`, `~/.config/git`, `~/.gitconfig`, `~/.npmrc`, `~/.netrc`,
 `~/.git-credentials`, `.git/hooks/**`, `.git/config`, `**/.github/workflows/**`),
 and the toolkit env `MCP_TOOLKIT_URL_POLICY=strict` and
-`MCP_TOOLKIT_INDEX_DENY=~/.ssh,~/.aws,~/.gnupg,~/Library/Keychains`.
+`MCP_TOOLKIT_INDEX_DENY=~/.ssh,~/.aws,~/.gnupg,~/Library/Keychains,~/.claude/logs/multi-agent/contract-server,~/.claude/logs/multi-agent/office`.
 
 The runner hands the file to each child with `claude --settings`, so only the
 unattended session loads it. `~/.claude/settings.json` is the attended posture

package/pipeline/multi-agent-refs/help/en.md

@@ -86,9 +86,9 @@ Status & Resume:
   /multi-agent:autopilot-status  Running, queued, awaiting an answer, today's PRs
   /multi-agent:autopilot-off  Stop picking work up (running work finishes; --now stops it)
   /multi-agent:serve          Contract server for a client: 127.0.0.1, token, stops when idle
-  /multi-agent:office-on      Open the office panel in your browser: agents at work, chats, ledger, runs
+  /multi-agent:office-on      Open the office in your browser: live runs and agents, PRs, keys, memory, system, jobs; its orientation room explains the rest
   /multi-agent:office-status  Is the panel running, its URL (never the token), its last actions
-  /multi-agent:office-off     Close the panel now (it also stops by itself when idle)
+  /multi-agent:office-off     Stop the panel's server (it runs until you do)
 
 Post-Hoc & Side-Channel:
 

package/pipeline/multi-agent-refs/help/tr.md

@@ -85,9 +85,9 @@ Status & Resume:
   /multi-agent:autopilot-status  Koşan, sıradaki, cevap bekleyen, bugünkü PR'lar
   /multi-agent:autopilot-off  Yeni madde alma (koşan iş biter; --now onu da durdurur)
   /multi-agent:serve          İstemci için sözleşme sunucusu: 127.0.0.1, token, boşta durur
-  /multi-agent:office-on      Ofis panelini tarayıcıda aç: çalışan ajanlar, sohbetler, defter, koşular
+  /multi-agent:office-on      Ofisi tarayıcıda aç: canlı koşular ve ajanlar, PR'lar, anahtarlar, hafıza, sistem, işler; gerisini oryantasyon odası anlatır
   /multi-agent:office-status  Panel çalışıyor mu, adresi (token asla), son işlemleri
-  /multi-agent:office-off     Paneli hemen kapat (boşta kalınca kendisi de kapanır)
+  /multi-agent:office-off     Panelin sunucusunu durdur (sen durdurana kadar çalışır)
 
 Post-Hoc & Side-Channel:
 

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: