Train R: identifier probe, find/stats --by, explain-target JSON, phrase factor (opt-in), harness-check, docs, embedded-core W1 guardrails - #8148

Area train R: seven queued pull requests merged unchanged, in order, on top of current master, so they land in one merge slot and one full test pass (GBRA-108's consolidation policy).

{
  "schema_version": 1,
  "pr": 8148,
  "head": "7a600001735d4005d28123751237ef4998c776e2",
  "version": "0.60.575.0",
  "base": "master",
  "gate": {
    "train-r": {
      "pass": 4025,
      "fail": 77,
      "skip": 9
    }
  },
  "session_kind": "unattended",
  "head_tree": "ac6bc56ad7b448cb1b49afd6de8ca2b90d673d1f",
  "product_patch_id": "d6c601ef46ae513070e50eb0f20b02a9f1dcc749",
  "gstack_version": "1.96.0.0",
  "review_depth": {
    "depth": "full",
    "class": "gate",
    "runtime_lines": 3176,
    "rules": "374e8bedc8e587f2",
    "base": "019f8fc3414a79f1f6657563edb9df1be4f31c86",
    "registry": "019f8fc3414a79f1f6657563edb9df1be4f31c86",
    "gate_scan": {
      "tagged": 4,
      "head": "7a600001735d4005d28123751237ef4998c776e2"
    },
    "reasons": [
      "gate-class",
      "risk:money",
      "risk:secret",
      "risk:security",
      "risk:data",
      "runtime=3176"
    ],
    "risk": [
      "money",
      "secret",
      "security",
      "data"
    ],
    "mode": "panel"
  },
  "pregate": "requires-remote cleared @ac6bc56ad7b4 (7 checks, current for 7a600001735d)",
  "requires_remote": [
    "macos-validation.yml/macos-26: https://github.com/garrytan/gbrain/actions/runs/41929815424/attempts/1",
    "native-locks.yml/native: https://github.com/garrytan/gbrain/actions/runs/41926783818/attempts/1",
    "pregate.json/remote_gate: remote-gate tree=ac6bc56ad7b4 tests=69688 receipt=/home/user/.capy/work/gbra294/ship2/pregate-remote.log sha256=b2f30b484cab"
  ],
  "issues": {
    "fixes": [
      7175,
      7191,
      7192,
      7491,
      7492,
      7972
    ],
    "refs": [
      1794,
      7198,
      7233,
      7497,
      7593,
      7609,
      7673,
      7787,
      8098
    ],
    "flakes": []
  },
  "docs": {
    "status": "current",
    "scope": "AGENTS.md, BOOTSTRAP_FOR_AGENTS.md, CLAUDE.md, CONTRIBUTING.md, INSTALL_FOR_AGENTS.md, README.md, docs/, llms.txt, skills/ (diff-read of the 174 changed files)"
  },
  "review_loop": {
    "passes": 1,
    "blocking_found": 2,
    "deferred": 0,
    "noted": 0,
    "fixed": 4,
    "scope": "frozen",
    "fix_checks": 2,
    "rounds": 3,
    "ledgers_read": 3,
    "unbound": 2,
    "dispatches": {
      "specialist": 3,
      "red-team": 1
    }
  },
  "review_loop_exception": {
    "accepted_by": "GBRA-108 (GBrain Minder)",
    "date": "2026-11-04",
    "via": "a-30c412c3d001",
    "reason": "granted one scoped fix-check for the two outside-voice CRITICALs; the fix-check found no blocker; the exports golden was regenerated afterwards for the widened onKeywordIncomplete union it reviewed",
    "fix_check": {
      "head": "2410cddf43182d834e096f06e4a75203a3d30c45",
      "findings": 4
    }
  },
  "review_targeted": {
    "classes": [
      "money",
      "gate",
      "secret"
    ],
    "rules": "15cc5c485da5af30",
    "brief_sha": "7f92a0d0a8319c3c0e076fb3b1a4689c45120b2be2c14dfc7d4cb03aafa9d6a5",
    "product_patch_id": "d6c601ef46ae513070e50eb0f20b02a9f1dcc749",
    "status": "done",
    "findings": 2,
    "raised_by": "targeted"
  },
  "review_exclude": {
    "source": "origin/master@019f8fc3414a",
    "patterns": [
      "docs/**",
      "test/fixtures/goldens/**"
    ],
    "applied": [
      "docs/**",
      "test/fixtures/goldens/**"
    ],
    "excluded": 14,
    "excluded_bytes": 1347019,
    "kept": 13,
    "gate_tagged": [],
    "patterns_sha256": "19818beb6b21b5c9a857948db2c3d8bbc2aa719704441fc5d045f98f4573f354",
    "list_sha256": "146ba56752a9d61f633b5202ffbcd28bbe8a1538b6c0052bd7693687f62fa090",
    "digest": "5c4e50fb5122cc689b738da00b0f84f349705046c4a3e6caa566459dc4750f2c"
  }
}

Constituents

Includes #7497 @ 6ee8d2f (search: identifier probe, slug handles, coverage notice by token and class)
Includes #7233 @ 7421fb8 (gbrain find / find_pages, stats --by source,type)
Includes #7673 @ 9046769 (advisory harness-check workflow)
Includes #7198 @ 11edbb1 (--explain-target cause in CLI JSON; opt-in keyword phrase factor, off by default)
Includes #7609 @ 562fb56 (docs: git-canonical guide and the week's catch-up)
Includes #7787 @ 3257cee (docs: page anatomy, where your memory lives, entity-scoped facts)
Includes #8098 @ 642b4a7 (embedded-core W1 guardrails)

Closes #7491
Closes #7492
Closes #7972
Closes #7191
Closes #7192
Closes #7175

Each constituent is a --no-ff merge commit of its exact head. Nothing was dropped. The constituent PRs close once this lands.

What the train itself changes

The merges needed these resolutions and follow-ups on the combined tree; none changes a constituent's behavior:

• CHANGELOG: one combined ## [Unreleased] entry for all seven (the version is picked at the slot). test(embedded-core): W1 guardrails: world-reads ratchet, two-engine suite, hermeticity, upgrade harness (GBRA-248) #8098's one-word correction to the 0.60.524.0 entry (gbrain trust review --accept-all) is applied.
• fix(search): identifier probe and slug handles in the keyword arm, rare words for long questions, coverage notice by token and class (#7491, #7492) #7497 × master: agent-contract.md keeps master's lines plus fix(search): identifier probe and slug handles in the keyword arm, rare words for long questions, coverage notice by token and class (#7491, #7492) #7497's search: projection_pending coverage counts unrelated image pages by substring and tells agents to wait for indexing #7492 sentence. The pglite-engine.ts imports are combined. fix(search): identifier probe and slug handles in the keyword arm, rare words for long questions, coverage notice by token and class (#7491, #7492) #7497's whois_exact_identity notice row was already on master (0.60.435.0), so only its two new rows were added.
• feat(find,stats): gbrain find / find_pages and stats --by source,type with alias collapse (#7191) #7233 × master: the brain-first lookup table replaces the old retrieval section, and keeps master's "never send stderr to /dev/null" rule and the identity-exact-match section. eligibility/registry.ts keeps both find_pages and whois. Generated artifacts (regen:all, plugin trees, the lookup-table copies, the vendored bootstrap template) are regenerated.
• search/query: explain_target cause in CLI --json (#7192); opt-in keyword phrase factor (#7175) #7198 × fix(search): identifier probe and slug handles in the keyword arm, rare words for long questions, coverage notice by token and class (#7491, #7492) #7497: the import lines are combined so keywordPhraseFactorSql sits next to the identifier-probe and handle imports. The phrase factor rides the same keyword statement the probe re-runs.
• Goldens: exports/types.json gains image_arm (fix(search): identifier probe and slug handles in the keyword arm, rare words for long questions, coverage notice by token and class (#7491, #7492) #7497's field). sql-text/pages.json re-hashes feat(find,stats): gbrain find / find_pages and stats --by source,type with alias collapse (#7191) #7233's find/stats --by statements, which now carry master's caller-aware private-page predicate (pageReadFilter → privatePagesFilterForCaller, v0.60.527.0 feat(auth): per-principal private_pages grant — granted_sources reads private pages in explicitly granted sources (GBRA-156) #7593). rls-scope-inventory.json and its test count searchKeyword's second scoped read, the slug-handle statement from fix(search): identifier probe and slug handles in the keyword arm, rare words for long questions, coverage notice by token and class (#7491, #7492) #7497 (36 call sites).
• Module-size ceilings were raised to the combined line counts, with each raise noted: engine.ts +6 and operations.ts +1 for feat(find,stats): gbrain find / find_pages and stats --by source,type with alias collapse (#7191) #7233; mode.ts +12 for search/query: explain_target cause in CLI --json (#7192); opt-in keyword phrase factor (#7175) #7198; types.ts and behavior-change-notice.ts for fix(search): identifier probe and slug handles in the keyword arm, rare words for long questions, coverage notice by token and class (#7491, #7492) #7497 and search/query: explain_target cause in CLI --json (#7192); opt-in keyword phrase factor (#7175) #7198. main.ts and postgres-engine.ts were raised to fit both.

Verification (train head)

• bun run typecheck passes, and so do regen:all (nothing stale), check:module-size and check-bootstrap-templates.sh.
• Targeted unit suites, 37 files: 1011 pass after the inventory fix. These cover the constituents' own tests, the CLI, export and SQL-text goldens, behavior-change notices, ci-pr-scope/ci-runner-routing, check-core-world-reads and build-llms. The serial suites (identifier-probe, slug-handles, two-engine-isolation, the dispatch meta suites) also pass.
• Postgres E2E (local pgvector pg16) passes: identifier-probe, slug-handles, coverage-token-class-7492, page-lookup-7191, legacy-chunk-privacy, mcp-search-transport-matrix, two-engine-isolation, keyword-arm-ranking, the schema-catalog and doctor-json goldens, and v0.60.527.0 feat(auth): per-principal private_pages grant — granted_sources reads private pages in explicitly granted sources (GBRA-156) #7593's private-pages-grant and serve-http member-token suites.

Not stamped. GBRA-108 calls the slot; /ship, the full-ci label and the pregate gate run then.

What changed

The three review blockers' tests: red with each fix reverted (before), green on this head on PGLite and Postgres (after).

--- Before · before.txt · captured output
+++ After · after.txt · captured output
+(pass) slug handles in keyword search (pglite) > <handle> -term excludes a page that contains the term, in keyword mode and the hybrid keyword arm
+(pass) slug handles in keyword search (pglite) > a quoted phrase beside a handle is respected, and so are the other words of a strict match
+(pass) slug handles in keyword search (postgres) > <handle> -term excludes a page that contains the term, in keyword mode and the hybrid keyword arm
+(pass) slug handles in keyword search (postgres) > a quoted phrase beside a handle is respected, and so are the other words of a strict match
+(pass) identifier probe (pglite) > scope and visibility (remote caller) > a probe that times out stamps the result degraded, never a silent miss
-(fail) slug handles in keyword search (pglite) > <handle> -term excludes a page that contains the term, in keyword mode and the hybrid keyword arm
-(fail) slug handles in keyword search (pglite) > a quoted phrase beside a handle is respected, and so are the other words of a strict match
-(fail) identifier probe (pglite) > scope and visibility (remote caller) > a probe that times out stamps the result degraded, never a silent miss
 

Why

Seven queued pull requests in the search, lookup and docs area were waiting for separate merge slots, and each slot costs a full test pass. This train lands them in one slot and one version. The outside reviewer found two real search bugs on the combined tree, so a query like alice-example -draft no longer returns the page that contains "draft", and an identifier probe that times out now stamps the result degraded instead of looking like a clean miss.

Blast radius

The changes reach the keyword arm of search and query, the new find_pages and stats --by reads, CLI JSON for --explain-target, and the exported SearchOpts.onKeywordIncomplete type. The slug-handle shortcut now runs only for a standalone handle or an OR list of handles, so every other query takes the strict keyword statement it took before this train. A probe or handle-read failure reports through the existing HybridSearchMeta.degraded and degradedStampFor path, which the full suite exercised on this exact tree (Test 41926783818, 61606 tests, 0 failed; E2E 41926788094, 8082 tests, 0 failed): script ran.

Approvals

Approved: yes (record r-83bf6e4de8eb). The full approval record stays private: this repository is public or its visibility is unknown.

Summary

Area train R: seven queued pull requests merged unchanged, in order, on top of current master, so they land in one merge slot and one full test pass.

Includes #7497 @ 6ee8d2f (search: identifier probe, slug handles, coverage notice by token and class)
Includes #7233 @ 7421fb8 (gbrain find / find_pages, stats --by source,type)
Includes #7673 @ 9046769 (advisory harness-check workflow)
Includes #7198 @ 11edbb1 (--explain-target cause in CLI JSON; opt-in keyword phrase factor, off by default)
Includes #7609 @ 562fb56 (docs: git-canonical guide and the week's catch-up)
Includes #7787 @ 3257cee (docs: page anatomy, where your memory lives, entity-scoped facts)
Includes #8098 @ 642b4a7 (embedded-core W1 guardrails)

Each constituent is a --no-ff merge commit of its exact head, and nothing was dropped. On top of the merges, the train resolves the combined CHANGELOG, imports and goldens, and raises module-size ceilings to the combined line counts. The ship run then fixed what review found: needsEngineScope short-circuits when both handles name the same engine (GBRA-294's fix), the --explain-target retry asks before a paid call and keeps array and object arguments, slug handles expand only for a standalone handle or an OR list of handles, and a failed identifier probe or handle read is reported as degraded keyword retrieval. The exports golden test/fixtures/goldens/exports/types.json was regenerated because onKeywordIncomplete's reason widened to 'candidate_budget' | 'timeout' | 'provider_error'; the other lines in that diff are the same literal unions printed in a different order.

Test Coverage

The new code paths have tests, and each fix's test was shown to fail with its fix reverted: test/engine-scope-identity.test.ts (engine-scope identity), test/search/explain-target-cli-json-7192.test.ts (2 cases), test/search/slug-handles.serial.test.ts (<handle> -term, a quoted phrase beside a handle) and test/search/identifier-probe.serial.test.ts (a forced probe timeout reaches meta.degraded, retrieval.degraded and the CLI stamp).

Tests ran: train-r count unavailable (the lane script reports per suite: unit 3849 pass, 7 skip, 77 fail, all 77 in test/search files that share state when the directory runs in one process and pass in their own process, which is how CI runs them; serial 56 pass, 0 fail; Postgres E2E 120 pass, 2 skip, 0 fail).

Pre-Landing Review

Pass 1 (specialists for testing, security and state machines, plus red team): 2 informational findings in src/core/search/explain-target.ts, both fixed. Round 2 fix-check: no findings. Step 11 voices: the outside voice (openai/gpt-6.1-sol) raised 2 blocking findings, slug handles that ignored negations and quoted phrases, and probe failures swallowed as an empty result. Both were fixed under the owner's grant of one scoped fix-check, which found no blocker.

REVIEW_LOOP: passes=1 blocking_found=2 deferred=0 noted=0 fixed=4 scope=frozen unbound=2 ledgers_read=3 fix_checks=2 dispatches=4

Review-loop exception: accepted by GBRA-108 (GBrain Minder) 2026-11-04 via a-30c412c3d001: granted one scoped fix-check for the two outside-voice CRITICALs; the fix-check found no blocker; the exports golden was regenerated afterwards for the widened onKeywordIncomplete union it reviewed (fix-check at 2410cdd, 4 findings)

Gate edits: 118 listed, 29 read, 0 findings — 0 kept, 0 restored, 0 open

Outside review: completed (openai/gpt-6.1-sol, medium); both findings fixed.

Review notes

• Fix-check note: a quoted OR alternative drops the handle (src/core/search/keyword-handles.ts). Filed search: quoted OR alternatives drop slug handles after the #8148 fix; skipped probe reports provider_error #8618.
• Fix-check note: a skipped probe reports provider_error rather than its own reason; the result is still stamped degraded (src/core/search/keyword-identifier-probe.ts). Filed search: quoted OR alternatives drop slug handles after the #8148 fix; skipped probe reports provider_error #8618.
• Native adversarial: a one-digit #N probe and hyphenated words read as handles (search: identifier probe fires on one-digit #N and slug handles match ordinary hyphenated words #8611); explain-target edge cases (explain-target: three edge cases (embedding column, leading-dash query, collapsed reason source) #8612); countPagesBy consistency (find/stats --by: countPagesBy totals can disagree with group sums under concurrent writes #8613); core-world-reads --prune (check-core-world-reads: --prune exits 0 with growth violations; scanner misses process['env'] and destructured env #8614).
• Targeted: the advisory harness-check workflow's trial and tool allowlist, and its read-only token (harness-check: a missing scoped trial reads as zero cross-scope pages; read token on the git command line #8609).
• Run 1 notes still open: plain get_stats under --as (stats --as <member> without --by reports host-wide counts #8608), --as behaviour in context.ts (--as <member> preview is looser than the member's remote view (chunk safety, takes holders) #8610).

Exploratory QA

Pass. Captures 005 (the import pair, 42 pass, 0 fail) and 006 (real CLI init, import and search on a repo-less PGLite brain) ran on current inputs.

Design Review

No frontend files changed, so design review was skipped.

Eval Results

No prompt-related files changed, so evals were skipped.

Review bot comments

No review bot comments.

Scope Drift

Scope Check: CLEAN

Plan Completion

Plan completion audit: not run (no plan bound).

Issues

Fixes #7175
Fixes #7191
Fixes #7192
Fixes #7491
Fixes #7492
Fixes #7972
Refs #1794
Refs #7198
Refs #7233
Refs #7497
Refs #7593
Refs #7609
Refs #7673
Refs #7787
Refs #8098
Refs p1/outside-voice#1
Refs p1/outside-voice#2
Refs p1/red-team#1
Refs p1/red-team#2
Refs p1/specialist-batched#1
Refs p1/specialist-batched#2
Refs p1/specialist-batched#3

Documentation

Status: current. The audit made no edits and found no blockers.

Scope: base 019f8fc to head 7a60000 on capy/train-r-20261101, covering 174 changed files. Staged, unstaged and untracked content was empty. The branch already updates 34 docs and authored templates for the new surface: AGENTS.md, CLAUDE.md, README.md, the guides, the architecture and key-files docs, the plugin docs, skills and bootstrap templates. I diff-read those changed docs and spot-checked the public surface (find_pages, gbrain find, stats --by, the generated CLI flag registry) against them.

Documentation health:

• README.md: current (the two-engines, canonical-files and brain/source paragraphs and the new guide links are consistent with the diff)
• CLAUDE.md: current
• AGENTS.md: current (diff-read only)
• CHANGELOG.md: current (top entry 0.60.575.0, not modified)
• docs/TOOL_CATALOG.md: current (165 tools, including the find_pages row)
• docs/mcp/TOOL_REFERENCE.md: current (starter surface only; find_pages is not a starter op)
• docs/architecture/key-files/engines-2.md: current (documents find_pages, stats-by, page-lookup and page-counts)
• llms.txt and llms-full.txt: current (diff-read only)
• TODOS.md: not audited (out of scope)

Coverage debt: none found. Regeneration reported to the parent: none required by this audit. Diagram drift: none observed.

Test plan

• Full suite, Test run 41926783818 on tree ac6bc56a: 61606 tests, 0 failed
• Full E2E, E2E run 41926788094 on tree ac6bc56a: 8082 tests, 0 failed
• macOS 26 validation run 41929815424: passed
• L=/home/user/.capy/work/gbra294/lanes-ship2 bash /home/user/.capy/work/gbra294/lanes.sh: serial 56 pass, 0 fail; Postgres E2E 120 pass, 0 fail; unit failures only in test/search directory-mode runs, each file green in its own process