diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 17bff95..c62564e 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,14 +6,15 @@ ## Completion Table - -| Acceptance Criterion | Status | Implementation Evidence | Test Evidence | -| :--- | :---: | :--- | :--- | -| **AC 1**: | Complete / Partial / Not Met | | | -| **AC 2**: | Complete / Partial / Not Met | | | +| Acceptance Criterion | Status | Implementation Evidence | Test Evidence | Documentation Impact | +| :--- | :---: | :--- | :--- | :--- | +| **AC 1**: | Complete / Partial / Not Met | | | Updated file(s), or N/A with reason | +| **AC 2**: | Complete / Partial / Not Met | | | Updated file(s), or N/A with reason | > **Incomplete criteria must include a reason and follow-up plan.** See Handling Incomplete Criteria in docs/traceability-mapping.md. @@ -69,6 +70,8 @@ for detailed guidance. ### 6. Acceptance Criteria Coverage - [ ] Every acceptance criterion from the issue is addressed in the Completion Table above. +- [ ] Documentation impact is recorded for every criterion, including an + explicit `N/A` with a reason when no documentation changes are needed. - [ ] Incomplete criteria include a rationale and, where applicable, a link to a follow-up issue. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 417e2a6..2d3051b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ We welcome open-source contributions to make the Aegis Protocol more robust! 5. **Formatting:** Ensure `cargo fmt` and `cargo clippy` pass before opening a PR. `make ci` runs the complete gate (`fmt-check` + `clippy` + `test` + `build`) in one command. 6. **PR Evidence Checklist:** Before requesting review, complete the [PR Evidence Checklist](docs/pr-evidence-checklist.md) in your PR description. This covers issue reference, implementation summary, tests, commands run, CI status, and acceptance criteria coverage — making review more objective. 7. **Self-Review:** Before requesting review, fill out the [Contributor Self-Review Form](docs/contributor-self-review-form.md) and include it in your PR. This covers requirements, implementation completeness, testing evidence, CI status, documentation updates, and known limitations. -8. **Completion Table:** You MUST include a [Completion Table](docs/traceability-mapping.md#completion-table-format) in your PR description, mapping every acceptance criterion to its status (Complete/Partial/Not Met), implementation evidence, and test evidence. For complex PRs, also include the [Detailed Traceability Mapping Table](docs/traceability-mapping.md#detailed-traceability-table-format-advanced). +8. **Completion Table:** You MUST include a [Completion Table](docs/traceability-mapping.md#completion-table-format) in your PR description, mapping every acceptance criterion to its status (Complete/Partial/Not Met), implementation evidence, test evidence, and documentation impact (or an explicit `N/A` with a reason). For complex PRs, also include the [Detailed Traceability Mapping Table](docs/traceability-mapping.md#detailed-traceability-table-format-advanced). ## Discussion -Join our ecosystem discussion before undertaking large architectural changes. Find the `// TODO:` comments in the source code for good places to start contributing. \ No newline at end of file +Join our ecosystem discussion before undertaking large architectural changes. Find the `// TODO:` comments in the source code for good places to start contributing. diff --git a/docs/evaluation-readiness.md b/docs/evaluation-readiness.md index 7ccdf03..4f7c398 100644 --- a/docs/evaluation-readiness.md +++ b/docs/evaluation-readiness.md @@ -89,13 +89,13 @@ Every PR must include a completion table in its description mapping each accepta ### Completion Table format: -| Acceptance Criterion | Status | Implementation Evidence | Test Evidence | -| :--- | :---: | :--- | :--- | -| **AC 1**: Brief description | Complete | `fn name()` — link or description | `test_name` — file:line | -| **AC 2**: ... | Partial | Reason and what was done | Tests that exist | -| **AC 3**: ... | Not Met | Explanation | N/A | +| Acceptance Criterion | Status | Implementation Evidence | Test Evidence | Documentation Impact | +| :--- | :---: | :--- | :--- | :--- | +| **AC 1**: Brief description | Complete | `fn name()` — link or description | `test_name` — file:line | `docs/page.md` updated | +| **AC 2**: ... | Partial | Reason and what was done | Tests that exist | Follow-up docs needed | +| **AC 3**: ... | Not Met | Explanation | N/A | N/A — no behavior changed | -**Status** must be one of: **Complete** (fully satisfied), **Partial** (known gaps with explanation), or **Not Met** (not addressed with rationale). +**Status** must be one of: **Complete** (fully satisfied), **Partial** (known gaps with explanation), or **Not Met** (not addressed with rationale). The Documentation Impact column must name each affected document or use an explicit `N/A` with a short reason. ### Detailed Traceability Table (for complex PRs): diff --git a/docs/pr-evidence-checklist.md b/docs/pr-evidence-checklist.md index cbce7de..7b5f4d3 100644 --- a/docs/pr-evidence-checklist.md +++ b/docs/pr-evidence-checklist.md @@ -42,7 +42,8 @@ acceptance criterion, test outcome, command run, and CI result. - [ ] Every acceptance criterion from the issue is addressed. - [ ] The [Completion Table](./traceability-mapping.md#completion-table-format) in the PR description maps each criterion to its status - (Complete/Partial/Not Met), implementation evidence, and test evidence. + (Complete/Partial/Not Met), implementation evidence, test evidence, and + documentation impact (or an explicit `N/A` with a reason). - [ ] Incomplete criteria include a rationale and, where applicable, a link to a follow-up issue. @@ -76,7 +77,7 @@ Maintainers should verify each item: | Tests | Tests exist, pass, and cover the change | | Commands Run | The output shows no errors or warnings | | CI Status | The CI badge or screenshot shows green | -| Acceptance Criteria | Every criterion in the issue is mapped in the Completion Table | +| Acceptance Criteria | Every criterion in the issue is mapped to status, implementation, tests, and documentation impact in the Completion Table | If any item is missing or insufficient, request clarification before proceeding with a full code review. diff --git a/docs/traceability-mapping.md b/docs/traceability-mapping.md index 9121bd1..ca52c39 100644 --- a/docs/traceability-mapping.md +++ b/docs/traceability-mapping.md @@ -2,17 +2,20 @@ To ensure high-quality engineering and evaluation readiness, all contract changes must be mapped to their respective acceptance criteria. This documentation defines the standard traceability table format required for all Pull Requests (PRs). +The Completion Table is the canonical acceptance criteria audit template used +for every PR. + ## Completion Table Format Every PR must include a completion table in its description mapping each acceptance criterion to its status and evidence. This table helps contributors self-evaluate before payment day and makes review expectations clear. ### Table Structure -| Acceptance Criterion | Status | Implementation Evidence | Test Evidence | -| :--- | :---: | :--- | :--- | -| **AC 1**: Brief description | Complete | `fn name()` — link to line or brief description | `test_name` — file:line | -| **AC 2**: ... | Partial | Reason and what was done | Tests that exist | -| **AC 3**: ... | Not Met | Explanation | N/A | +| Acceptance Criterion | Status | Implementation Evidence | Test Evidence | Documentation Impact | +| :--- | :---: | :--- | :--- | :--- | +| **AC 1**: Brief description | Complete | `fn name()` — link to line or brief description | `test_name` — file:line | `docs/page.md` updated | +| **AC 2**: ... | Partial | Reason and what was done | Tests that exist | Follow-up docs needed | +| **AC 3**: ... | Not Met | Explanation | N/A | N/A — no behavior changed | ### Status Definitions @@ -22,14 +25,24 @@ Every PR must include a completion table in its description mapping each accepta | **Partial** | The criterion is partially addressed but has known gaps (must explain why in the evidence column). | | **Not Met** | The criterion is not addressed in this PR (must explain why in the evidence column). | +### Documentation Impact Evidence + +For every criterion, use the **Documentation Impact** column to identify the +README, contributor guide, API reference, specification, or other document +that changed. Write `N/A` with a short reason when the criterion has no +documentation impact. Do not leave the column blank: an explicit `N/A` tells +reviewers that documentation impact was assessed rather than overlooked. + ### Handling Incomplete Criteria If any acceptance criterion is marked **Partial** or **Not Met**: 1. **Explain why** in the Implementation Evidence column (e.g., "scope limited — criterion deferred to follow-up PR", "blocked by upstream dependency", "out of scope for this issue"). 2. **Link to a follow-up issue** if the criterion is intentionally deferred. -3. **Do not request payment evaluation** for incomplete criteria — payment is assessed against full acceptance criteria coverage. -4. Reviewers may reject a PR with incomplete criteria unless a clear, accepted rationale is provided and the incomplete items are explicitly scoped out. +3. **Record documentation impact** for the work that is complete and note any + deferred documentation in the Documentation Impact column. +4. **Do not request payment evaluation** for incomplete criteria — payment is assessed against full acceptance criteria coverage. +5. Reviewers may reject a PR with incomplete criteria unless a clear, accepted rationale is provided and the incomplete items are explicitly scoped out. > If you cannot mark all criteria Complete, be honest about it. Incomplete criteria with clear explanations and follow-up plans are accepted more readily than claims of completeness that don't hold up under review.