[PR #5000] [CLOSED] feat(skill): coordinate evidence-led REA investigations #6722

Closed
opened 2026-11-01 21:42:34 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/5000
Author: @RishabhhR
Created: 10/18/2026
Status: ❌ Closed

Base: main ← Head: codex/coordo-investigation-v2


📝 Commits (10+)

  • 416d5c7 feat(skill): add opt-in Coordo evidence handoffs
  • 53359d5 fix(skill): harden Coordo handoffs, package managed files, and add tests
  • 0794d74 fix(skill): validate manifest UTF-8, bound agent names, and enforce bundle repo ownership
  • 7294c84 fix(skill): allow selected subprojects in parent repositories
  • b888d04 fix(skill): suppress potentially credentialed Coordo errors
  • 4e88a3b feat(skill): coordinate evidence-led REA investigations
  • beabe49 test(skill): expect privacy-safe Coordo failures
  • effd5d5 fix(skill): reject lone surrogates and align Coordo failure test
  • 1823343 Merge Coordo handoff fixes into investigation v2
  • 0d9cfcf Merge morluto/rea main into codex/coordo-investigation-v2

📊 Changes

13 files changed (+2274 additions, -24 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+10 -1)
➕ .agents/skills/reverse-engineer-anything/references/coordo-investigation-v2.md (+150 -0)
➕ .agents/skills/reverse-engineer-anything/references/coordo-multi-agent.md (+102 -0)
➕ .agents/skills/reverse-engineer-anything/scripts/coordo-handoff.mjs (+320 -0)
➕ .agents/skills/reverse-engineer-anything/scripts/coordo-investigate.mjs (+949 -0)
📝 src/application/SetupSkill.ts (+18 -2)
📝 src/generatedPackageMetadata.ts (+1 -1)
📝 tests/acceptance/setup/selectedSkillSetup.test.ts (+2 -1)
➕ tests/boundary/filesystem/coordoHandoff.test.ts (+295 -0)
➕ tests/boundary/filesystem/coordoInvestigate.test.ts (+319 -0)
📝 tests/boundary/filesystem/setupSkill.test.ts (+8 -19)
➕ tests/fixtures/fakeCoordo.mjs (+98 -0)
📝 turbo.json (+2 -0)

📄 Description

Summary

Stacked V2 of #4831. Where #4831 creates evidence-linked Coordo tasks from a private REA Evidence bundle, this PR adds an opt-in runner that dispatches those tasks to worker agents and then to an independent reviewer, so a lead does not have to relay each prompt by hand.

  • coordo-investigate.mjs previews a strict rea-coordo-investigation/v2 manifest and checks the Evidence bundle, ignored report paths, and headless agent adapters before creating any task.
  • With explicit --apply, it creates scoped tasks for 2–8 independent workers, dispatches them with bounded parallelism (max_parallel 1–4), and requires one distinct evidence-linked findings report per worker.
  • It dispatches a reviewer that must be different from every worker, and only after every worker task and report passes structural and identity checks.
  • Reports, run state, and dispatch logs stay under ignored .coordo/runs/. --resume provides a bounded retry path, and partial outcomes are reported explicitly.
  • The runner and its guide (references/coordo-investigation-v2.md) are added to the managed REA skill package; skill version 44.

Problem and expected behavior

Use case: an analyst splits one REA question into independent scopes for several agents and wants an independent check of their findings against the same Evidence. With only #4831, the lead creates tasks, starts each agent, and relays reports manually.

Expected: one previewed manifest drives task creation, dispatch, report validation, and review. Any failure stops with a machine-readable summary of what was created and completed. The runner checks report shape and identity only. It does not establish that findings are true; the reviewer checks claims against the Evidence bundle.

Change and scope

  • New script .agents/skills/reverse-engineer-anything/scripts/coordo-investigate.mjs, plus references/coordo-investigation-v2.md, linked from SKILL.md.
  • SetupSkill installs and inspects every managed parent directory (references/, scripts/), not only references/.
  • Includes all of #4831 (the handoff helper and its review fixes). Its well-formed Unicode check is applied to this runner's singleLine validator as well.
  • Review hardening (fec89fdd4): resume rechecks every task and report; every output (reports, state, lock, reservations, agent logs) must be Git ignored before writing; the reviewer handoff is size-checked in preview; SIGINT/SIGTERM cancel the run (no further work, exit 130); report paths are reserved per run; every observation must cite Evidence.
  • Not included: no REA analysis tool is invoked, no target is opened or executed, and no runtime authority is granted. Worker and reviewer CLIs run with whatever .coordo/lead.json configures.

Follow the contribution scope.
Scope decision pending. This PR depends on the unresolved maintainer question on #4831 about whether a Coordo-specific workflow belongs in the shipped skill (thread). It launches agent processes, so it needs that decision before integration.

Contract and boundary impact

  • Semantic owner and earliest changed stage: the managed skill package (.agents/skills/reverse-engineer-anything/) and SetupSkill managed-file installation.
  • Contribution scope fit and linked maintainer decision: pending; see the #4831 scope thread above.
  • CLI and MCP/tool-catalog contract: none. No REA CLI or MCP tool is added or changed.
  • Provider, bridge, target-format, or platform compatibility: --apply and --resume require a Unix-like Coordo host; Windows is rejected explicitly. Dry run works on every platform.
  • Evidence, artifact, provenance, or reconstruction contract: consumes an existing exported Evidence bundle by path and SHA-256 and does not modify it. Worker reports must cite Evidence IDs from the manifest.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): target selection and runtime authorization stay with the original request. Child dispatch processes are tracked and terminated on interruption, and run state is persisted for --resume.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact: skill version 42 → 44 (main independently moved to 43). generatedPackageMetadata.ts matches the generator output. Two new managed skill files are installed by rea setup.

Expected effects (check known effects; use documentation-only on its own).
Unchecked items do not establish absence; leave uncertainties visible.

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Notes: "launch" means coordo dispatch starts the configured agent CLIs. "Files" means Coordo ledger tasks and ignored run state, reports, and logs under .coordo/ (including report reservations under .coordo/runs/reservations/). "Network" applies only when the Coordo installation uses a remote backend.

Evidence and regression coverage

  • Tests added or updated: tests/boundary/filesystem/coordoInvestigate.test.ts drives the runner end to end against a fake Coordo CLI (tests/fixtures/fakeCoordo.mjs): bounded max_parallel dispatch, the reviewer gate, resume rechecks, observations without Evidence, Git-visible outputs, reviewer size preflight, report reservations and cancellation. Six of its seven tests fail against the runner before fec89fdd4. coordoHandoff.test.ts (from #4831) covers the handoff helper, including the privacy-safe --apply failure output and lone-surrogate rejection. setupSkill.test.ts and selectedSkillSetup.test.ts cover managed-file installation for the new directories.
  • Base reproduction or other evidence: executed. On a temporary project with a .coordo directory, an investigation manifest whose question is "before\ud800after" (a JSON escape) is rejected by validation with tasks[0].question must be a nonempty single line of well-formed Unicode…. The same manifest with a valid pair (U+1F600) passes validation.
  • User-visible CLI/MCP output (if applicable): no REA CLI/MCP output changes. Runner output is a JSON preview or run summary.
  • Remaining proof gaps: the runner is tested only against a fake Coordo CLI. Its dispatch, review, and --resume paths have not been run against a real Coordo CLI, real agents, or a remote backend in this PR's current state. Windows --apply is rejected by design and was not exercised.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

On fec89fdd4 (merged with main at c374c2fe7), macOS, Node 26.10.0:

  • npm run test:focused -- tests/boundary/filesystem/coordoInvestigate.test.ts tests/boundary/filesystem/coordoHandoff.test.ts tests/boundary/filesystem/setupSkill.test.ts tests/acceptance/setup/selectedSkillSetup.test.ts — 4 files, 41 tests passed.
  • coordoInvestigate.test.ts against the previous runner (4c1ba239a) — 6 of 7 failed, as expected; the happy-path baseline passed.
  • npm run check:fast (typecheck and lint) — passed.
  • node scripts/generate-package-metadata.mjs — output identical to the committed generatedPackageMetadata.ts.
  • Manual lone-surrogate and valid-pair probe of coordo-investigate.mjs (above) — rejected and accepted as expected.

Earlier, on 4e88a3b05: skill quick_validate.py, node --check on the runner, npm run build:cached (Node 24.19.0), npm run check:fast, and git diff --check all passed.

Compatibility, safety, and release

  • Breaking changes or migration steps: none. Opt-in; nothing runs unless a user invokes the runner, and dispatch requires --apply.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable to providers. macOS only; Linux and Windows not run locally. GitHub CI on this head is awaiting maintainer approval for fork workflows.
  • Package or release metadata impact: managed skill version 44 and two new packaged skill files. If #4831 merges first, its version (43, which main also uses now) and this one may need renumbering.
  • Security, privacy, process, or containment review: agent CLIs run with the permissions configured in .coordo/lead.json, and Coordo adapters do not sandbox agents as a group, so the project and agent configuration must be trusted. Child stderr from Coordo is not echoed (it may carry backend credentials). Reports and logs stay in ignored local paths with mode 0600 logs.

Author readiness

Human owner: @RishabhhR

  • 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.

🤖 Generated with Claude Code


🔄 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/5000 **Author:** [@RishabhhR](https://github.com/RishabhhR) **Created:** 10/18/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `codex/coordo-investigation-v2` --- ### 📝 Commits (10+) - [`416d5c7`](https://github.com/morluto/rea/commit/416d5c79adb2edf76db0a27b59bcc0c8f20033be) feat(skill): add opt-in Coordo evidence handoffs - [`53359d5`](https://github.com/morluto/rea/commit/53359d5e3b674d80d5b6142388c9b91bd801aab4) fix(skill): harden Coordo handoffs, package managed files, and add tests - [`0794d74`](https://github.com/morluto/rea/commit/0794d74f01be2d852ff45bf6163b88590dfcb9c5) fix(skill): validate manifest UTF-8, bound agent names, and enforce bundle repo ownership - [`7294c84`](https://github.com/morluto/rea/commit/7294c84a098b291bf31266a1ef3cbfd21affe210) fix(skill): allow selected subprojects in parent repositories - [`b888d04`](https://github.com/morluto/rea/commit/b888d041eddfc78b7162b6bda33388ab37ff40bd) fix(skill): suppress potentially credentialed Coordo errors - [`4e88a3b`](https://github.com/morluto/rea/commit/4e88a3b05b99b20eab1fcc122d6ce40a0da529c7) feat(skill): coordinate evidence-led REA investigations - [`beabe49`](https://github.com/morluto/rea/commit/beabe4908173b03bce053be5210f35bbd13e1b3b) test(skill): expect privacy-safe Coordo failures - [`effd5d5`](https://github.com/morluto/rea/commit/effd5d53a637c95f4addd71e7284f5451810e2ce) fix(skill): reject lone surrogates and align Coordo failure test - [`1823343`](https://github.com/morluto/rea/commit/1823343d96f3e067054dc342a5cd914f099296f1) Merge Coordo handoff fixes into investigation v2 - [`0d9cfcf`](https://github.com/morluto/rea/commit/0d9cfcf0e73c13b67960970597cf9882dbfb4871) Merge morluto/rea main into codex/coordo-investigation-v2 ### 📊 Changes **13 files changed** (+2274 additions, -24 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+10 -1) ➕ `.agents/skills/reverse-engineer-anything/references/coordo-investigation-v2.md` (+150 -0) ➕ `.agents/skills/reverse-engineer-anything/references/coordo-multi-agent.md` (+102 -0) ➕ `.agents/skills/reverse-engineer-anything/scripts/coordo-handoff.mjs` (+320 -0) ➕ `.agents/skills/reverse-engineer-anything/scripts/coordo-investigate.mjs` (+949 -0) 📝 `src/application/SetupSkill.ts` (+18 -2) 📝 `src/generatedPackageMetadata.ts` (+1 -1) 📝 `tests/acceptance/setup/selectedSkillSetup.test.ts` (+2 -1) ➕ `tests/boundary/filesystem/coordoHandoff.test.ts` (+295 -0) ➕ `tests/boundary/filesystem/coordoInvestigate.test.ts` (+319 -0) 📝 `tests/boundary/filesystem/setupSkill.test.ts` (+8 -19) ➕ `tests/fixtures/fakeCoordo.mjs` (+98 -0) 📝 `turbo.json` (+2 -0) </details> ### 📄 Description ## Summary Stacked V2 of #4831. Where #4831 creates evidence-linked Coordo tasks from a private REA Evidence bundle, this PR adds an opt-in runner that dispatches those tasks to worker agents and then to an independent reviewer, so a lead does not have to relay each prompt by hand. - `coordo-investigate.mjs` previews a strict `rea-coordo-investigation/v2` manifest and checks the Evidence bundle, ignored report paths, and headless agent adapters before creating any task. - With explicit `--apply`, it creates scoped tasks for 2–8 independent workers, dispatches them with bounded parallelism (`max_parallel` 1–4), and requires one distinct evidence-linked findings report per worker. - It dispatches a reviewer that must be different from every worker, and only after every worker task and report passes structural and identity checks. - Reports, run state, and dispatch logs stay under ignored `.coordo/runs/`. `--resume` provides a bounded retry path, and partial outcomes are reported explicitly. - The runner and its guide (`references/coordo-investigation-v2.md`) are added to the managed REA skill package; skill version 44. ## Problem and expected behavior Use case: an analyst splits one REA question into independent scopes for several agents and wants an independent check of their findings against the same Evidence. With only #4831, the lead creates tasks, starts each agent, and relays reports manually. Expected: one previewed manifest drives task creation, dispatch, report validation, and review. Any failure stops with a machine-readable summary of what was created and completed. The runner checks report shape and identity only. It does not establish that findings are true; the reviewer checks claims against the Evidence bundle. ## Change and scope - New script `.agents/skills/reverse-engineer-anything/scripts/coordo-investigate.mjs`, plus `references/coordo-investigation-v2.md`, linked from `SKILL.md`. - `SetupSkill` installs and inspects every managed parent directory (`references/`, `scripts/`), not only `references/`. - Includes all of #4831 (the handoff helper and its review fixes). Its well-formed Unicode check is applied to this runner's `singleLine` validator as well. - Review hardening (`fec89fdd4`): resume rechecks every task and report; every output (reports, state, lock, reservations, agent logs) must be Git ignored before writing; the reviewer handoff is size-checked in preview; SIGINT/SIGTERM cancel the run (no further work, exit 130); report paths are reserved per run; every observation must cite Evidence. - Not included: no REA analysis tool is invoked, no target is opened or executed, and no runtime authority is granted. Worker and reviewer CLIs run with whatever `.coordo/lead.json` configures. Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). **Scope decision pending.** This PR depends on the unresolved maintainer question on #4831 about whether a Coordo-specific workflow belongs in the shipped skill ([thread](https://github.com/morluto/rea/pull/4831#discussion_r4305054542)). It launches agent processes, so it needs that decision before integration. ## Contract and boundary impact - Semantic owner and earliest changed stage: the managed skill package (`.agents/skills/reverse-engineer-anything/`) and `SetupSkill` managed-file installation. - Contribution scope fit and linked maintainer decision: pending; see the #4831 scope thread above. - CLI and MCP/tool-catalog contract: none. No REA CLI or MCP tool is added or changed. - Provider, bridge, target-format, or platform compatibility: `--apply` and `--resume` require a Unix-like Coordo host; Windows is rejected explicitly. Dry run works on every platform. - Evidence, artifact, provenance, or reconstruction contract: consumes an existing exported Evidence bundle by path and SHA-256 and does not modify it. Worker reports must cite Evidence IDs from the manifest. - Target selection, authority, upstream behavior, and cleanup details (if applicable): target selection and runtime authorization stay with the original request. Child dispatch processes are tracked and terminated on interruption, and run state is persisted for `--resume`. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: skill version 42 → 44 (main independently moved to 43). `generatedPackageMetadata.ts` matches the generator output. Two new managed skill files are installed by `rea setup`. Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible. - [x] Read existing files or captured data. - [x] Launch or attach to a process. - [x] Inject instrumentation or run scripts/code. - [x] Change process memory, registers, files, or configuration. - [x] Contact network services. - [x] Recover protected code or work around protections. - [x] Documentation or usability only; no target interaction. - [x] Not sure yet; investigation or maintainer guidance needed. Notes: "launch" means `coordo dispatch` starts the configured agent CLIs. "Files" means Coordo ledger tasks and ignored run state, reports, and logs under `.coordo/` (including report reservations under `.coordo/runs/reservations/`). "Network" applies only when the Coordo installation uses a remote backend. ## Evidence and regression coverage - Tests added or updated: `tests/boundary/filesystem/coordoInvestigate.test.ts` drives the runner end to end against a fake Coordo CLI (`tests/fixtures/fakeCoordo.mjs`): bounded `max_parallel` dispatch, the reviewer gate, resume rechecks, observations without Evidence, Git-visible outputs, reviewer size preflight, report reservations and cancellation. Six of its seven tests fail against the runner before `fec89fdd4`. `coordoHandoff.test.ts` (from #4831) covers the handoff helper, including the privacy-safe `--apply` failure output and lone-surrogate rejection. `setupSkill.test.ts` and `selectedSkillSetup.test.ts` cover managed-file installation for the new directories. - Base reproduction or other evidence: executed. On a temporary project with a `.coordo` directory, an investigation manifest whose question is `"before\ud800after"` (a JSON escape) is rejected by validation with `tasks[0].question must be a nonempty single line of well-formed Unicode…`. The same manifest with a valid pair (U+1F600) passes validation. - User-visible CLI/MCP output (if applicable): no REA CLI/MCP output changes. Runner output is a JSON preview or run summary. - Remaining proof gaps: the runner is tested only against a fake Coordo CLI. Its dispatch, review, and `--resume` paths have not been run against a real Coordo CLI, real agents, or a remote backend in this PR's current state. Windows `--apply` is rejected by design and was not exercised. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed On `fec89fdd4` (merged with `main` at `c374c2fe7`), macOS, Node 26.10.0: - `npm run test:focused -- tests/boundary/filesystem/coordoInvestigate.test.ts tests/boundary/filesystem/coordoHandoff.test.ts tests/boundary/filesystem/setupSkill.test.ts tests/acceptance/setup/selectedSkillSetup.test.ts` — 4 files, 41 tests passed. - `coordoInvestigate.test.ts` against the previous runner (`4c1ba239a`) — 6 of 7 failed, as expected; the happy-path baseline passed. - `npm run check:fast` (typecheck and lint) — passed. - `node scripts/generate-package-metadata.mjs` — output identical to the committed `generatedPackageMetadata.ts`. - Manual lone-surrogate and valid-pair probe of `coordo-investigate.mjs` (above) — rejected and accepted as expected. Earlier, on `4e88a3b05`: skill `quick_validate.py`, `node --check` on the runner, `npm run build:cached` (Node 24.19.0), `npm run check:fast`, and `git diff --check` all passed. ## Compatibility, safety, and release - Breaking changes or migration steps: none. Opt-in; nothing runs unless a user invokes the runner, and dispatch requires `--apply`. - Real Hopper/Ghidra, browser, or OS coverage: not applicable to providers. macOS only; Linux and Windows not run locally. GitHub CI on this head is awaiting maintainer approval for fork workflows. - Package or release metadata impact: managed skill version 44 and two new packaged skill files. If #4831 merges first, its version (43, which `main` also uses now) and this one may need renumbering. - Security, privacy, process, or containment review: agent CLIs run with the permissions configured in `.coordo/lead.json`, and Coordo adapters do not sandbox agents as a group, so the project and agent configuration must be trusted. Child stderr from Coordo is not echoed (it may carry backend credentials). Reports and logs stay in ignored local paths with mode 0600 logs. ## Author readiness Human owner: @RishabhhR - [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. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-11-01 21:42:34 +00:00
Sign in to join this conversation.
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#6722
No description provided.