Add issue approval readiness checklist (#144)

README.md

@@ -30,6 +30,7 @@ Key resources for contributors:
 - [Evaluation Readiness Dashboard](docs/evaluation-readiness.md) — Central summary page for testing standards, CI workflow, PR evidence, acceptance criteria mapping, self-review, and payment guidance
 - [Contributing Guide](CONTRIBUTING.md) — Branch naming, component rules, PR evidence checklist, and review process
 - [Evaluation-Readiness Index](docs/evaluation-readiness-index.md) — Central page linking every requirement for GrantFox evaluation: payment expectations, testing standards, CI guidance, acceptance criteria audit, self-assessment, and reviewer checklist
+- [Issue Approval Readiness Checklist](docs/issue-approval-readiness-checklist.md) — Pre-evaluation checklist for contributors and reviewers to verify implementation completeness, testing, CI, acceptance criteria, documentation, and known limitations before GrantFox evaluation
 - [PR Evidence Checklist](docs/pr-evidence-checklist.md) — Detailed requirements for pull request evidence and documentation
 - [Test-First Contribution Guide](docs/test-first-contribution-guide.md) — How to write tests before code, with area-specific patterns and examples
 - [Aegis Dashboard Minimum Testing Standard](docs/testing-standard.md) — Minimum test coverage for admin workflows, investor views, compliance screens, asset registration, minting, wallet connection, and diagnostics

docs/ci-guidance.md

@@ -48,6 +48,12 @@ npm run verify
 | Build failure | Syntax error, missing import, broken module | Check build output for specific error messages |
 | Test failure | Assertion failure, broken test | Run `npm test` locally and debug the failing test |
 
+## CI Status on PRs
+
+- All CI checks must be **green** before a PR can be merged.
+- If a CI step fails, investigate the root cause and push a fix.
+- Pre-existing failures unrelated to your change should be noted in the PR description.
+- If CI is flaky (e.g., a timeout), you may re-run the failed job from the Actions tab.
 ## CI Pass Requirement
 
 A pull request satisfies the CI pass requirement only when all four checks — **Lint**, **Type check**, **Test**, and **Build** — report a green (passing) status in GitHub Actions.

docs/evaluation-readiness-index.md

@@ -18,6 +18,8 @@ This page is the single entry point for every requirement a contributor must sat
 | Testing Evidence | [Testing Evidence Requirement](testing-evidence-requirement.md) | What evidence each PR must include (tests, screenshots, commands run) |
 | CI Guidance | [CI Guidance](ci-guidance.md) | CI pipeline steps, running checks locally, common failures and fixes |
 | Acceptance Criteria Audit | [Acceptance Criteria Audit](acceptance-criteria-audit.md) | How to map each criterion to evidence and verify completeness |
+| Self-Assessment | [Self-Assessment Checklist](self-assessment-checklist.md) | Pre-submit review checklist for contributors |
+| Reviewer Checklist | [Reviewer Quality Checklist](reviewer-checklist.md) | What reviewers check before approving a PR |
 | Self-Assessment | [Contributor Self-Assessment Form](self-assessment-checklist.md) | Pre-submit self-assessment form for contributors |
 | Reviewer Checklist | [Reviewer Quality Checklist](reviewer-checklist.md) | What reviewers check before approving a PR |
 | Reviewer Evidence | [PR Reviewer Evidence Checklist](pr-reviewer-evidence-checklist.md) | Structured reference for reviewers to verify PR evidence completeness and quality |
@@ -46,6 +48,10 @@ Ensure your change meets the minimum test coverage for the affected areas.
 
 Run `npm run verify` (or the individual commands) to confirm your branch is green.
 
+### Step 4: Complete the Self-Assessment
+→ [Self-Assessment Checklist](self-assessment-checklist.md)
+
+Work through every item on the checklist. Do not skip this step.
 ### Step 4: Complete the Self-Assessment Form
 → [Contributor Self-Assessment Form](self-assessment-checklist.md)
 

docs/issue-approval-readiness-checklist.md

@@ -0,0 +1,85 @@
+# Issue Approval Readiness Checklist
+
+> **Applies to:** All contributors and reviewers before considering an Aegis Dashboard issue resolved and ready for GrantFox evaluation
+> **Last updated:** 2026-07-29
+
+## Purpose
+
+A PR being merged does **not** automatically mean the issue is complete or ready for evaluation. This checklist helps contributors and reviewers verify that every aspect of an issue has been addressed before marking it as approval-ready. Use it as the final gate before requesting GrantFox evaluation.
+
+---
+
+## Important: Merge ≠ Evaluation
+
+Merged PRs are still subject to GrantFox evaluation. Meeting this checklist does not guarantee payment — it ensures your work is reviewable and complete. See the [Contributor Payment Guide](contributor-payment-guide.md) for full details.
+
+---
+
+## Pre-Evaluation Checklist
+
+### 1. Implementation Completeness
+
+- [ ] Every acceptance criterion from the issue is satisfied by the merged PR(s).
+- [ ] The implementation handles edge cases (empty states, error boundaries, unexpected input).
+- [ ] No `TODO`, `FIXME`, or `HACK` comments related to this issue remain unresolved.
+- [ ] The change works end-to-end as described in the issue.
+- [ ] If the issue spans multiple PRs, each PR references the same issue and the overall completion is tracked.
+
+### 2. Testing Expectations
+
+- [ ] Tests have been added or updated for every new or changed public method.
+- [ ] Test coverage meets the [Minimum Testing Standard](testing-standard.md) for the affected areas.
+- [ ] All existing tests pass (`npm test`).
+- [ ] For UI changes, screenshots or recordings are attached showing before/after at relevant viewport widths.
+- [ ] Negative-path tests exist for error states, invalid inputs, and edge cases.
+
+### 3. CI Status
+
+- [ ] All CI checks pass on the merged PR(s) — lint, type check, build, and tests.
+- [ ] No new warnings or errors were introduced by the change.
+- [ ] If a CI step failed and was resolved, the root cause and fix are documented.
+
+### 4. Acceptance Criteria Review
+
+- [ ] Every acceptance criterion from the issue is mapped to concrete, verifiable evidence.
+- [ ] Evidence points to specific files, test names, or screenshots — not vague statements.
+- [ ] No criterion is left unchecked without a documented justification.
+- [ ] The PR description includes a traceability table or criteria mapping section.
+
+### 5. Documentation
+
+- [ ] New features or behavioural changes are reflected in the relevant documentation.
+- [ ] API changes are documented in the appropriate docs.
+- [ ] If the change affects setup, usage, or contribution flow, README is updated.
+- [ ] Screenshots or diagrams are included where they aid understanding.
+
+### 6. Known Limitations
+
+- [ ] Any known limitations, trade-offs, or follow-up work are documented in the PR or issue comments.
+- [ ] If the issue was intentionally only partially addressed, the remaining work is tracked in a follow-up issue.
+- [ ] Performance implications, if any, are noted.
+
+---
+
+## Self-Review Flow
+
+Before requesting GrantFox evaluation:
+
+1. Open the merged PR(s) and verify CI is green.
+2. Walk through each section of this checklist.
+3. Check off every item. If any item cannot be checked, fix it or document why.
+4. Confirm the PR description contains all required evidence (issue reference, acceptance criteria mapping, test output, screenshots).
+5. Add a comment on the issue confirming the checklist is complete and requesting evaluation.
+
+---
+
+## Related Documents
+
+- [Contributor Payment Guide](contributor-payment-guide.md) — GrantFox evaluation criteria and merge-vs-payment distinction
+- [Self-Assessment Checklist](self-assessment-checklist.md) — Pre-submit review for contributors before opening a PR
+- [Acceptance Criteria Audit](acceptance-criteria-audit.md) — Criteria-to-evidence mapping process
+- [CI Guidance](ci-guidance.md) — CI pipeline steps and local verification
+- [Minimum Testing Standard](testing-standard.md) — Test coverage requirements
+- [PR Evidence Checklist](pr-evidence-checklist.md) — PR description structure
+- [Reviewer Quality Checklist](reviewer-checklist.md) — What reviewers check
+- [Evaluation-Readiness Index](evaluation-readiness-index.md) — Central resource index

docs/self-assessment-checklist.md

@@ -1,10 +1,12 @@
+# Self-Assessment Checklist
 # Contributor Self-Assessment Form
 
 > **Applies to:** All contributors before submitting a pull request to the Aegis Dashboard
 > **Last updated:** 2026-07-29
 
 ## Purpose
 
+This checklist helps contributors self-review their own work before requesting a maintainer review. Completing this checklist reduces review cycles, catches common issues early, and ensures GrantFox evaluation readiness.
 This self-assessment form helps contributors evaluate their own work before requesting a maintainer review. Completing this form reduces review cycles, catches common issues early, and ensures GrantFox evaluation readiness.
 
 ## Instructions
@@ -72,6 +74,7 @@ Branch Name: ________________________
 - [ ] "Acceptance Criteria Coverage" section maps each criterion to evidence.
 - [ ] Screenshots section is populated for UI changes.
 
+## Post-Submit
 ---
 
 ## Declaration