feat(swarm): configurable base branch and auto-generate vBRIEFs from GitHub issues (#373)

[MScottAdams]

Summary

Configurable base branch and auto-generate vBRIEFs from GitHub issues for deft-directive-swarm skill.

Closes #373
Parent: #338

Changes

Task A -- Fix broken See also link (pre-existing failure)

• Changed ../deft-review-cycle/SKILL.md to ../deft-directive-review-cycle/SKILL.md on line 16 -- fixes the one failing test in task check

Task B -- Configurable base branch (#373 item 1)

• Phase 0 Step 1: added step to determine base branch (ask user, default master)
• Phase 2 Step 1: worktree creation uses <configured-base-branch> instead of hardcoded master
• Phase 6 Step 1: rebase cascade references configured base branch
• Phase 6 Step 3: git pull origin <configured-base-branch>
• Prompt Template: PR target uses configured base branch
• Crash Recovery: origin/<configured-base-branch> references
• Anti-pattern: prohibits hardcoding master

Task C -- Auto-generate vBRIEFs from GitHub issues (#373 item 2)

• Phase 0 Step 0 (Work-Item Source): asks user whether work items come from existing vBRIEFs or GitHub issue numbers
• If issue numbers: fetches via gh issue view, generates minimal vBRIEF scaffolds in vbrief/active/ conforming to v0.5 schema with github-issue reference provenance
• ! rule: auto-generated vBRIEFs are minimal scaffolds requiring review

Tests

• 5 new tests in section 37 of tests/content/test_skills.py

Checklist

• task check passes (1414 passed, 2 xfailed)
• CHANGELOG.md entry under [Unreleased]
• Conventional commit message
• No files outside scope touched

[greptile-apps]

Greptile Summary

This PR adds configurable base branch support (replacing hardcoded master) and auto-generation of minimal vBRIEF scaffolds from GitHub issue numbers to deft-directive-swarm, plus a broken See also link fix. All three P0/P1 issues flagged in the prior review round (\"id\" lacking the # prefix, plan.narrative vs plan.narratives, and missing plan. prefix on references) are addressed in the follow-up fix commit and confirmed correct against the schema and the domain tooling (reconcile_issues.py, vbrief_validate.py). Remaining findings are P2 style suggestions only.

Confidence Score: 5/5

Safe to merge — all prior P0/P1 schema-field bugs are resolved and task check passes at 1414 tests.

All three previously-flagged blocking issues are fixed. Only two P2 style suggestions remain: a redundant local re import and missing regression assertions for the fixed schema field names. Neither affects runtime correctness.

tests/content/test_skills.py — minor style nit (redundant import) and a coverage gap for the schema-field regression tests.

Important Files Changed

Filename	Overview
skills/deft-directive-swarm/SKILL.md	Adds Phase 0 Step 0 (work-item source selection) and configurable base branch support; three previously-flagged schema-field bugs (id prefix, plan.narratives plural, plan. prefix on references) are correctly fixed in the follow-up commit.
tests/content/test_skills.py	Adds 5 new tests in section 37 covering the See also link fix, configurable base branch, no hardcoded master, auto-generate from issues, and anti-pattern; minor: redundant local import re as _re and no regression assertions for the three previously-fixed schema field names.
CHANGELOG.md	Adds a well-formed [Unreleased] entry describing all three tasks (configurable base branch, vBRIEF auto-generation, See also link fix) and 5 new tests; no issues found.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([Phase 0 Start]) --> S0{Step 0: Work-Item Source?}
    S0 -->|Option A: existing vBRIEFs| S1[Step 1: Read Project State]
    S0 -->|Option B: GitHub issue numbers| GH[gh issue view N --json ...]
    GH --> GEN[Generate minimal vBRIEF scaffold\nvbrief/active/YYYY-MM-DD-slug.vbrief.json\nstatus=running, plan.narratives, plan.references]
    GEN --> S1
    S1 --> BB[Ask user: configured base branch\ndefault: master]
    BB --> S2[Step 2: Surface Blockers]
    S2 --> S3[Step 3: Plan Allocation]
    S3 --> S4[Step 4: Present Analysis]
    S4 --> S5{Step 5: User Approval}
    S5 -->|approved| P1([Phase 1 - Select])
    S5 -->|changes requested| S3
    P1 --> P2_S1[Phase 2 Step 1: git worktree add using configured-base-branch]
    P2_S1 --> P6_S1[Phase 6 Step 1: Rebase cascade onto configured base branch]
    P6_S1 --> P6_S3[Phase 6 Step 3: git pull origin configured-base-branch]

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: tests/content/test_skills.py
Line: 1523-1524

Comment:
**Redundant local `import re` shadows module-level import**

`re` is already imported at the module level (line 15). The `import re as _re` inside the function body is unnecessary and adds confusion about why a different alias is used.

```suggestion
    old_refs = re.findall(r'(?<!directive-)deft-review-cycle/SKILL\.md', text)
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: tests/content/test_skills.py
Line: 1553-1561

Comment:
**No regression tests for the three previously fixed schema field names**

The three issues addressed in the follow-up fix commit (`"id": "#<N>"` prefix, `plan.narratives` plural, and `plan.references` prefix) have no automated coverage in section 37. A future edit to the scaffold spec could silently re-introduce any of these without a failing test. Consider extending `test_deft_directive_swarm_auto_generate_vbriefs_from_issues` with assertions like:

```python
assert 'plan.narratives' in text, ...
assert 'plan.references' in text, ...
assert '"#' in text, ...  # id requires '#' prefix
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (4): Last reviewed commit: "fix: address Greptile review findings (b..." | Re-trigger Greptile}