morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #6996] [MERGED] feat(guidance): search installed workflow sections #7559

New issue

Closed

opened 2026-11-03 13:38:42 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-03 13:38:42 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/6996
Author: @Deepak-Kambala
Created: 10/24/2026
Status: ✅ Merged
Merged: 10/29/2026
Merged by: @gensokyo-dev

Base: main ← Head: feat/6916-guidance-search

📝 Commits (10+)

ff9bfe5 feat(guidance): search bundled REA workflow guidance
7de4dce fix(guidance): address review findings
ef0740b test(guidance): fix boundary and dispatcher coverage
3465567 test(setup): use supported doctor fixture runtime
e2a7876 Merge remote-tracking branch 'upstream/main' into feat/6916-guidance-search
9638b6d fix(guidance): resolve CI conformance, coverage, and review findings
cb60adf feat(guidance): add bounded workflow search and section retrieval
c608920 chore(guidance): align workflow search with current main
b667c16 fix(guidance): own complete requests through shutdown
465a262 test(guidance): bound lifecycle gates and join failed work

📊 Changes

33 files changed (+2117 additions, -41 deletions)

View changed files

📝 docs/mcp-contracts.md (+6 -4)
📝 docs/mcp-prompts.md (+20 -0)
📝 scripts/lib/development-tests.mjs (+5 -0)
📝 scripts/rea.mjs (+5 -5)
📝 scripts/run-development-tests.mjs (+4 -2)
➕ src/application/GuidanceAccess.boundaries.test.ts (+139 -0)
➕ src/application/GuidanceAccess.lifecycle.test.ts (+183 -0)
➕ src/application/GuidanceAccess.test.ts (+320 -0)
➕ src/application/GuidanceAccess.ts (+602 -0)
➕ src/application/GuidanceSections.ts (+123 -0)
📝 src/application/SetupSkill.ts (+10 -4)
📝 src/cli.ts (+19 -1)
➕ src/cli/guidanceCommands.ts (+120 -0)
📝 src/cliCommandNames.ts (+1 -0)
📝 src/contracts/applicationToolContracts.ts (+31 -0)
➕ src/contracts/guidanceContracts.ts (+91 -0)
📝 src/contracts/toolEffects.ts (+4 -0)
📝 src/server/registerApplicationTools.ts (+2 -0)
📝 src/server/registerApplicationTools/types.ts (+1 -1)
➕ src/server/registerGuidanceTools.ts (+45 -0)

...and 13 more files

📄 Description

Summary

Fixes #6916. Analysts can find a workflow section with rea guidance --query "exact JavaScript module" or MCP search_guidance, then retrieve the selected section by locator with --action read / read_guidance_section. This continuation preserves the contributor history and integrates main f25d1e3e9.

Search reads only the eight installed MANAGED_SKILL_FILES; responses identify documentation rather than analysis results or Evidence. No target/provider is required or executed and no arbitrary directory or external service is accessed. This stays within the existing local documentation boundary.

Shared implementation and bounds

CLI/MCP share application search/retrieval and one ATX section parser. Every non-generic query word must occur in a section; generic-only or unmatched subjects return scoped no_matches, without a capability claim. Ranking and query/bundle-bound paging are deterministic. Bundle bytes are re-read on every operation; changed content produces stale locators/cursors. No new cache is retained.

Limits: 1 MiB/file, 4 MiB/bundle, 4,096 sections and 25,165,824 expanded UTF-16 code units. A line scan counts headings and a stack establishes spans before section strings/ranked objects are allocated. Search pages contain at most 20 entries with 500-code-unit excerpts; read returns the selected section.
Locators contain bundle, fixed guide, ordinal and complete-section SHA-256. The section hash already covers its heading, so the heading is not duplicated in the identity. Long headings remain readable within the 4,096-character input contract.
ATX closing hashes require whitespace; literal/escaped hashes, indented headings and empty headings retain their source meaning. Title cleanup scans each end directly instead of using suffix regexes with quadratic blank-run behavior. Ranking computes each section's distinct words once.
Each complete search/read request is admitted once; individual file reads use its child scope. Shutdown waits for later reads and finalization, while failed child cleanup remains owned by the root with its exact descriptor and live lease. New work after shutdown is refused. Deterministic gates reproduce both original shutdown failures and cover overlapping mixed outcomes/retry.
Unreadable/oversized bundles report bundle_unavailable, with no partial index or inferred absence. First-close and retry cleanup failures remain errors carrying the exact live lease. CLI shutdown settles both JavaScript/guidance owners; reusable CLI workers and dispatcher fixtures use the shared cleanup entrypoint. Unrelated Android/browser formatting was excluded.

Executed validation

Linux x64, Node 24.22.1 / npm 11.16.0; head 465a262ee (runtime unchanged from b667c16be):

181 tests pass in 17 focused files on runtime head b667c16be, and again on local candidate 2d389f6c5 merging final head 465a262ee with current main 131fbe075, including public CLI/MCP, advertised schemas, paging/staleness, filesystem/symlink/size bounds, dispatcher/closed-pipe behavior, cleanup retry, mixed close outcomes and reusable CLI workers. Seven original boundary failures and both shutdown regressions were reproduced before their fixes. Final test-only follow-up 465a262ee reruns the four lifecycle tests and type/lint checks; gates now use bounded acknowledgement and unconditional release/join/close. Two temporary negative controls (early operation settlement and failed assertions, including denied cleanup) each produce the expected three failures and exit in about 1.2 s; restored tests pass.
check:fast, formatting, git diff --check, docs (9 README tests), catalog validation, and discovery (2,824 files exactly once) pass. Catalog check ran before the latest main-only integration; final CI checks the merged head.
Real generated bundle: 8 guides, 152,210 bytes, 69 ATX headings. Independent markdown-it-py 4.0.0/CommonMark heading maps verify returned titles and full section content. CLI search/read and SDK 2.3.1 stdio MCP select the expected exact-module recipe. Full module pagination retains all 19 results without duplicates, omissions or reordering.
A live MCP test changes an owned generated guide, observes stale locator and continuation responses, restores the exact bytes and confirms successful retrieval again. The unknown-subject/domain-word control returns no matches. The guide backup and all profiling evidence stay outside Git.

CI baseline and current-main verification

CI 40840282556 tests merge df89030ba on main 3503578f9: 21,777 source tests pass /16 skip across 1,172 files. Built shard 8 passes. Shard 5 has one failure in the unchanged bundleComparisonMcp.test.ts:168: it expects a legacy left_bundle_path: ... text substring while validation returns structured field issues. Pure main 3503578f9 reproduces the identical failure (8 pass /1 fail) with npm run test:focused -- tests/boundary/mcp/bundleComparisonMcp.test.ts. Matrix fail-fast cancels the other six shards; they are unverified on this run, not reported as passing. Platform results remain in the linked run. This is the only observed failed test; the operator explicitly authorized bypass for demonstrated main failures.

Current-main candidate 2d389f6c5 (tree 4f2e5359223864fc9876e00e49328fe021ef16e3, parents main 131fbe075 and final head 465a262ee) merges cleanly, passes all 181 focused tests /17 files, type/lint and diff checks. Its updated installed bundle is 152,417 bytes /8 guides /69 headings; independent CommonMark maps, real recipe search/read, all 19 module results and live drift/restore pass again. Greptile gives 5/5 on exact final head, with all eleven threads resolved. Codex could not review the final head because the repository review quota is exhausted.

Completed-task measurements

Before 1af45280e is the original implementation integrated on the same main base; after cb60adf28 includes the fixes. Two alternating/reversed repetitions per revision/workflow, fresh client/server sessions, warm OS caches; compile-cache state not independently controlled. application family and compact input schemas; initialization/instructions, catalog, requests, replies, notifications and both text/structured representations are counted.

Task	Estimated tokens	Elapsed	CPU	Peak family RSS
Before, recipe search + read	272,186	2.084–2.101 s	2.80–2.85 s	454.6–455.3 MiB
After, recipe search + read	272,133	2.121–2.138 s	2.86–3.00 s	454.3–454.5 MiB
Before, all module pages	280,518	2.251–2.339 s	2.96–3.13 s	454.1–455.9 MiB
After, all module pages	280,189	2.265–2.426 s	3.02–3.18 s	453.6–456.5 MiB

The recipe's chosen answer stays the same; requiring complete meaningful-term coverage reduces candidate sections from 41 to 11. Single-word pagination remains identical at 19 entries. Catalog 268,264 → 268,268 estimated tokens; compact locators offset that small addition. These whole-task measurements establish no overall speedup.

After the latest main integration, two more guarded tasks pass: recipe 272,133 tokens /3.632 s /4.72 CPU s /456.3 MiB; pagination 280,189 /3.818 s /4.93 CPU s /456.8 MiB. Historical comparisons remain pinned above. After the lifecycle fix, the same two tasks pass again: recipe 3.987 s /5.22 CPU s /454.7 MiB; paging 4.110 s /5.30 CPU s /453.8 MiB. Token counts remain 272,133 /280,189; no guard stop or surviving process. The live freshness/restore test also passes again.

The latest-main candidate also completes guarded recipe/paging tasks: 272,148 /280,204 tokens; 2.330 /2.496 s; 3.24 /3.42 CPU s; 455.5 /453.4 MiB. Its catalog is 268,283 tokens; updated main accounts for the changed catalog and guide bytes. These are additional observations, not an equivalent-base speed comparison. No guard stops or survivors.

A separate bounded diagnostic found a pre-linear title-cleanup expression took 440 ms for 16K internal spaces; the current complete section parser took 0.037 ms for that input and 0.108 ms at 64K. These have different scopes and are not a whole-workflow speed claim. The million-heading case was source-derived and deliberately not executed; a tiny boundary fixture proves refusal before expansion.

Tokenx 1.3.0 provides transport estimates, not billed model/context tokens. RSS is a 10 ms client/server process-group sum; CPU includes both and excludes the external sampler. A 1.5 GiB family/150 s guard bounds runs; all final measured tasks complete with no guard stops or survivors. Cold caches, full-schema discovery and OS-enforced network denial are unmeasured. One incomplete measurement preflight used the wrong legacy root-union payload shape; it cost 269,925 estimated tokens /3.392 s /4.58 CPU s /452.9 MiB, is retained separately and is not represented as passing. The corrected client follows the advertised SDK projection.

Author readiness

Human owner: @Deepak-Kambala

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/6996 **Author:** [@Deepak-Kambala](https://github.com/Deepak-Kambala) **Created:** 10/24/2026 **Status:** ✅ Merged **Merged:** 10/29/2026 **Merged by:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Base:** `main` ← **Head:** `feat/6916-guidance-search` --- ### 📝 Commits (10+) - [`ff9bfe5`](https://github.com/morluto/rea/commit/ff9bfe508a7915ac1707bca90fffdecf5238c2c4) feat(guidance): search bundled REA workflow guidance - [`7de4dce`](https://github.com/morluto/rea/commit/7de4dce921caa2769dd8767a5baa4bd5d7b4598d) fix(guidance): address review findings - [`ef0740b`](https://github.com/morluto/rea/commit/ef0740ba63407bb23ab9a0b07a40f806af3a8637) test(guidance): fix boundary and dispatcher coverage - [`3465567`](https://github.com/morluto/rea/commit/34655672c8a01d407a4d1fdf5d17c96ed0a62313) test(setup): use supported doctor fixture runtime - [`e2a7876`](https://github.com/morluto/rea/commit/e2a7876eb987986865c3e87d7c0886b9b19dc18e) Merge remote-tracking branch 'upstream/main' into feat/6916-guidance-search - [`9638b6d`](https://github.com/morluto/rea/commit/9638b6d77b5dfb2630397c6fcfb954d2ab9a6e47) fix(guidance): resolve CI conformance, coverage, and review findings - [`cb60adf`](https://github.com/morluto/rea/commit/cb60adf28f8853b9c612fa3acaf755f517351c55) feat(guidance): add bounded workflow search and section retrieval - [`c608920`](https://github.com/morluto/rea/commit/c60892045cc5924a467c17d3059ec9404e5050b3) chore(guidance): align workflow search with current main - [`b667c16`](https://github.com/morluto/rea/commit/b667c16be04866a69e28398b26d7015ece2e2ae0) fix(guidance): own complete requests through shutdown - [`465a262`](https://github.com/morluto/rea/commit/465a262eeca8fa5402a5a951246269058a5d64f8) test(guidance): bound lifecycle gates and join failed work ### 📊 Changes **33 files changed** (+2117 additions, -41 deletions) <details> <summary>View changed files</summary> 📝 `docs/mcp-contracts.md` (+6 -4) 📝 `docs/mcp-prompts.md` (+20 -0) 📝 `scripts/lib/development-tests.mjs` (+5 -0) 📝 `scripts/rea.mjs` (+5 -5) 📝 `scripts/run-development-tests.mjs` (+4 -2) ➕ `src/application/GuidanceAccess.boundaries.test.ts` (+139 -0) ➕ `src/application/GuidanceAccess.lifecycle.test.ts` (+183 -0) ➕ `src/application/GuidanceAccess.test.ts` (+320 -0) ➕ `src/application/GuidanceAccess.ts` (+602 -0) ➕ `src/application/GuidanceSections.ts` (+123 -0) 📝 `src/application/SetupSkill.ts` (+10 -4) 📝 `src/cli.ts` (+19 -1) ➕ `src/cli/guidanceCommands.ts` (+120 -0) 📝 `src/cliCommandNames.ts` (+1 -0) 📝 `src/contracts/applicationToolContracts.ts` (+31 -0) ➕ `src/contracts/guidanceContracts.ts` (+91 -0) 📝 `src/contracts/toolEffects.ts` (+4 -0) 📝 `src/server/registerApplicationTools.ts` (+2 -0) 📝 `src/server/registerApplicationTools/types.ts` (+1 -1) ➕ `src/server/registerGuidanceTools.ts` (+45 -0) _...and 13 more files_ </details> ### 📄 Description ## Summary Fixes #6916. Analysts can find a workflow section with `rea guidance --query "exact JavaScript module"` or MCP `search_guidance`, then retrieve the selected section by locator with `--action read` / `read_guidance_section`. This continuation preserves the contributor history and integrates main `f25d1e3e9`. Search reads only the eight installed `MANAGED_SKILL_FILES`; responses identify documentation rather than analysis results or Evidence. No target/provider is required or executed and no arbitrary directory or external service is accessed. This stays within the existing local documentation boundary. ## Shared implementation and bounds CLI/MCP share application search/retrieval and one ATX section parser. Every non-generic query word must occur in a section; generic-only or unmatched subjects return scoped `no_matches`, without a capability claim. Ranking and query/bundle-bound paging are deterministic. Bundle bytes are re-read on every operation; changed content produces stale locators/cursors. No new cache is retained. - Limits: 1 MiB/file, 4 MiB/bundle, 4,096 sections and 25,165,824 expanded UTF-16 code units. A line scan counts headings and a stack establishes spans before section strings/ranked objects are allocated. Search pages contain at most 20 entries with 500-code-unit excerpts; read returns the selected section. - Locators contain bundle, fixed guide, ordinal and complete-section SHA-256. The section hash already covers its heading, so the heading is not duplicated in the identity. Long headings remain readable within the 4,096-character input contract. - ATX closing hashes require whitespace; literal/escaped hashes, indented headings and empty headings retain their source meaning. Title cleanup scans each end directly instead of using suffix regexes with quadratic blank-run behavior. Ranking computes each section's distinct words once. - Each complete search/read request is admitted once; individual file reads use its child scope. Shutdown waits for later reads and finalization, while failed child cleanup remains owned by the root with its exact descriptor and live lease. New work after shutdown is refused. Deterministic gates reproduce both original shutdown failures and cover overlapping mixed outcomes/retry. - Unreadable/oversized bundles report `bundle_unavailable`, with no partial index or inferred absence. First-close and retry cleanup failures remain errors carrying the exact live lease. CLI shutdown settles both JavaScript/guidance owners; reusable CLI workers and dispatcher fixtures use the shared cleanup entrypoint. Unrelated Android/browser formatting was excluded. ## Executed validation Linux x64, Node 24.22.1 / npm 11.16.0; head `465a262ee` (runtime unchanged from `b667c16be`): - **181 tests pass in 17 focused files** on runtime head `b667c16be`, and again on local candidate `2d389f6c5` merging final head `465a262ee` with current main `131fbe075`, including public CLI/MCP, advertised schemas, paging/staleness, filesystem/symlink/size bounds, dispatcher/closed-pipe behavior, cleanup retry, mixed close outcomes and reusable CLI workers. Seven original boundary failures and both shutdown regressions were reproduced before their fixes. Final test-only follow-up `465a262ee` reruns the four lifecycle tests and type/lint checks; gates now use bounded acknowledgement and unconditional release/join/close. Two temporary negative controls (early operation settlement and failed assertions, including denied cleanup) each produce the expected three failures and exit in about 1.2 s; restored tests pass. - `check:fast`, formatting, `git diff --check`, docs (9 README tests), catalog validation, and discovery (2,824 files exactly once) pass. Catalog check ran before the latest main-only integration; final CI checks the merged head. - Real generated bundle: **8 guides, 152,210 bytes, 69 ATX headings**. Independent markdown-it-py 4.0.0/CommonMark heading maps verify returned titles and full section content. CLI search/read and SDK 2.3.1 stdio MCP select the expected exact-module recipe. Full `module` pagination retains all 19 results without duplicates, omissions or reordering. - A live MCP test changes an owned generated guide, observes stale locator and continuation responses, restores the exact bytes and confirms successful retrieval again. The unknown-subject/domain-word control returns no matches. The guide backup and all profiling evidence stay outside Git. ## CI baseline and current-main verification [CI 40840282556](https://github.com/morluto/rea/actions/runs/40840282556) tests merge `df89030ba` on main `3503578f9`: **21,777 source tests pass /16 skip across 1,172 files**. Built shard 8 passes. Shard 5 has one failure in the unchanged `bundleComparisonMcp.test.ts:168`: it expects a legacy `left_bundle_path: ...` text substring while validation returns structured field issues. **Pure main `3503578f9` reproduces the identical failure (8 pass /1 fail)** with `npm run test:focused -- tests/boundary/mcp/bundleComparisonMcp.test.ts`. Matrix fail-fast cancels the other six shards; they are unverified on this run, not reported as passing. Platform results remain in the linked run. This is the only observed failed test; the operator explicitly authorized bypass for demonstrated main failures. Current-main candidate `2d389f6c5` (tree `4f2e5359223864fc9876e00e49328fe021ef16e3`, parents main `131fbe075` and final head `465a262ee`) merges cleanly, passes all **181 focused tests /17 files**, type/lint and diff checks. Its updated installed bundle is **152,417 bytes /8 guides /69 headings**; independent CommonMark maps, real recipe search/read, all 19 module results and live drift/restore pass again. Greptile gives **5/5 on exact final head**, with all eleven threads resolved. Codex could not review the final head because the repository review quota is exhausted. ## Completed-task measurements Before `1af45280e` is the original implementation integrated on the same main base; after `cb60adf28` includes the fixes. Two alternating/reversed repetitions per revision/workflow, fresh client/server sessions, warm OS caches; compile-cache state not independently controlled. `application` family and compact input schemas; initialization/instructions, catalog, requests, replies, notifications and both text/structured representations are counted. | Task | Estimated tokens | Elapsed | CPU | Peak family RSS | | --- | ---: | ---: | ---: | ---: | | Before, recipe search + read | 272,186 | 2.084–2.101 s | 2.80–2.85 s | 454.6–455.3 MiB | | After, recipe search + read | 272,133 | 2.121–2.138 s | 2.86–3.00 s | 454.3–454.5 MiB | | Before, all module pages | 280,518 | 2.251–2.339 s | 2.96–3.13 s | 454.1–455.9 MiB | | After, all module pages | 280,189 | 2.265–2.426 s | 3.02–3.18 s | 453.6–456.5 MiB | The recipe's chosen answer stays the same; requiring complete meaningful-term coverage reduces candidate sections from 41 to 11. Single-word pagination remains identical at 19 entries. Catalog 268,264 → 268,268 estimated tokens; compact locators offset that small addition. These whole-task measurements establish **no overall speedup**. After the latest main integration, two more guarded tasks pass: recipe 272,133 tokens /3.632 s /4.72 CPU s /456.3 MiB; pagination 280,189 /3.818 s /4.93 CPU s /456.8 MiB. Historical comparisons remain pinned above. After the lifecycle fix, the same two tasks pass again: recipe 3.987 s /5.22 CPU s /454.7 MiB; paging 4.110 s /5.30 CPU s /453.8 MiB. Token counts remain 272,133 /280,189; no guard stop or surviving process. The live freshness/restore test also passes again. The latest-main candidate also completes guarded recipe/paging tasks: **272,148 /280,204 tokens; 2.330 /2.496 s; 3.24 /3.42 CPU s; 455.5 /453.4 MiB**. Its catalog is 268,283 tokens; updated main accounts for the changed catalog and guide bytes. These are additional observations, not an equivalent-base speed comparison. No guard stops or survivors. A separate bounded diagnostic found a pre-linear title-cleanup expression took 440 ms for 16K internal spaces; the current complete section parser took 0.037 ms for that input and 0.108 ms at 64K. These have different scopes and are not a whole-workflow speed claim. The million-heading case was source-derived and deliberately not executed; a tiny boundary fixture proves refusal before expansion. Tokenx 1.3.0 provides transport estimates, not billed model/context tokens. RSS is a 10 ms client/server process-group sum; CPU includes both and excludes the external sampler. A 1.5 GiB family/150 s guard bounds runs; all final measured tasks complete with no guard stops or survivors. Cold caches, full-schema discovery and OS-enforced network denial are unmeasured. One incomplete measurement preflight used the wrong legacy root-union payload shape; it cost 269,925 estimated tokens /3.392 s /4.58 CPU s /452.9 MiB, is retained separately and is not represented as passing. The corrected client follows the advertised SDK projection. ## Author readiness Human owner: @Deepak-Kambala - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-03 13:38:42 +00:00

closed this issue
added the
pull-request
label

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#7559

No description provided.

Rows
Columns