diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 3b45b027c1..0000000000 --- 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 0000000000..f93e9f7bd9 --- /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 0000000000..912e18c44a --- /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 38602f41a7..0000000000 --- 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 0000000000..fa2bc024ea --- /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 97d2d892e0..0000000000 --- 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 0000000000..7b0767b276 --- /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 8c3078530b..9fd1c2086b 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,34 +1,73 @@ -## Description + - +## Summary -## Type of Change + -- [ ] Bug fix -- [ ] New feature -- [ ] Documentation update -- [ ] Performance improvement -- [ ] Refactoring (no functional change) -- [ ] Tool contract change (MCP schema modification) +## Problem and expected behavior -## Testing Performed + - +## 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`) + -## Tool Contract Impact +## Contract and boundary impact - - + -## 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: - +## Evidence and regression coverage + + + +- 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 + + + +- `command` — result + +## Compatibility, safety, and release + + + +- 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.