docs: upstream cherry-pick recommendations from github/spec-kit sync (2026-07-27)

docs/upstream-sync-recommendations.md

@@ -0,0 +1,62 @@
+# Upstream Sync Recommendations
+
+> Auto-generated by spec-kit sync mission (2026-07-27).
+> Compares fellowship-dev/spec-kit `templates/commands/` against upstream [github/spec-kit](https://github.com/github/spec-kit).
+
+## Summary
+
+The command files in `templates/commands/` were compared against upstream. The divergences fall into five categories (note: Section 4 was initially mis-reported; see correction inline).
+
+## 1. Extension Hook System (affects all commands except `checklist.md`)
+
+**fellowship-dev addition.** Where upstream uses a one-liner:
+
+```
+Run `hooks.before_analyze` from `.specify/extensions.yml` if present.
+```
+
+fellowship-dev/spec-kit has verbose, explicit instructions covering:
+- YAML parsing and error handling
+- `enabled` flag filtering
+- `condition` expression skipping (deferred to HookExecutor)
+- Distinct rendering blocks for optional vs. mandatory hooks
+
+**Cherry-pick recommendation**: If the `.specify/extensions.yml` hook system is production-stable, open a PR to `github/spec-kit` to contribute the extension hook documentation upstream.
+
+## 2. `checklist.md` — Quality Dimension Expansion
+
+**fellowship-dev improvement.** Upstream replaced the "unit tests for English" framing with a spec-quality validation approach. fellowship-dev adds:
+
+- Explicit six-dimension framework: **Completeness**, **Clarity**, **Consistency**, **Measurability**, **Coverage**, **Edge Cases** — each with a definition
+- `[Spec §X.Y]` or `[Gap]` citation format for checklist item cross-references
+
+**Cherry-pick recommendation**: The expanded quality dimensions and citation format are clear improvements with no breaking changes. High-value upstream PR candidate.
+
+## 3. `constitution.md` — Scope Guard
+
+**fellowship-dev addition.** A new **Scope Guard** section explicitly prevents `constitution` from executing feature implementations, code generation, refactoring, or deployment requests. Instead it:
+- Classifies every part of user input as either constitution content or a non-governance intent
+- Defers non-governance intents to a `Next Actions` section
+- Suggests the appropriate follow-up Spec Kit command for each deferred intent
+
+**Cherry-pick recommendation**: This guardrail prevents scope creep in the constitution command. Strong upstream contribution candidate.
+
+## 4. `tasks.md` — No Meaningful Divergence
+
+**No divergence found.** The actual `templates/commands/tasks.md` references `scripts/bash/check-prerequisites.sh`, identical to upstream. No dedicated `setup-tasks.sh` or `setup_tasks.py` scripts exist in this repo.
+
+**Action**: No upstream contribution needed for this file; the templates are aligned.
+
+## 5. `taskstoissues.md` — `list_issues` MCP Tool
+
+**Upstream addition fellowship-dev should adopt.** Upstream `github/spec-kit` (via upstream PR #2992) adds `github/github-mcp-server/list_issues` to the tools list, enabling duplicate-detection before creating issues. fellowship-dev/spec-kit currently only has `issue_write` and does not yet include `list_issues`.
+
+**Cherry-pick recommendation**: Cherry-pick `list_issues` FROM `github/spec-kit` INTO fellowship-dev/spec-kit. This upstream improvement prevents duplicate GitHub issues during tasks-to-issues runs — a clear quality improvement that fellowship-dev should adopt.
+
+## Action Items
+
+- [ ] Contribute extension hook system documentation to `github/spec-kit`
+- [ ] Contribute `checklist.md` quality dimension improvements upstream
+- [ ] Contribute `constitution.md` scope guard upstream
+- [ ] `tasks.md` — no action needed (templates already aligned with upstream)
+- [ ] Cherry-pick `list_issues` MCP tool FROM `github/spec-kit` INTO fellowship-dev/spec-kit