Upstream spec-kit improvements to cherry-pick (v0.13.1–v0.16.4)

[pylot-app]

Upstream spec-kit improvements to cherry-pick (v0.13.1–v0.16.4)

Problem Statement

The fellowship-dev/spec-kit fork is missing four upstream improvements from v0.13.1–v0.16.4 (released 2026-07-21 through 2026-08-14). The most urgent is a correctness bug: taskstoissues lacks the list_issues MCP tool and uses a too-narrow task-ID regex, causing duplicate GitHub issues when re-run and silently skipping tasks with 4+ digit IDs. The remaining three items (constitution Scope Guard, converge command, clarify question quality rules) address scope creep, missing capability, and output quality. All four are safe standalone cherry-picks with no bulk sync required.

User Stories

• As an agent running taskstoissues in a consumer repo, I want existing issues to be detected before creation so that re-runs do not create duplicate issues for already-filed tasks.
• As an agent running speckit.constitution, I want non-governance intents (feature implementation, code generation) to be deferred to Next Actions so that the constitution command does not accidentally execute work outside its scope.
• As an agent running speckit.converge, I want to assess the codebase against spec/plan/tasks and append remaining unbuilt work to tasks.md so that interrupted or partial implementations can be completed.
• As an agent running speckit.clarify, I want question quality rules enforced so that every question is a full interrogative sentence a reader unfamiliar with Spec Kit can answer.

Success Metrics

• taskstoissues re-run on a repo with pre-existing issues creates zero duplicate issues
• speckit.constitution defers non-governance prompts to Next Actions without executing them
• presets/lean/commands/speckit.converge.md exists, is ≤40 lines, and functional
• templates/commands/clarify.md rejects topic-label-only question text

Measurable Impact

• Hypothesis: Implementing these fixes will reduce duplicate issue noise and maintain or improve the pr_merged rate by unblocking stalled implementations that need the converge command.
• Baseline: pr_merged: 98.0% (30d avg, n=447) | time_to_merge_hours: 4.9h (30d avg, n=438)
• Target: pr_merged: maintain ≥98% (already high — target is non-regression). time_to_merge_hours: ≤4.5h (8% reduction).
• 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 >2pp (below 96%) or time_to_merge_hours increases >20% (above 5.9h).

Scope

In Scope

1. taskstoissues.md dual fix (correctness bug — priority 1):
   • Add 'github/github-mcp-server/list_issues' to tools frontmatter in templates/commands/taskstoissues.md
   • Update task-ID dedup regex from \bT\d{3}\b to \bT\d+\b (any-length numeric suffix)
2. Lean speckit.constitution.md Scope Guard (priority 2):
   • Add the Scope Guard block to presets/lean/commands/speckit.constitution.md between ## User Input and ## Outline
3. speckit.converge new command (priority 3):
   • Add templates/commands/converge.md (ported from upstream SHA eadb96ee)
   • Add presets/lean/commands/speckit.converge.md (authored lean, ≤40 lines)
4. clarify.md question quality rules (priority 4):
   • Add two enforcement rules to templates/commands/clarify.md question-writing section

Out of Scope

• Python CLI changes (scripts/python/, py: script types, specify CLI internals)
• Workflow engine changes (fan-out, fan-in, gate steps, WorkflowResolver)
• Integration layer additions (Alquimia, Junie, Mistral Vibe, Factory Droid, Bob 2.0, Copilot skills default)
• Extension/preset catalog submissions
• PowerShell / bundler / archive / auth hardening fixes
• Hook enforcement directive (lean fork intentionally uses terse hook lines)
• Consumer repo sync PRs (handled automatically by weekly tooling mission)
• Creating a presets/lean/commands/speckit.clarify.md lean variant

Technical Requirements

• templates/commands/taskstoissues.md tools frontmatter must list both list_issues and issue_write from github/github-mcp-server
• Task-ID regex in taskstoissues.md must match any-length numeric suffix: \bT\d+\b
• Scope Guard text in lean constitution (verbatim from issue):

  ## Scope Guard
  
  This command's own work is limited to creating or updating the project constitution.
  
  - Classify every part of the user input as constitution content or a non-governance intent (feature
    implementation, code generation, refactoring, deployment). **Do not execute non-governance intents.**
  - Defer each non-governance intent to `Next Actions` with an appropriate follow-up command.
  - If ambiguous, ask before making changes.
  - Omit `Next Actions` when there are none.

• Lean speckit.converge.md: ≤40 lines, terse, no prose preamble, follows the lean format (see presets/lean/commands/speckit.implement.md as pattern reference)
• Clarify rules addition (verbatim from issue):

  - Every question MUST be a full interrogative sentence ending with `?`. Never use a topic label, section heading, or requirement ID alone as the question text.
  - Self-check: a reader unfamiliar with Spec Kit must be able to answer from the question line alone.
  

Implementation Constraints

Anti-patterns

• Do NOT exceed 40 lines in presets/lean/commands/speckit.converge.md — count and trim before committing.
• Do NOT copy the upstream verbose templates/commands/converge.md verbatim as the lean variant; author a terse lean version from the functional description.
• Do NOT touch consumer repos (booster-pack, rails-backend, inbox-angel-worker, mtg-lotr, clapes). Consumer sync is automatic.
• Do NOT clean up, refactor, or modify any other sections of speckit.constitution.md beyond inserting the Scope Guard block.
• Do NOT create a presets/lean/commands/speckit.clarify.md file; only modify the template.
• Do NOT bulk-sync any other upstream changes outside the 4 listed items.
• Do NOT widen the task-ID regex beyond \bT\d+\b — it must still match 3-digit IDs (T001, T123).

Scope fences

Only touch these 5 files:

1. templates/commands/taskstoissues.md
2. presets/lean/commands/speckit.constitution.md
3. templates/commands/converge.md (new file)
4. presets/lean/commands/speckit.converge.md (new file)
5. templates/commands/clarify.md

Patterns to follow

• Lean format: see presets/lean/commands/speckit.implement.md (terse, ≤40 lines, no prose preamble)
• Tools frontmatter format: see templates/commands/taskstoissues.md line 2 (current tools: entry)
• Constitution file structure: see presets/lean/commands/speckit.constitution.md — insert Scope Guard between ## User Input and ## Outline

Testing Strategy

Prerequisites

• None — all changes are Markdown edits; no test infrastructure gaps.

Pre-merge Verification

• templates/commands/taskstoissues.md tools frontmatter contains both 'github/github-mcp-server/list_issues' and 'github/github-mcp-server/issue_write'
• Task-ID dedup regex is \bT\d+\b (or equivalent any-length pattern), not \bT\d{3}\b
• presets/lean/commands/speckit.constitution.md contains the Scope Guard block between ## User Input and ## Outline; no other sections modified
• templates/commands/converge.md exists
• presets/lean/commands/speckit.converge.md exists and is ≤40 lines
• Lean converge follows fork conventions (terse, no prose preamble, matches lean format)
• templates/commands/clarify.md question-writing section includes the two enforcement rules
• No presets/lean/commands/speckit.clarify.md was created
• git diff --stat shows only the 5 expected files (no consumer repo changes, no unrelated edits)
• pytest tests/test_presets.py passes

Post-merge Verification (if any)

• [requires prod access] After the weekly tooling mission (Monday ~1am CLT), verify consumer repos (booster-pack, inbox-angel-worker, mtg-lotr) have received sync PRs installing the updated taskstoissues command and the new speckit.converge lean preset.

Dependencies

• Consumer repos (booster-pack, rails-backend, inbox-angel-worker, mtg-lotr, clapes repos) will need follow-up sync PRs after these template changes. The weekly tooling mission handles this automatically.
• Upstream SHA reference for converge: eadb96ee (for verification/audit purposes).

Open Questions

• None.

Implementation Notes

Implement in priority order (1 → 4): taskstoissues fix first (active correctness bug), then constitution Scope Guard (small patch), then converge command pair, then clarify rules. Items 1–3 are safe to cherry-pick independently; no coordination with consumer repos needed during implementation. After any template change here, consumer sync is automatic via the weekly tooling mission.

The speckit.converge lean preset must be authored from scratch — the upstream verbose template is the functional reference, not the source to copy. The lean format target is the same terse style as speckit.implement.md.