docs: upstream spec-kit improvements to consider (2026-07-20)

docs/upstream-improvements-2026-07-20.md

@@ -0,0 +1,113 @@
+# Upstream spec-kit Improvements to Consider (2026-07-20)
+
+> Generated by automated spec-kit sync on 2026-07-20.
+> Upstream: `github/spec-kit` | Current fork sync point: v0.8.1 | Upstream current: v0.13.0
+
+## Upstream Status
+
+No bulk sync recommended — upstream v0.9–v0.13 made deep changes to the Python CLI, workflows engine, and
+integration layer that are out of scope for our Claude-native fork. The items below are scoped to
+command-template improvements that are directly applicable.
+
+---
+
+## Recommended Cherry-Picks
+
+### 1. New command: `speckit.converge` (HIGH VALUE)
+
+**Upstream PR**: #3001 `feat: add /speckit.converge command`
+
+Assesses the current codebase against spec/plan/tasks and appends any remaining unbuilt work as new tasks
+to `tasks.md` so `/speckit.implement` can complete it. Useful when implementation was interrupted or
+partially completed.
+
+**Recommendation**: Add `templates/commands/converge.md` and a lean variant in `presets/lean/commands/`
+with terse rewrite (≤40 lines per fork convention).
+
+---
+
+### 2. Hook enforcement directive (MEDIUM VALUE)
+
+**Upstream PR**: #2901 `fix(extensions): tell agent to run mandatory hooks, not just emit the directive`
+
+All command templates now include an explicit instruction after each hook block:
+
+```
+After emitting the block above you MUST actually invoke the hook and wait for it to finish before
+continuing. Run it the same way you would run the command yourself in this agent/session (the invocation
+may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as
+`/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook.
+```
+
+Fixes a compliance gap where agents emit the hook directive but do not actually execute it.
+
+**Recommendation**: Cherry-pick into all 9 command templates. Low-risk, improves hook reliability.
+
+---
+
+### 3. Fix: `speckit.taskstoissues` deduplication (HIGH VALUE)
+
+**Upstream PR**: #2992 `fix(taskstoissues): skip tasks that already have a GitHub issue`
+
+Before creating issues, the command now:
+1. Adds `list_issues` to the `tools` frontmatter
+2. Fetches all existing issues and matches against task IDs (`\bT\d{3}\b`)
+3. Skips tasks that already have a matching issue and reports them
+
+Prevents duplicate issues when the command is re-run after tasks.md is regenerated.
+
+**Recommendation**: High-value fix. Cherry-pick into `templates/commands/taskstoissues.md`.
+
+---
+
+### 4. Fix: `speckit.implement` loads constitution for governance (MEDIUM VALUE)
+
+**Upstream PR**: #2460 `Load constitution context in /speckit.implement to enforce governance`
+
+Adds a step to read `/memory/constitution.md` during context loading, so governance constraints are
+enforced during code generation (consistent with how `checklist.md` and `taskstoissues.md` already load it).
+
+---
+
+### 5. Fix: `speckit.constitution` — generalize command file scanning (MEDIUM VALUE)
+
+**Upstream PR**: #3418 `fix(templates): point constitution sync checklist at installed command files`
+
+The constitution sync checklist previously referenced `.specify/templates/commands/*.md` (upstream path).
+Now scans for installed commands named `speckit.*` or `speckit-*` in the agent's actual commands directory
+(e.g., `.claude/commands/`). Directly relevant to our Claude setup.
+
+---
+
+### 6. Rename: `branch_numbering` → `feature_numbering` (LOW VALUE)
+
+`init-options.json` key `branch_numbering` is deprecated in favor of `feature_numbering`. The command emits
+a deprecation warning if only `branch_numbering` is present.
+
+**Recommendation**: Low urgency — add warning when consumer repos actually use `branch_numbering`.
+
+---
+
+## Already Applied
+
+- Checklist 6 named quality dimensions (Completeness/Clarity/Consistency/Measurability/Coverage/Edge Cases)
+  — cherry-picked in fellowship-dev fork PR #4. ✅
+
+---
+
+## Out of Scope
+
+- Python CLI changes (`py:` scripts, `scripts/python/` directory) — fork targets Claude/LLM agents, not the `specify` CLI
+- Workflow engine changes (fan-out, fan-in, concurrency)
+- Integration layer (Grok, Kiro, Azure DevOps, Firebender, OMP)
+- Python git extension ports — bash scripts are intentional for this fork
+
+---
+
+## Priority Order
+
+1. `speckit.converge` new command
+2. `speckit.taskstoissues` dedup fix
+3. Hook enforcement directive (all templates)
+4. `speckit.implement` constitution load
+5. `speckit.constitution` command scanning fix