Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

docs: improve GitHub issue and pull request templates

morlutoc490d85045de
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
deleted file mode 100644
index 3b45b027c..000000000
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-name: Bug Report
-about: Report a bug in REA
-title: "[Bug] "
-labels: ["bug", "triage"]
-assignees: []
----
-
-## Bug Description
-
-A clear and concise description of what the bug is.
-
-## Steps to Reproduce
-
-1.
-2.
-3.
-
-## Expected Behavior
-
-What you expected to happen.
-
-## Actual Behavior
-
-What actually happened, including any error messages or unexpected output.
-
-## Environment
-
-- REA version (`rea --version` or `npm list @morluto/rea`):
-- Node.js version (`node --version`):
-- macOS version:
-- Hopper Disassembler version:
-- Target binary format (Mach-O, ELF, PE, .hop):
-
-## Additional Context
-
-- MCP client and version (if applicable):
-- Any relevant logs or stack traces:
-- Does the issue reproduce with a different target binary?
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 000000000..f93e9f7bd
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,155 @@
+name: Bug report
+description: Report a reproducible problem in REA
+title: "[Bug] "
+labels:
+ - bug
+ - triage
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Please report one primary behavior per issue. Keep observed behavior
+ separate from suspected causes, and remove credentials and private paths.
+
+ - type: checkboxes
+ id: before-submitting
+ attributes:
+ label: Before submitting
+ options:
+ - label: I searched the open and closed issues for a related report.
+ required: true
+ - label: I removed credentials, tokens, private paths, and sensitive target data.
+ required: true
+
+ - type: dropdown
+ id: area
+ attributes:
+ label: Area
+ options:
+ - Setup, packaging, or upgrade
+ - Provider or capability discovery
+ - Process capture or runtime observation
+ - Native analysis or decompilation
+ - Evidence, artifacts, or reconstruction
+ - CLI
+ - MCP or agent integration
+ - Documentation
+ - Other
+ validations:
+ required: true
+
+ - type: textarea
+ id: observed-behavior
+ attributes:
+ label: Observed behavior
+ description: What happened? Include the command, MCP tool, provider, target type, and conditions that matter.
+ validations:
+ required: true
+
+ - type: textarea
+ id: reproduction
+ attributes:
+ label: Reproduction
+ description: Give the smallest realistic command, configuration, input, or event sequence that demonstrates the problem.
+ placeholder: |
+ 1. Configure or start ...
+ 2. Run ...
+ 3. Observe ...
+ validations:
+ required: true
+
+ - type: textarea
+ id: expected-behavior
+ attributes:
+ label: Expected behavior
+ description: What result, contract, invariant, recovery action, or state transition should have occurred?
+ validations:
+ required: true
+
+ - type: textarea
+ id: impact-scope
+ attributes:
+ label: Impact and scope
+ description: What is affected, what is not affected, and does this affect evidence integrity, process isolation, compatibility, or recovery?
+ validations:
+ required: true
+
+ - type: input
+ id: rea-version
+ attributes:
+ label: REA version
+ description: Use `rea --version` or provide the source revision.
+ placeholder: 3.1.0 or git revision
+ validations:
+ required: true
+
+ - type: input
+ id: runtime
+ attributes:
+ label: Runtime and platform
+ description: Include Node.js, OS, architecture, and Hopper/Ghidra version when relevant.
+ placeholder: Node 24.18; macOS 15 arm64; Hopper 5.15
+ validations:
+ required: true
+
+ - type: input
+ id: target
+ attributes:
+ label: Target and artifact context
+ description: Include binary format, app/container type, artifact kind, or workload details when relevant.
+ placeholder: Mach-O arm64 app; Evidence v2 bundle; not applicable
+
+ - type: dropdown
+ id: interface
+ attributes:
+ label: Interface
+ options:
+ - CLI
+ - MCP
+ - Python bridge
+ - Package or setup
+ - Other
+ validations:
+ required: true
+
+ - type: dropdown
+ id: failure-stage
+ attributes:
+ label: Earliest failure stage
+ description: Select where the incorrect behavior first becomes observable.
+ options:
+ - Request parsing or validation
+ - Setup or provider admission
+ - Capture or observation
+ - Artifact or evidence registration
+ - Native analysis or reconstruction
+ - Transport or result projection
+ - Cleanup, cancellation, or lifecycle
+ - Unknown
+ validations:
+ required: true
+
+ - type: textarea
+ id: relevant-evidence
+ attributes:
+ label: Relevant output or evidence
+ description: Paste the smallest useful CLI output, MCP result, error, trace, or evidence excerpt. Redact sensitive values.
+ render: text
+
+ - type: textarea
+ id: typed-outcome
+ attributes:
+ label: Typed outcome or recovery expected
+ description: Optional. What typed result, error, next tool, cleanup state, or limitation should the caller have received?
+
+ - type: textarea
+ id: analysis
+ attributes:
+ label: Analysis or suspected cause
+ description: Optional. Clearly mark source-derived reasoning or a hypothesis; do not present an unverified cause as fact.
+
+ - type: textarea
+ id: additional-context
+ attributes:
+ label: Additional context
+ description: Add links, reduced fixtures, screenshots, or a proposed regression test.
diff --git a/.github/ISSUE_TEMPLATE/design_discussion.yml b/.github/ISSUE_TEMPLATE/design_discussion.yml
new file mode 100644
index 000000000..912e18c44
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/design_discussion.yml
@@ -0,0 +1,69 @@
+name: Design discussion
+description: Resolve an REA architecture, provider, or contract question before implementation
+title: "[Design] "
+labels:
+ - enhancement
+ - triage
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Use this for a substantial provider, public/persisted contract, or
+ authority-boundary decision. Keep one decision per discussion.
+
+ - type: checkboxes
+ id: before-submitting
+ attributes:
+ label: Before submitting
+ options:
+ - label: I searched the open and closed issues and pull requests for a related discussion.
+ required: true
+ - label: I removed credentials, tokens, private paths, and sensitive target data.
+ required: true
+
+ - type: textarea
+ id: decision
+ attributes:
+ label: Decision needed
+ description: State the exact question maintainers need to resolve.
+ placeholder: Should REA ... or ...?
+ validations:
+ required: true
+
+ - type: textarea
+ id: context-evidence
+ attributes:
+ label: Context and evidence
+ description: Explain why the decision is needed now. Separate observed behavior, derived evidence, and inference.
+ validations:
+ required: true
+
+ - type: textarea
+ id: boundary-invariants
+ attributes:
+ label: Boundary and invariants
+ description: Identify the owning layer, provider/bridge boundary, artifact or evidence invariants, and any process or authorization constraints.
+ validations:
+ required: true
+
+ - type: textarea
+ id: options
+ attributes:
+ label: Options and tradeoffs
+ description: Compare a small number of viable approaches, including platform, compatibility, safety, evidence, and maintenance costs.
+ validations:
+ required: true
+
+ - type: textarea
+ id: success-criteria
+ attributes:
+ label: Success criteria and open questions
+ description: State what outcome would settle the decision and list only unresolved questions that could change the choice.
+ validations:
+ required: true
+
+ - type: textarea
+ id: references
+ attributes:
+ label: References
+ description: Link relevant contracts, upstream provider documentation, tests, measurements, or prior discussions.
diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md
deleted file mode 100644
index 38602f41a..000000000
--- a/.github/ISSUE_TEMPLATE/documentation.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-name: Documentation
-about: Suggest improvements to REA documentation
-title: "[Docs] "
-labels: ["documentation", "triage"]
-assignees: []
----
-
-## Documentation Area
-
-Which documentation needs improvement? (README, AGENTS.md, API docs, inline JSDoc, skill files)
-
-## Problem
-
-What is unclear, missing, or incorrect in the current documentation?
-
-## Suggested Improvement
-
-Describe the change you would like to see.
-
-## Additional Context
-
-- Link to the relevant documentation file or section:
-- Any examples or references that would help:
diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml
new file mode 100644
index 000000000..fa2bc024e
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/documentation.yml
@@ -0,0 +1,53 @@
+name: Documentation
+description: Report unclear, missing, or incorrect REA documentation
+title: "[Docs] "
+labels:
+ - documentation
+ - triage
+body:
+ - type: checkboxes
+ id: before-submitting
+ attributes:
+ label: Before submitting
+ options:
+ - label: I searched the existing issues for a related documentation report.
+ required: true
+ - label: I removed credentials, tokens, private paths, and sensitive target data.
+ required: true
+
+ - type: input
+ id: location
+ attributes:
+ label: Documentation location
+ description: Link the page, section, command, API, skill, or inline comment.
+ placeholder: README.md#quick-start or docs/mcp-contracts.md
+ validations:
+ required: true
+
+ - type: textarea
+ id: problem
+ attributes:
+ label: Problem
+ description: What is unclear, missing, outdated, or incorrect, and who is affected?
+ validations:
+ required: true
+
+ - type: textarea
+ id: expected-content
+ attributes:
+ label: Expected content
+ description: Describe the accurate behavior or example that should be documented.
+ validations:
+ required: true
+
+ - type: textarea
+ id: evidence
+ attributes:
+ label: Supporting evidence
+ description: Add source, command output, provider documentation, or a link that supports the correction.
+
+ - type: textarea
+ id: additional-context
+ attributes:
+ label: Additional context
+ description: Include screenshots, affected translations, or related issues.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
deleted file mode 100644
index 97d2d892e..000000000
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-name: Feature Request
-about: Propose a new feature or enhancement for REA
-title: "[Feature] "
-labels: ["enhancement", "triage"]
-assignees: []
----
-
-## Problem Statement
-
-What problem does this feature solve? Describe the use case and why existing tools are insufficient.
-
-## Proposed Solution
-
-Describe the feature or enhancement you would like to see. Include:
-
-- Which REA tool(s) this affects (direct, enhanced, or session tools)
-- Expected inputs and outputs
-- How it integrates with the existing MCP workflow
-
-## Alternatives Considered
-
-Any alternative approaches or workarounds you have tried.
-
-## Additional Context
-
-- Relevant Hopper API methods or concepts:
-- Links to related issues or discussions:
-- Would this require changes to the bridge (`bridge/hopper_bridge.py`)?
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 000000000..7b0767b27
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,88 @@
+name: Feature request
+description: Propose a focused improvement to REA
+title: "[Feature] "
+labels:
+ - enhancement
+ - triage
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Keep one primary capability or workflow outcome per request. For a
+ substantial provider, public contract, or architecture change, explain
+ the decision maintainers need to make before implementation.
+
+ - type: checkboxes
+ id: before-submitting
+ attributes:
+ label: Before submitting
+ options:
+ - label: I searched the open and closed issues and pull requests for a related proposal.
+ required: true
+ - label: I removed credentials, tokens, private paths, and sensitive target data.
+ required: true
+
+ - type: dropdown
+ id: area
+ attributes:
+ label: Area
+ options:
+ - Setup, packaging, or upgrade
+ - Provider or capability discovery
+ - Process capture or runtime observation
+ - Native analysis or decompilation
+ - Evidence, artifacts, or reconstruction
+ - CLI
+ - MCP or agent integration
+ - Documentation
+ - Other
+ validations:
+ required: true
+
+ - type: textarea
+ id: current-limitation
+ attributes:
+ label: Current limitation
+ description: What user or agent workflow is blocked, ambiguous, or unnecessarily difficult today?
+ validations:
+ required: true
+
+ - type: textarea
+ id: use-cases
+ attributes:
+ label: Use cases
+ description: Give concrete applications, targets, callers, or investigation workflows. Explain why current tools are insufficient.
+ validations:
+ required: true
+
+ - type: textarea
+ id: desired-outcome
+ attributes:
+ label: Desired outcome and success criteria
+ description: Describe observable behavior, inputs, outputs, evidence, and compatibility criteria that would make this useful.
+ validations:
+ required: true
+
+ - type: textarea
+ id: boundaries
+ attributes:
+ label: Authority boundaries and non-goals
+ description: Call out process execution, target mutation, provider licensing, evidence provenance, supported platforms, and work that should remain out of scope.
+
+ - type: textarea
+ id: alternatives
+ attributes:
+ label: Alternatives considered
+ description: Describe existing REA operations, upstream tools, or workarounds considered and why they do not meet the need.
+
+ - type: textarea
+ id: possible-direction
+ attributes:
+ label: Possible direction
+ description: Optional implementation or integration idea. Treat it as a proposal, not a requirement.
+
+ - type: textarea
+ id: references
+ attributes:
+ label: References
+ description: Link relevant provider documentation, source, measurements, artifacts, issues, or discussions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 8c3078530..9fd1c2086 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,34 +1,73 @@
-## Description
+<!--
+PR title: type(optional-scope): imperative outcome
+The title becomes the squash-merge commit subject and generated changelog entry.
+-->
-<!-- What does this change do? Why is it needed? -->
+## Summary
-## Type of Change
+<!-- 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. -->
-- [ ] Bug fix
-- [ ] New feature
-- [ ] Documentation update
-- [ ] Performance improvement
-- [ ] Refactoring (no functional change)
-- [ ] Tool contract change (MCP schema modification)
+## Problem and expected behavior
-## Testing Performed
+<!-- For fixes, give the smallest trigger and violated invariant. For features,
+describe the use case and observable outcome. -->
-<!-- Describe the testing you have done to verify this change. -->
+## Change and scope
-- [ ] Unit tests added or updated
-- [ ] TypeScript typecheck passes (`npm run typecheck`)
-- [ ] Linting passes (`npm run lint`)
-- [ ] Full test suite passes (`npm test`)
-- [ ] Real Hopper verification performed (`npm run verify:hopper`)
-- [ ] Linux real Hopper verification performed (`npm run verify:hopper:linux`) or unavailability explained
-- [ ] Real browser verification performed (`npm run verify:browser`) or unavailability explained
-- [ ] Package verification performed (`npm run verify:package`)
+<!-- Explain the chosen approach, why it fits REA's architecture, and what is
+intentionally not included. -->
-## Tool Contract Impact
+## Contract and boundary impact
-<!-- If this PR adds, removes, or modifies MCP tools, list them here. -->
-<!-- Canonical inventory and family counts are generated in docs/product-catalog.json. -->
+<!-- Complete the applicable lines; use "none" or "not applicable" explicitly. -->
-## Related Issues
+- Semantic owner and earliest changed stage:
+- CLI and MCP/tool-catalog contract:
+- Provider, bridge, target-format, or platform compatibility:
+- Evidence, artifact, provenance, or reconstruction contract:
+- Process execution, authorization, cleanup, or containment impact:
+- Generated metadata, package, or installation impact:
-<!-- Link issues this PR closes or relates to. Use "Closes #123" syntax. -->
+## Evidence and regression coverage
+
+<!-- State whether evidence is executed, source-derived, or proposed. For fixes,
+explain how the regression would fail on the affected base revision when practical. -->
+
+- Tests added or updated:
+- Base reproduction or other evidence:
+- User-visible CLI/MCP output (if applicable):
+- Remaining proof gaps:
+
+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. -->
+
+- `command` — result
+
+## 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:
+- Real Hopper/Ghidra, browser, or OS coverage:
+- Package or release metadata impact:
+- Security, privacy, process, or containment review:
+
+## Review checklist
+
+- [ ] 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.