Upstream improvements to cherry-pick from github/spec-kit

[pylot-app]

Problem Statement

The fellowship-dev fork of spec-kit has drifted from upstream in ways that cause real defects: taskstoissues.md creates duplicate GitHub issues on re-runs, agents emit hooks without executing them, constitution.md scans the wrong file path, and the converge recovery command is missing entirely. These gaps silently degrade the reliability of spec-kit workflows across all consumer repos. An audit against upstream v0.16.1 (2026-08-10) identified 6 actionable cherry-picks.

User Stories

• As a fellowship-dev contributor running /speckit.taskstoissues, I want duplicate issue detection so that re-running after tasks.md regeneration doesn't flood the issue tracker.
• As an agent executing a spec-kit command, I want mandatory hook enforcement text so that I actually run hooks rather than just emit the directive.
• As a fork maintainer, I want the constitution.md path scanner to point at the installed location (.claude/commands/speckit.*) so constitution sync checks work correctly.
• As a developer whose implementation was interrupted, I want /speckit.converge to assess and append remaining work so I can resume without losing track of what was already built.

Success Metrics

• 0 duplicate issues created on re-run of /speckit.taskstoissues after tasks.md regeneration
• All 9 command templates include hook enforcement directive (verifiable by grep)
• constitution.md path scanner references .claude/commands/speckit.* (not .specify/templates/)
• speckit.converge command exists and produces an append-only ## Phase N: Convergence section
• implement.md conditionally loads /memory/constitution.md in step 3

Measurable Impact

• Hypothesis: Implementing these template fixes will maintain the pr_merged rate and reduce time-to-merge by eliminating re-work caused by duplicate issues, missed hook execution, and interrupted implementations.
• Baseline: pr_merged: 98.6% (30d avg, n=577) | time_to_merge_hours: 4.06h (30d avg, n=569)
• Target: pr_merged: maintain ≥98% (guard against regression from template breakage). time_to_merge_hours: ≤3.5h (target 14% reduction via fewer re-work cycles and cleaner agent runs).
• Experiment plan: Monitor via outcomes API post-merge; link to relevant Phase 2 experiment if applicable.
• Eval criteria: Regression triggers auto-issue if pr_merged drops >3pp or time_to_merge_hours increases >20% after these template changes land.

Scope

In Scope

• HIGH: Add templates/commands/converge.md and presets/lean/commands/speckit.converge.md (≤40 lines)
• HIGH: Add list_issues deduplication to templates/commands/taskstoissues.md
• MEDIUM: Add conditional constitution read to step 3 of templates/commands/implement.md
• MEDIUM: Add hook enforcement directive after each hook block in all 9 templates/commands/*.md files
• MEDIUM: Fix command file path in templates/commands/constitution.md to .claude/commands/speckit.*
• LOW: Add branch_numbering → feature_numbering deprecation warning in init-options.json or docs

Out of Scope

• Python CLI changes (excluded by prior decision — this fork is Claude-native only)
• Outbound contribution PRs to github/spec-kit (listed as opportunities, not action items)
• Consumer repo updates — handled by weekly drift-check automation
• Auto-merging any upstream changes without manual CTO review

Technical Requirements

• converge.md must be append-only: reads spec.md, plan.md, tasks.md; appends a ## Phase N: Convergence section; makes no code changes
• converge.md must flag constitution violations as CRITICAL severity and hand off to implement or PR review
• taskstoissues.md deduplication uses list_issues with cursor-paginated perPage: 100; task ID match regex is \bT\d{3}\b
• implement.md constitution read is strictly conditional: IF EXISTS /memory/constitution.md; insert at step 3 only
• Hook enforcement text is added after the existing one-liner, not replacing it
• presets/lean/commands/speckit.converge.md must be ≤40 lines per fork convention
• init-options.json deprecation warning must not touch any Python source code

Implementation Constraints

Anti-patterns

• Do NOT copy Python CLI code from upstream — this fork is Claude-native only
• Do NOT modify presets/lean/commands/ for the hook enforcement item (standard templates only)
• Do NOT create taskstoissues.md in the lean preset (it does not exist there)
• Do NOT treat the "Contribution opportunities" section as work items for this issue
• Do NOT push directly to main — every cherry-pick must be a PR for CTO review
• Do NOT modify consumer repos; those are handled by the weekly drift-check automation

Scope fences

• speckit.converge: only create templates/commands/converge.md and presets/lean/commands/speckit.converge.md
• taskstoissues.md dedup: only modify templates/commands/taskstoissues.md
• implement.md constitution: only modify templates/commands/implement.md, step 3
• Hook enforcement: only modify the 9 files in templates/commands/ (analyze.md, checklist.md, clarify.md, constitution.md, implement.md, plan.md, specify.md, tasks.md, taskstoissues.md)
• constitution.md path: only modify the one path reference in templates/commands/constitution.md
• branch_numbering: only modify init-options.json or docs; no Python code

Patterns to follow

• Lean command structure: derive from presets/lean/commands/speckit.implement.md (canonical ≤40-line pattern)
• Existing hook one-liner to preserve: Run hooks.X from .specify/extensions.yml if present.
• Task ID regex for dedup: \bT\d{3}\b (upstream PR fix(taskstoissues): skip tasks that already have a GitHub issue github/spec-kit#2992)

Testing Strategy

Prerequisites

• A scratch repo with spec-kit installed from the PR branch (for converge spot-check)

Pre-merge Verification

• templates/commands/converge.md exists and is valid markdown
• presets/lean/commands/speckit.converge.md exists and is ≤40 lines
• Converge template is append-only (no step modifies spec.md, plan.md, or source code)
• Converge reads spec.md, plan.md, tasks.md in context step
• taskstoissues.md frontmatter includes list_issues in tools list
• Deduplication step appears BEFORE the issue-creation loop in taskstoissues.md
• Pagination uses cursor-based perPage: 100; regex is \bT\d{3}\b
• implement.md step 3 includes IF EXISTS /memory/constitution.md conditional (steps 1–2 unchanged)
• All 9 templates/commands/*.md files have enforcement text after each hook block
• presets/lean/commands/ is NOT modified for hook enforcement
• constitution.md references .claude/commands/speckit.* (not .specify/templates/commands/*.md)
• init-options.json includes deprecation warning for branch_numbering; no Python code changed

Post-merge Verification

• [prod access required] Run /speckit.converge in a repo with partially-implemented tasks.md; confirm append-only ## Phase N: Convergence section
• [prod access required] Re-run /speckit.taskstoissues in a repo with existing issues; confirm no duplicate issues created

Dependencies

• Upstream PRs: feat: add /speckit.converge command github/spec-kit#3001 (converge), fix(taskstoissues): skip tasks that already have a GitHub issue github/spec-kit#2992 (taskstoissues dedup), Load constitution context in /speckit.implement to enforce governance during implementation github/spec-kit#2460 (implement constitution), fix(extensions): make mandatory-hook dispatch contract self-contained github/spec-kit#2901 (hook enforcement), fix(templates): point constitution sync checklist at installed command files github/spec-kit#3418 (constitution path)
• Prior sync docs: docs/upstream-improvements-2026-07-20.md, docs/upstream-sync-recommendations.md (2026-07-27)
• Consumer repos will need re-sync after templates land (handled separately by drift-check automation)

Open Questions

• PR granularity: Should the 6 items ship as one bundled PR or separate PRs per priority tier? Recommend two PRs (HIGH items first, then MEDIUM+LOW), but CTO decides before dispatch.

Implementation Notes

Each cherry-pick is a targeted markdown edit. Agents should start from the specific file in the scope fence, read only that file plus any referenced pattern file, and stop. Do not investigate callers, do not refactor surrounding content.

Upstream PRs are references for intent, not for copy-paste. Read the action description in this issue, not the upstream diff — upstream may include Python changes that are excluded here.