[PR #4970] docs(companions): propose opt-in integration contract #6702

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

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4970
Author: @ShadowSwaps
Created: 10/18/2026
Status: 🔄 Open

Base: main ← Head: docs/4718-companion-integration-design


📝 Commits (2)

  • 3c30a6d docs(companions): propose opt-in integration contract
  • d8c0f3c docs(companions): clarify update ownership and source references

📊 Changes

3 files changed (+158 additions, -0 deletions)

View changed files

➕ docs/specs/4718-companion-integration/example/instructions.example.md (+5 -0)
➕ docs/specs/4718-companion-integration/example/manifest.json (+13 -0)
➕ docs/specs/4718-companion-integration/spec.md (+140 -0)

📄 Description

Summary

I propose an opt-in companion contract that preserves REA's canonical skill checks.
This PR adds a design note, illustrative manifest and instruction fixture for
feedback on loading, trusted profile binding and installation ownership.

Related to #4718; this design-only proposal does not resolve the issue. Contributor
review feedback is addressed by preserving this full template, clarifying
Companion-owned update settings, and refreshing the pinned source references.

Problem and expected behavior

Adding companion instructions to managed REA skill text causes the canonical-file
conflict described in #4718. I propose a supported opt-in loading route with
separate consent and health reporting; no such integration is implemented here.

Change and scope

Follow the contribution scope.
Unresolved scope, authority, side effects, or required verification block
integration. Link the required maintainer scope decision for new providers or
capabilities involving target execution, injection, mutation, or protection
recovery; ordinary fixes within existing boundaries may state "not applicable".
Draft PRs may leave the scope decision pending and the readiness and merge checklists
unchecked. Maintainers can help resolve open questions.

Exactly three documentation/example files remain under
docs/specs/4718-companion-integration/: spec.md,
example/manifest.json, and example/instructions.example.md. This local
correction changes only the spec; the fixture bytes and manifest stay unchanged.

My preferred route remains a canonical loading instruction, read-only resolver
and one explicitly selected existing installation. Loader choice, the trusted
client/profile/registry/executable source and installation ownership still need
maintainer agreement. Contributor source review is not that agreement.
Weekly-check opt-in and cooldown are the Companion installer/updater's settings,
not existing REA settings or consent for the proposed integration.

The separate inactive prototype in #6366 is outside this design PR and is not
extended by this correction. No implementation, new command, setup/update/doctor
wiring, migration writer or client-support claim is added here.

Contract and boundary impact

  • Semantic owner and earliest changed stage: Design documentation only; any future adapter/registration ownership remains a maintainer decision. No production path or lifecycle changes.
  • Contribution scope fit and linked maintainer decision: Documentation-only discussion for #4718; integration scope/authority remains pending, with no linked maintainer acceptance established.
  • CLI and MCP/tool-catalog contract: Unchanged; no command or tool added.
  • Provider, bridge, target-format, or platform compatibility: Unchanged; no host/client support is established.
  • Evidence, artifact, provenance, or reconstruction contract: Illustrative fixture and source provenance only; the proposed runtime contract remains unimplemented.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): No target interaction or runtime changes; the proposal retains scope, consent and cleanup limits.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact (CI generates and validates ignored catalogs and skills/; edit authored instructions in .agents/skills/reverse-engineer-anything/ and never commit build outputs): None in this design diff; no generated metadata, canonical skill or installation is changed.

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.

Evidence and regression coverage

  • Tests added or updated: No runtime tests; local documentation/fixture checks are recorded below.
  • Base reproduction or other evidence: Source-only recheck of upstream main 1e421242b97a533a5c03458ac074d4353ec17bf3 on 28 October 2026: SetupSkill.ts byte comparison, Doctor.ts canonical predicate, and Update.ts unapplied maintenance plan. No setup/doctor/update sequence was executed. The historical comparison at 6b180783ed04ebc87548c8385c80e05725804c47 is line 437, not line 406.
  • User-visible CLI/MCP output (if applicable): Not applicable to documentation-only changes.
  • Remaining proof gaps: Maintainer design decisions, trusted host binding, genuine session delivery, package completeness, migration/recovery and production validation remain unestablished by this PR. No #6366 test result is substituted for them.

For boundary fixes, identify the applicable boundary regressions
and lifecycle regressions
covered by the evidence above, and explain relevant gaps.

This is a documentation correction, not a production boundary fix. Boundary and
lifecycle regressions remain proposed acceptance requirements; none were run or
waived for this design.

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

  • node -e 'JSON.parse(require("node:fs").readFileSync("docs/specs/4718-companion-integration/example/manifest.json","utf8")); console.log("JSON valid")' — valid JSON.
  • node -e 'const fs=require("node:fs"),c=require("node:crypto"),m=JSON.parse(fs.readFileSync("docs/specs/4718-companion-integration/example/manifest.json","utf8")); for(const [p,h] of Object.entries(m.files)){if(c.createHash("sha256").update(fs.readFileSync("docs/specs/4718-companion-integration/example/"+p)).digest("hex")!==h)throw Error("digest mismatch")} console.log("manifest digests match")' — manifest digests match.
  • Local document checks — full-template round trip, preserved human declarations,
    fixture/local links, exact pinned source/blob identities, refreshed line targets
    and restricted spec changes passed. The private validation script is not a
    repository addition.

Full repository checks, documentation build, CI and real setup/runtime workflows
were not run for this local-only correction. No dependencies were installed.
Earlier public CI results describe the existing remote head, not this unpublished
spec revision.

Compatibility, safety, and release

  • Breaking changes or migration steps: None implemented; migration remains a design requirement.
  • Real Hopper/Ghidra, browser, or OS coverage: Not exercised; source/document review is not runtime or provider proof.
  • Package or release metadata impact: None; no release, installer or update action is part of this diff.
  • Security, privacy, process, or containment review: The proposal retains explicit per-profile consent, exact content identity, safe reads, inactive recovery and host-delivery limits. Hashes are not publisher authentication or a sandbox. This source/document review establishes no production trust or execution authority.

Author readiness

Human owner: @ShadowSwaps

  • 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/4970 **Author:** [@ShadowSwaps](https://github.com/ShadowSwaps) **Created:** 10/18/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `docs/4718-companion-integration-design` --- ### 📝 Commits (2) - [`3c30a6d`](https://github.com/morluto/rea/commit/3c30a6d9f97251bea2c8aae299469bf591ff9729) docs(companions): propose opt-in integration contract - [`d8c0f3c`](https://github.com/morluto/rea/commit/d8c0f3c4a19ab5b9dbdc7dfa2ca93babea4e86ba) docs(companions): clarify update ownership and source references ### 📊 Changes **3 files changed** (+158 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `docs/specs/4718-companion-integration/example/instructions.example.md` (+5 -0) ➕ `docs/specs/4718-companion-integration/example/manifest.json` (+13 -0) ➕ `docs/specs/4718-companion-integration/spec.md` (+140 -0) </details> ### 📄 Description <!-- PR title: type(optional-scope): imperative outcome The title becomes the squash-merge commit subject and generated changelog entry. --> ## Summary <!-- What user, agent, or maintainer problem does this solve? Link the issue with "Fixes #123" when applicable. Keep the prior behavior, expected contract, and new behavior understandable without private context. --> I propose an opt-in companion contract that preserves REA's canonical skill checks. This PR adds a design note, illustrative manifest and instruction fixture for feedback on loading, trusted profile binding and installation ownership. Related to #4718; this design-only proposal does not resolve the issue. Contributor review feedback is addressed by preserving this full template, clarifying Companion-owned update settings, and refreshing the pinned source references. ## Problem and expected behavior <!-- For fixes, give the smallest trigger and violated invariant. For features, describe the use case and observable outcome. --> Adding companion instructions to managed REA skill text causes the canonical-file conflict described in #4718. I propose a supported opt-in loading route with separate consent and health reporting; no such integration is implemented here. ## Change and scope <!-- Explain the chosen approach, why it fits REA's architecture, and what is intentionally not included. If adding complexity for a speculative or vanishingly unlikely race or security edge case, record the concrete failure mode, likelihood, complexity cost, and the user's buy-in obtained before implementation. Do not silently expand scope for theoretical robustness. --> Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). Unresolved scope, authority, side effects, or required verification block integration. Link the required maintainer scope decision for new providers or capabilities involving target execution, injection, mutation, or protection recovery; ordinary fixes within existing boundaries may state "not applicable". Draft PRs may leave the scope decision pending and the readiness and merge checklists unchecked. Maintainers can help resolve open questions. Exactly three documentation/example files remain under `docs/specs/4718-companion-integration/`: `spec.md`, `example/manifest.json`, and `example/instructions.example.md`. This local correction changes only the spec; the fixture bytes and manifest stay unchanged. My preferred route remains a canonical loading instruction, read-only resolver and one explicitly selected existing installation. Loader choice, the trusted client/profile/registry/executable source and installation ownership still need maintainer agreement. Contributor source review is not that agreement. Weekly-check opt-in and cooldown are the Companion installer/updater's settings, not existing REA settings or consent for the proposed integration. The separate inactive prototype in #6366 is outside this design PR and is not extended by this correction. No implementation, new command, setup/update/doctor wiring, migration writer or client-support claim is added here. ## Contract and boundary impact <!-- Short answers are welcome. Complete applicable lines; mark unresolved facts as "unknown". Use "none" or "not applicable" only when established. --> - Semantic owner and earliest changed stage: Design documentation only; any future adapter/registration ownership remains a maintainer decision. No production path or lifecycle changes. <!-- Name the producer of parsed facts or resources and its affected consumers. Summarize superseded paths removed and any distinct policy, lifecycle, lazy-loading, or compatibility responsibility retained. --> - Contribution scope fit and linked maintainer decision: Documentation-only discussion for #4718; integration scope/authority remains pending, with no linked maintainer acceptance established. - CLI and MCP/tool-catalog contract: Unchanged; no command or tool added. - Provider, bridge, target-format, or platform compatibility: Unchanged; no host/client support is established. - Evidence, artifact, provenance, or reconstruction contract: Illustrative fixture and source provenance only; the proposed runtime contract remains unimplemented. - Target selection, authority, upstream behavior, and cleanup details (if applicable): No target interaction or runtime changes; the proposal retains scope, consent and cleanup limits. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact (CI generates and validates ignored catalogs and `skills/`; edit authored instructions in `.agents/skills/reverse-engineer-anything/` and never commit build outputs): None in this design diff; no generated metadata, canonical skill or installation is changed. 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. - [x] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage <!-- State whether evidence is executed, source-derived, or proposed. For fixes, show the original failure and explain how the regression would fail on the affected base revision when practical. Include the most useful proof inline; link long logs or artifacts, or put them in optional details. Documentation-only changes can use source, link, or rendered-document checks. --> - Tests added or updated: No runtime tests; local documentation/fixture checks are recorded below. - Base reproduction or other evidence: Source-only recheck of upstream main `1e421242b97a533a5c03458ac074d4353ec17bf3` on 28 October 2026: [SetupSkill.ts byte comparison](https://github.com/morluto/rea/blob/1e421242b97a533a5c03458ac074d4353ec17bf3/src/application/SetupSkill.ts#L509), [Doctor.ts canonical predicate](https://github.com/morluto/rea/blob/1e421242b97a533a5c03458ac074d4353ec17bf3/src/application/Doctor.ts#L431-L436), and [Update.ts unapplied maintenance plan](https://github.com/morluto/rea/blob/1e421242b97a533a5c03458ac074d4353ec17bf3/src/application/Update.ts#L238-L252). No setup/doctor/update sequence was executed. The historical comparison at `6b180783ed04ebc87548c8385c80e05725804c47` is line 437, not line 406. - User-visible CLI/MCP output (if applicable): Not applicable to documentation-only changes. - Remaining proof gaps: Maintainer design decisions, trusted host binding, genuine session delivery, package completeness, migration/recovery and production validation remain unestablished by this PR. No #6366 test result is substituted for them. For boundary fixes, identify the applicable [boundary regressions](https://github.com/morluto/rea/blob/main/docs/testing.md#boundary-regressions) and [lifecycle regressions](https://github.com/morluto/rea/blob/main/docs/testing.md#lifecycle-regressions) covered by the evidence above, and explain relevant gaps. This is a documentation correction, not a production boundary fix. Boundary and lifecycle regressions remain proposed acceptance requirements; none were run or waived for this design. 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 <!-- List only commands that actually ran, with observed results. Include the relevant real-provider or platform workflow, or explain why it was unavailable. Keep these results current after changes; a command without its result is incomplete. --> - `node -e 'JSON.parse(require("node:fs").readFileSync("docs/specs/4718-companion-integration/example/manifest.json","utf8")); console.log("JSON valid")'` — valid JSON. - `node -e 'const fs=require("node:fs"),c=require("node:crypto"),m=JSON.parse(fs.readFileSync("docs/specs/4718-companion-integration/example/manifest.json","utf8")); for(const [p,h] of Object.entries(m.files)){if(c.createHash("sha256").update(fs.readFileSync("docs/specs/4718-companion-integration/example/"+p)).digest("hex")!==h)throw Error("digest mismatch")} console.log("manifest digests match")'` — manifest digests match. - Local document checks — full-template round trip, preserved human declarations, fixture/local links, exact pinned source/blob identities, refreshed line targets and restricted spec changes passed. The private validation script is not a repository addition. Full repository checks, documentation build, CI and real setup/runtime workflows were not run for this local-only correction. No dependencies were installed. Earlier public CI results describe the existing remote head, not this unpublished spec revision. ## Compatibility, safety, and release <!-- Call out breaking changes, migrations, package effects, platform/provider limits, security/privacy/containment implications, and meaningful proof gaps. --> - Breaking changes or migration steps: None implemented; migration remains a design requirement. <!-- For ! / BREAKING CHANGE: show a previously valid call/configuration, its new behavior and migration, and why compatibility/deprecation cannot preserve it. Every release increments minor, including breaking changes; keep breaking markers and migration notes so callers can assess compatibility. See docs/releasing.md. --> - Real Hopper/Ghidra, browser, or OS coverage: Not exercised; source/document review is not runtime or provider proof. - Package or release metadata impact: None; no release, installer or update action is part of this diff. - Security, privacy, process, or containment review: The proposal retains explicit per-profile consent, exact content identity, safe reads, inactive recovery and host-delivery limits. Hashes are not publisher authentication or a sandbox. This source/document review establishes no production trust or execution authority. ## Author readiness <!-- The human owner completes these declarations before requesting review. The PR author is the owner by default. A different owner must explicitly accept ownership on this PR. AI agents must leave these declarations to a human to dictate to them or there could be catastrophic consequences for many users of REA. Draft PRs may leave them unchecked. These declarations record initial readiness when opening the PR for review; later pushes do not require a new human sign-off. Keep the description and validation evidence current as the work changes. See CONTRIBUTING.md#pull-request-ownership-and-readiness. --> Human owner: @ShadowSwaps - [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 <!-- Draft PRs may leave pending items unchecked. Resolve material scope and authority questions before integration. --> - [ ] 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. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
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#6702
No description provided.