@mmerterden/multi-agent-pipeline 20.33.0 → 20.35.0

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-remote-protocol.md

@@ -0,0 +1,166 @@
+# Office remote protocol
+
+<!-- toc -->
+- [Parts and trust](#parts-and-trust)
+- [Account](#account)
+- [Pairing](#pairing)
+- [Transport](#transport)
+- [Passkey tiers](#passkey-tiers)
+- [Audit](#audit)
+- [Decisions](#decisions)
+- [To verify on a real phone](#to-verify-on-a-real-phone)
+<!-- /toc -->
+
+How a phone reaches the phone routes of the local contract server through a
+relay on the user's site, without the machine opening a port and without the
+relay or the site being able to read a payload or act on their own.
+
+The request layer exists and is not changed here: every phone request is signed
+with the device's Ed25519 key (`MA-PHONE-SIG-1`), and `_phone-auth.mjs` checks
+the device, the window, the nonce, the scopes and writes the audit line
+(`phone-api.md`). This document adds what leaving the machine requires: an
+end-to-end layer around those requests, the relay that carries it, pairing that
+enrols the device through the existing registry, and a passkey on top of the
+device signature for the routes that change something.
+
+## Parts and trust
+
+| Part | Runs | Holds | Trusted for |
+|---|---|---|---|
+| Phone page | the phone browser, on the site origin (behind the owner session) | the device signing key and the session key pair (non-extractable WebCrypto), a passkey | showing data, asking the user, signing |
+| Site + relay | the user's site (serverless functions + database) | the owner's account, pairing records, ciphertext queues | delivering ciphertext, nothing else |
+| Machine client | the user's machine, started with the office | the machine key pair, the audit of remote frames | decrypting, checking the passkey tier, forwarding to the local server |
+| Local server | the user's machine, 127.0.0.1 only | the device registry, nonces, audit | verifying the device signature and executing phone routes, as today |
+
+The relay and its database are treated as compromised: they can drop, delay,
+replay and reorder frames. None of that lets them read a frame, forge a device
+signature or pass the passkey check. The phone page itself is the trust anchor
+on the phone side, as for any web app holding keys: a site that serves a
+modified page can act as the phone. The page therefore loads no third-party
+script, runs under a strict CSP and keeps its keys non-extractable, and the
+machine still applies every check of its own (tiers, routes, counters).
+
+## Account
+
+The first release serves the owner's account only and reuses the site's
+existing owner session rather than adding a second login: the phone page and
+every phone relay route require it, and state-changing routes also require a
+same-origin request. The session only lets the phone use the relay for its
+own pairings; it never authorizes an action on the machine, which still
+checks the device signature, the passkey tier and the route itself. Invited
+accounts are a later step.
+
+## Pairing
+
+`office-pair.mjs` runs the machine side; every subcommand refuses an
+unattended run. The user runs it in their own terminal (`! node
+~/.claude/scripts/office-pair.mjs start`), so nothing it shows lands in a
+transcript.
+
+1. `start [--relay <origin>]` creates the machine key pair (P-256) on first
+   use and a relay token (256 bits) kept in `<phone dir>/remote.json` (0600),
+   a pairing id and a one-time secret (128 bits, valid 10 minutes). The relay
+   origin comes from `prefs.global.office.remote.relayUrl` or the flag, never
+   from the code; it is https, or http on the loopback. The relay receives the
+   pairing id, the machine public key, the expiry and the SHA-256 of the relay
+   token, never the token itself.
+2. The QR code is drawn by the dependency-free encoder in `lib/qr-code.mjs`
+   into a 0600 page (`default-src 'none'`) in a 0700 directory and opened in
+   the local browser; the secret is never printed. It holds
+   `<origin>/office/pair#p=<pairing id>&s=<secret>&k=<machine public key>`.
+   A browser never sends the fragment to a server, so the relay neither sees
+   the secret nor can swap the machine key.
+3. The phone, signed in, scans it, creates its Ed25519 device key and its P-256
+   session key, registers a passkey (WebAuthn `create`, user verification
+   required) and sends, sealed with a key that mixes the ECDH secret with the
+   pairing secret: the device name and public key, and the passkey credential
+   id, public key (`getPublicKey()`, SPKI), rp id and origin.
+4. `wait` polls the relay with the token, opens the message, refuses a passkey
+   whose origin is not the relay origin or whose rp id is not its host, and
+   prints the six-digit code derived from both public keys and a fingerprint
+   of the machine key. The phone shows the same code and fingerprint, and
+   accepts the pairing only after its user confirms on the phone that both
+   match, so a link someone else registered cannot pair the phone with their
+   machine.
+5. `confirm <code>` takes the code as the phone shows it. A mismatch drops the
+   pairing (one attempt). A match enrols the device with
+   `phone-devices.mjs add` (scopes `read,answer`; `launch` stays a separate
+   local switch), stores the session key and passkey beside it, and tells the
+   relay to start delivering for the pairing. That call carries the first
+   machine-to-phone frame (counter 1), sealed with the pairing's keys, holding
+   the device id the phone signs its requests with; the relay cannot alter it.
+6. Revoke: `phone-devices.mjs revoke <id>` on the machine also drops the
+   device's remote keys; the site can stop delivering for a pairing. Either
+   alone ends control.
+
+## Transport
+
+- The machine client polls the relay over HTTPS (long poll, 25 s) and posts
+  responses. No inbound port, no tunnel, no funnel.
+- A frame is `{method, target, headers, body}` (request) or
+  `{status, headers, body}` (response), as `phone-api.md` specifies, sealed
+  with AES-256-GCM. The keys come from ECDH between the phone session key and
+  the machine key, through HKDF-SHA-256 with the pairing id as salt, one key
+  per direction; the nonce is a per-direction counter, and a frame whose
+  counter does not exceed the last one accepted is dropped.
+- The relay stores `{pairingId, direction, counter, ciphertext, expiresAt}` in
+  a table only the service role reaches, and deletes a row on delivery or
+  after 10 minutes.
+- The machine client takes a target only in the canonical form the local
+  server routes on (no encoded dot segment, backslash or fragment), so the
+  tier and the route prefix are judged on the path the server executes. Only
+  one client runs at a time (a lock file), and each poll writes its counters
+  onto the config as it is on disk, so a revoke made meanwhile is kept.
+- The machine client forwards only targets under `/v1/phone/`, never adds an
+  `Authorization` header, and rewrites `Host` to the loopback address; the
+  local server's own checks then apply unchanged.
+- Remote is off by default: the client runs only while the office is on and
+  a device is paired; `office-off` stops it.
+
+## Passkey tiers
+
+The device signature proves which phone sent a request; the passkey proves the
+user was holding it. Each phone route carries a tier from the route table:
+
+| Tier | Phone routes | Passkey |
+|---|---|---|
+| read | `GET /v1/phone/runs`, `GET /v1/phone/runs/{id}` | one at session open; the session locks after 5 minutes idle |
+| low | `POST /v1/phone/runs/{id}/answer`, a canned steer | within 2 minutes of the last passkey (configurable down to every time) |
+| high | `POST /v1/phone/launch` and any later route that changes code or writes to a host | every time, bound to the request |
+
+For a passkey-bound request the phone sends `X-MA-Passkey` with a WebAuthn
+assertion whose challenge is SHA-256 of the request's canonical signed text.
+The machine verifies, before the request reaches the local server: the rp id
+hash and origin match the paired ones, the user verified flag is set, the
+signature verifies with the paired credential key, and the sign count (when the
+authenticator keeps one) has grown. Steering from the phone is a canned
+template chosen by id and expanded on the machine; free-text steering, widening
+actions (autopilot on, stack, routine delete, host permissions) and merges stay
+desktop routes.
+
+## Audit
+
+The local server keeps its per-request audit as today. The machine client adds
+`<phone dir>/remote-frames.jsonl` (0600): time, device, counter,
+target path without query, tier, passkey verdict and the reason of a drop.
+Never a body, a header value or a signature.
+
+## Decisions
+
+1. **The machine client ships in the public pipeline**, inert until
+   `office-pair` pairs a device. The relay URL comes from prefs or the pairing
+   QR, never from the code.
+2. **Steering from the phone takes canned templates only**, chosen by id and
+   expanded on the machine.
+3. **The first release serves the owner's account only**; invites follow as a
+   separate step.
+4. **The relay queue is a short-lived table in the site's database**: ciphertext
+   only, deleted on delivery or after 10 minutes, service role only.
+
+## To verify on a real phone
+
+WebCrypto Ed25519 and non-extractable P-256 keys in the phone's browser,
+`getPublicKey()` on the passkey registration response, and the long-poll
+interval against the site's function time limit. The design falls back to
+P-256 ECDSA for the device key if Ed25519 is missing, which `_phone-auth.mjs`
+would then accept as a second key type.

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" |
@@ -66,7 +66,7 @@ not mitigated here.
 | 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` |
+| 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. `GET /v1/prs/reach` (local-only) asks gh for the changed file paths of at most 20 GitHub pull requests, three at a time, each with its account's token in the environment; it asks nothing for a repository whose name is not `owner/repo` or that has no graph under `~/.claude/knowledge/<repo name>/`. The paths serve only as keys into the local graph: nothing is read from disk by them and none is returned, only counts. The graph is parsed in a child process, so no other route waits behind it. 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`, `pr-reach.test.mjs`, `office-work.test.mjs` "GET /v1/prs/reach says which pull requests have no graph to measure against" |
 | 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

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,31 @@ 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>`. On a rework pass, `--rejected <triage-output.json> --repo <dir> --rework-base <rev>` (the two come together) adds `rejectedTouched[]` (`rejectedError` when unreadable): each finding triage rejected whose line a hunk of `git diff <rework base>` against the working tree changed, read on the hunk's old side within two lines. Phase 2 acts on accepted findings only, so such a hunk is a fix triage ruled out; it is reported, never fatal. 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)`.
+
+## Rework pass
+
+Rejected findings carry the line numbers of the tree the review read, and every round rewrites `triage-output.json`, so a rework is compared against that round's own base.
+
+1. Before the first rework edit, record the base: `node $HOME/.claude/scripts/rework-base.mjs record --worktree "$WORKTREE" --iteration "$(jq '.reviewIterations | length' "$STATE_FILE")"`. One file per round, `.pipeline/rework-base-<N>`; a resumed re-entry of the same round keeps the base it started from.
+2. In Step 3.7, after the normal gate:
+
+```bash
+REWORK_BASE=$(node $HOME/.claude/scripts/rework-base.mjs get --worktree "$WORKTREE" --iteration "$(jq '.reviewIterations | length' "$STATE_FILE")")
+node $HOME/.claude/scripts/scope-check-gate.mjs --check "$WORKTREE/.pipeline/scope-check.json" --diff-files /dev/null --advisory \
+  --rejected "$WORKTREE/triage-output.json" --repo "$WORKTREE" --rework-base "$REWORK_BASE"
+```
+
+Each `rejectedTouched[]` entry is an edit to lines triage ruled out: revert that hunk unless an accepted finding needs it, and say which in the record's reason. Log `dev.rework_rejected_touch=<n>`.
+
+## 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/verify-by-test.md

@@ -21,6 +21,16 @@
 
 Downgrades go to `deferred`, never `rejected`: triage judged the issue real, and deferred items surface in the Phase 5 report for a human eye.
 
+## Repeat runs
+
+Phase 2's stability rule keeps each run of the new and changed tests as `.pipeline/repeat-<k>.junit.xml` (k = 1..N) and judges them together:
+
+```bash
+node $HOME/.claude/scripts/test-stability-gate.mjs --dir "$WORKTREE/.pipeline" --expect N
+```
+
+Exit 1 means a missing run, a flake (`flaky[]`: outcomes that differ across runs) or a test that failed every time; the step is not GREEN. A runner that writes no JUnit XML (xcodebuild) has each run exported with `xcrun xcresulttool` first, or logs `test.stability=unverifiable` and says so in the Phase 5 report.
+
 ## Red-test handoff to Phase 3
 
 `state.reviewIterations[-1].verifyByTest = { attempted, confirmed, downgraded, inconclusive, redTests: [{file, testRef, issue}] }`. On the Phase 3 re-entry, each `redTests[]` entry IS the RED step of the rework TDD cycle for its finding: the reflection prompt instructs "a failing repro test already exists at <testRef>; make it green; do not delete or weaken it." The dev agent must not write a duplicate failing test for those findings.

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

@@ -1,5 +1,12 @@
 ## Keychain Token Registry
 
+<!-- toc -->
+- [Keychain Token Registry](#keychain-token-registry)
+- [Rule 1  -  Never prompt for a token *value* mid-run](#rule-1---never-prompt-for-a-token-value-mid-run)
+- [Rule 2  -  MUST: never ask the user for what a mapped credential can fetch (BLOCKING)](#rule-2---must-never-ask-the-user-for-what-a-mapped-credential-can-fetch-blocking)
+- [Credential store mechanics](#credential-store-mechanics)
+<!-- /toc -->
+
 > **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
 
 Tokens live in the macOS Keychain. Key names are resolved via **preferences mapping**  -  never hardcoded.

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: