Add docs issue form and tighten issue triage response targets

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,55 @@
+name: Bug report
+about: Report a defect that is reproducible and impacts expected behavior
+labels: [bug]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Problem summary
+      description: What happened vs what should happen?
+      placeholder: Actual behavior / Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction steps
+      description: Provide exact steps, inputs, and data needed to reproduce
+      placeholder: |
+        1. ...
+        2. ...
+        3. ...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: plane
+    attributes:
+      label: Affected plane
+      options:
+        - Control Plane
+        - Orchestration Plane
+        - Execution Plane
+        - Observability Plane
+    validations:
+      required: true
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Suggested priority
+      description: Use triage matrix from docs/issue-triage.md
+      options:
+        - P0
+        - P1
+        - P2
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Runtime, versions, deployment context
+      placeholder: OS / versions / branch / commit

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Contribution guide
+    url: https://github.com/monthop-gmail/devfactory-core/blob/main/CONTRIBUTING.md
+    about: Read contribution conventions before opening an issue.

.github/ISSUE_TEMPLATE/docs-improvement.yml

@@ -0,0 +1,36 @@
+name: Docs improvement
+about: Suggest documentation fixes or improvements
+labels: [docs]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Documentation problem
+      description: What is missing, unclear, or incorrect?
+    validations:
+      required: true
+
+  - type: textarea
+    id: location
+    attributes:
+      label: Affected files/sections
+      description: List files or URLs if known
+      placeholder: docs/roadmap.md, README.md, ...
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed improvement
+      description: What should be changed?
+    validations:
+      required: true
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: Suggested priority
+      options:
+        - P1
+        - P2
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/governance-change.yml

@@ -0,0 +1,33 @@
+name: Governance or architecture change
+about: Propose changes that affect policy, risk, approvals, or architecture direction
+labels: [governance, architecture]
+body:
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: Describe the change and intended outcome
+    validations:
+      required: true
+
+  - type: textarea
+    id: alignment
+    attributes:
+      label: Direction-lock alignment
+      description: Explain alignment with governance-first architecture and plane separation
+    validations:
+      required: true
+
+  - type: textarea
+    id: risk
+    attributes:
+      label: Risk and approval impact
+      description: What risks are introduced? Any human-in-the-loop requirement changes?
+    validations:
+      required: true
+
+  - type: input
+    id: rfc
+    attributes:
+      label: Related RFC (optional)
+      placeholder: rfcs/xxxx-*.md

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,28 @@
+name: Question
+about: Ask a scoped implementation or architecture question
+labels: [question]
+body:
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      description: What do you need clarified?
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: Relevant files, docs, links, and constraints
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Related area
+      options:
+        - Core State Machine
+        - Governance Engine
+        - Orchestration Foundation
+        - Observability
+        - Documentation / Process

docs/issue-triage.md

@@ -0,0 +1,50 @@
+# Issue Triage Guide
+
+This guide defines a lightweight process for handling incoming GitHub issues in `devfactory-core`.
+
+## 1) Intake
+- Confirm the issue is reproducible.
+- Collect: expected behavior, actual behavior, reproduction steps, and environment.
+- Tag with one of: `bug`, `docs`, `architecture`, `governance`, `question`.
+- Prefer structured issue forms in `.github/ISSUE_TEMPLATE/*.yml` to normalize inputs.
+- Ensure labels are from the supported set: `bug`, `docs`, `architecture`, `governance`, `question`.
+
+### Intake from restricted environments
+If GitHub API access is blocked (e.g., `403` from unauthenticated requests):
+- Use the issue web URL and manually capture title/body/comments into triage notes.
+- Request a token-backed mirror process in CI for `issues.json` export.
+- Do not block triage; continue with reproducibility and alignment checks using available context.
+
+## 2) Alignment Check
+Before implementation, verify alignment with project direction:
+- Governance-first infrastructure
+- Control/Orchestration/Execution/Observability plane separation
+- Explicit state-machine workflows
+
+Reject or defer issues that push the project toward chatbot-only or SaaS-MVP scope.
+
+## 3) Prioritization
+Use this simple matrix:
+- **P0**: breaks architecture direction or blocks core state machine work
+- **P1**: major feature gap within existing roadmap
+- **P2**: quality/docs/ergonomics
+
+## 4) Resolution Checklist
+- Add/update docs and architecture notes where behavior is defined.
+- Reference related RFCs when introducing process or policy changes.
+- Record follow-up tasks in `docs/roadmap.md`.
+
+## 5) Close Criteria
+Close an issue only when all are true:
+- Reproduction no longer fails (or docs clarify intentional behavior)
+- Scope is aligned with project direction lock
+- Linked commit/PR clearly documents the change
+
+## 6) Response targets
+- **First response:** within 1 business day for P0/P1, 3 business days for P2.
+- **Triage decision:** within 2 business days after first response.
+
+## 7) Weekly issue operations cadence
+- **Daily:** 15-minute intake sweep and label hygiene.
+- **Twice weekly:** prioritization review for P0/P1 items.
+- **Weekly:** roadmap mapping check (every open issue must map to a phase, or be explicitly deferred).

docs/roadmap.md

@@ -1 +1,22 @@
-Phase 1: Core State Machine
+# Roadmap
+
+## Phase 1: Core State Machine
+- Define canonical states for intake, plan, execute, review, and merge.
+- Document transition guards and approval requirements.
+- Produce an RFC for error and retry semantics.
+
+## Phase 2: Governance Engine
+- Add policy model for risk classification and escalation.
+- Define human-in-the-loop checkpoints and override paths.
+- Specify immutable audit logging requirements.
+
+## Phase 3: Orchestration Foundation
+- Document task decomposition and agent assignment strategy.
+- Define retry and timeout policies per task type.
+- Specify provider isolation and cost-control constraints.
+
+## Cross-cutting: Issue Operations
+- Standardize issue triage with `docs/issue-triage.md`.
+- Enforce structured issue forms and labels (`bug`, `docs`, `question`, `governance`, `architecture`).
+- Use priority classes (P0/P1/P2).
+- Ensure issues map to roadmap phases or direction-lock decisions.