chore(issues): enforce production-ready issue standards - #93
Conversation
Dyu20705
left a comment
Dyu20705
left a comment
There was a problem hiding this comment.
Review verdict: changes requested before marking this draft ready.
The overall direction is strong: the forms are proportional by work type, the managed-issue metadata check is useful, the live reconciliation plan is explicit, and CI #173 passed against the current main merge commit. Two contract gaps remain:
- The new fail-closed test only greps for field IDs, so it does not prove that required fields are actually required or that GitHub can parse the forms.
- The combined research/design form generates a title prefix that the new standard does not permit.
After these are corrected, rerun the policy test and CI on the updated head. Non-blocking maintainability note: keep ISSUE_STANDARD.md and ROADMAP_OPERATING_MODEL.md linked rather than allowing Definition of Ready/WIP rules to drift between two documents.
There was a problem hiding this comment.
Pull request overview
This PR hardens the repo’s GitHub Issue system by adding a production-ready issue taxonomy, introducing/strengthening structured public intake forms, documenting a type-aware operating standard, and adding CI-enforced regression tests to fail closed when contracts drift.
Changes:
- Add new
type:*taxonomy labels andstatus:needs-triage, and update roadmap docs to reference the new standard. - Introduce
docs/process/ISSUE_STANDARD.mdto define type-specific readiness/closure evidence, workflow states, and traceability rules. - Add a new test suite (
tests/roadmap/test-issue-standard.sh+ Ruby form validator) and run it in CI to enforce issue-form structure and managed-issue minimum contracts.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| tests/roadmap/validate-issue-forms.rb | Adds a strict Ruby validator for issue-form YAML structure and expected contracts/labels. |
| tests/roadmap/test-issue-standard.sh | Adds a shell test suite enforcing taxonomy, form presence/validity, managed-issue metadata contracts, and policy doc requirements. |
| roadmap/README.md | Documents the new production issue standard and adds the new test to the local/CI checklist. |
| roadmap/labels.json | Adds new taxonomy/triage labels used by forms and tests. |
| docs/process/ISSUE_STANDARD.md | Defines the durable, type-aware issue operating standard (readiness, DoD, workflow, evidence safety, PR linkage). |
| .github/workflows/ci.yml | Executes the new issue-standard test suite in CI. |
| .github/ISSUE_TEMPLATE/research_design.yml | Adds a dedicated research/design intake form with required decision/hand-off fields. |
| .github/ISSUE_TEMPLATE/feature_request.yml | Strengthens proposal intake (triage label, impact, scope, non-goals, dependencies, quality/rollback expectations). |
| .github/ISSUE_TEMPLATE/data_correction.yml | Adds a dedicated source-backed data/content correction intake form. |
| .github/ISSUE_TEMPLATE/bug_report.yml | Strengthens bug intake (triage label, impact/regression/workaround, more explicit environment/evidence guidance). |
| .github/ISSUE_TEMPLATE/accessibility_report.yml | Adds a dedicated accessibility barrier intake form with AT/input-method context requirements. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| jq -s -e ' | ||
| [.[].issues[]] | ||
| | all(.[ ]; | ||
| select((.state // "open") == "open" and .phase != "cleanup") | ||
| | ((.labels // []) | map(select(startswith("type:"))) | length) == 1 | ||
| and ((.labels // []) | map(select(startswith("priority:"))) | length) == 1 | ||
| and ((.assignees // []) | length) >= 1 | ||
| and (.milestone != null) | ||
| and ((.key == "web-mvp-roadmap") or (.parent != null)) | ||
| and ((.outcome // "") | length) > 0 | ||
| and ((.scope // []) | length) > 0 | ||
| and ((.acceptanceCriteria // []) | length) > 0 | ||
| and ((.definitionOfDone // []) | length) > 0) | ||
| ' "$ROOT"/roadmap/issues/*.json >/dev/null || fail 'an active managed issue lacks one type, one priority, ownership, hierarchy, scope, acceptance criteria, or DoD' |
Outcome
Strengthen the repository's GitHub Issue system so public intake and roadmap-managed work use explicit, proportional, type-aware, and verifiable contracts instead of generic checklists.
Refs #34 and #53.
Scope
Included
docs/process/ISSUE_STANDARD.mdfor title conventions, required metadata, type-specific readiness/closure evidence, workflow transitions, handoff, PR linkage, and evidence safety;docs/process/ROADMAP_OPERATING_MODEL.md.Excluded
Review fixes
P1 — Schema-aware Issue Form enforcement
Replaced presence-only
grepchecks withtests/roadmap/validate-issue-forms.rb, using Ruby's standard-library YAML parser.The validator now checks:
config.ymlparses as YAML;validations.required: truefor mandatory fields;roadmap/labels.json;blank_issues_enabled: false;Mutation self-tests prove the validator rejects malformed YAML,
required: false, wrong field types, duplicate IDs, wrong titles, and wrong labels. The self-test helper itself fails when a mutation unexpectedly passes.P2 — Research/design title contract
[Research/Design]is now explicitly defined as a combined untriaged intake prefix. During triage it must be normalized to[Research]or[Design], with exactly one correspondingtype:*label, before the issue enters managed work or is marked Ready.The standard now links to
ROADMAP_OPERATING_MODEL.mdinstead of maintaining a competing numeric WIP policy.RED → GREEN evidence
Original taxonomy RED
CI #159 reached the new policy test after existing roadmap tests passed, then failed as intended:
Review-fix RED
CI #174 proved the new schema-aware test was active and failed because the validator had not yet been implemented:
CI #175 then proved P1 passed while P2 was still unresolved:
Final GREEN
Final head:
e96d3f84c72a8e10cdb5f026624f1b598db1cc3fCI #177 completed successfully on the pull-request merge commit against current
main:roadmap-automation: success--dry-run --force-updateplan;check: successBoth P1 and P2 review threads are resolved.
Final diff
+959/-18;tests/roadmap/validate-issue-forms.rb;Reviewed live reconciliation plan
The authoritative dry-run still plans only the documented post-merge operations:
No write operation was executed by CI.
Post-merge operation
Run the existing authorized roadmap apply from the reviewed default-branch state with
--force-update, then rerun the authoritative dry-run. Treat live state as reconciled only when the plan contains expected no-ops and intentional superseded skips with no unexplained issue, label, parent, dependency, assignee, or milestone drift.Rollback
Revert this focused PR. If live reconciliation has already run, execute the tested apply/dry-run workflow from the reverted canonical state to restore the previous labels, bodies, and relationships.