feat(change,skills): convert deft:change to vBRIEF outputs, replace PRD gate, fix deterministic question UX (#371, #372, #345, #359)

[MScottAdams]

Summary

Convert deft:change artifacts to vBRIEF format, replace PRD.md approval gate with vBRIEF draft approval, and fix deterministic question UX in the interview skill.

Changes

Task A -- proposal.vbrief.json (#371)

• asks/change.yml change:init: creates proposal.vbrief.json instead of proposal.md + design.md
• commands.md: artifacts section and field descriptions updated
• deft-directive-build SKILL.md: Change Lifecycle Gate references proposal.vbrief.json
• deft-directive-review-cycle SKILL.md: Phase 1 audit references proposal.vbrief.json

Task B -- delta vBRIEF specs (#372)

• commands.md specs/ section: documents {capability}.delta.vbrief.json format
• Archive Spec Delta Merge: reads delta vBRIEF narratives directly
• context/spec-deltas.md: fully rewritten for vBRIEF format

Task C -- vBRIEF draft approval (#345)

• deft-directive-interview SKILL.md: Output Targets clarified (specification.vbrief.json sole output)
• deft-directive-setup SKILL.md: Phase 3 human approval gate strengthened

Task D -- deterministic question UX (#359)

• Rule 8: Deterministic Selection Confirmation (echo + wait for Enter)
• Rule 9: Backward Navigation (back/prev/b)
• Rule 10: Freeform Conversation Escape (option 0)

Tests

• 14 new tests in ests/content/test_change_and_skills.py
• Updated existing est_correct_directory_structure for new output format

Checklist

• ask check passes (1427 tests, 0 failures)
• CHANGELOG.md updated under [Unreleased]
• Conventional commit message
• Feature branch (not direct to default)

Closes #371
Closes #372
Closes #345
Closes #359
Parent: #338

[greptile-apps]

Greptile Summary

This PR completes the vBRIEF format migration for deft:change artifacts, converting proposal.md + design.md to proposal.vbrief.json, documenting delta.vbrief.json spec formats, replacing the PRD gate with vBRIEF draft approval, and adding Rules 8–10 to the interview skill (deterministic confirmation, backward navigation, and option-0 escape). The tasks/change.yml update and documentation changes are clean; tests cover the new behaviour well with two minor gaps noted below.

Confidence Score: 5/5

Safe to merge — all remaining findings are P2 style/coverage suggestions that do not affect runtime correctness.

No P0 or P1 issues found. The tasks/change.yml logic change is clean and well-tested; skill documentation changes are consistent and internally correct. Two P2 gaps (misplaced rule headings and a missing test for the review-cycle skill) and one overly-broad test assertion are quality improvements rather than blockers.

skills/deft-directive-interview/SKILL.md (Rules 8–10 section placement), tests/content/test_change_and_skills.py (missing review-cycle test and broad Phase 3 assertion)

Important Files Changed

Filename	Overview
tasks/change.yml	Replaces proposal.md + design.md creation with a single proposal.vbrief.json; tasks.vbrief.json creation is unchanged. Logic is clean and the variable rename (vbrief → tasks) is correct.
tests/content/test_change_and_skills.py	13 new acceptance-criteria tests; covers commands.md, build skill, interview skill, and setup skill. Missing corresponding test for review-cycle SKILL.md proposal.vbrief.json reference (also changed in this PR). One assertion is overly broad and doesn't anchor to Phase 3.
tests/cli/test_task_scripts.py	test_correct_directory_structure updated to assert proposal.vbrief.json and tasks.vbrief.json; also validates vBRIEF structure fields. Correct and sufficient.
skills/deft-directive-interview/SKILL.md	Output Targets section clarified; Rules 8–10 added. Rules 1–7 live under ## Interview Loop; Rules 8–10 land under ## Invocation Contract after the embedded/delegation subsections — inconsistent placement that could cause readers to miss them.
skills/deft-directive-setup/SKILL.md	Phase 3 human-approval gate strengthened; ⊗ anti-pattern against authoritative PRD.md added in two places. Clean and well-structured.
skills/deft-directive-review-cycle/SKILL.md	Phase 1 audit item 6 updated to reference proposal.vbrief.json. Change is correct and consistent with the rest of the PR.
skills/deft-directive-build/SKILL.md	Change Lifecycle Gate updated to reference proposal.vbrief.json. Correct and consistent.
context/spec-deltas.md	Fully rewritten for delta.vbrief.json format with clear rules, vBRIEF chain examples, and ⊗ anti-pattern against markdown spec files.
commands.md	Artifacts section updated for proposal.vbrief.json; specs/ section now documents delta.vbrief.json format; archive Spec Delta Merge reads vBRIEF narratives directly. All changes are clean.
CHANGELOG.md	New [Unreleased] entry accurately summarises all four tasks (A–D). Satisfies the CHANGELOG gate requirement.

Sequence Diagram

sequenceDiagram
    participant U as User
    participant A as Agent
    participant FS as Filesystem

    Note over U,FS: task change:init
    A->>FS: "write proposal.vbrief.json (narratives)"
    A->>FS: "write tasks.vbrief.json (items, edges)"

    Note over U,A: Rule 8 - Deterministic Selection Confirmation
    A->>U: "Which option? 1/2/3"
    U->>A: "1"
    A->>U: "You selected: Cross-platform. Confirm?"
    U->>A: "Enter"
    A->>A: "advance to next question"

    Note over U,A: Rule 9 - Backward Navigation
    U->>A: "back"
    A->>U: "re-display previous question"
    U->>A: "confirm or change answer"

    Note over U,A: Rule 10 - Option 0 Freeform Escape
    U->>A: "0"
    A->>U: "enter freeform mode"
    A->>U: "re-display same question to resume"

    Note over U,FS: Phase 3 vBRIEF Approval Gate
    A->>FS: "write specification.vbrief.json draft"
    A->>U: "present vBRIEF narratives for review"
    U->>A: "approved"
    A->>FS: "update status: approved, create scope vBRIEFs"

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: skills/deft-directive-interview/SKILL.md
Line: 180-237

Comment:
**Rules 8–10 placed outside `## Interview Loop`**

Rules 1–7 live under `## Interview Loop`; Rules 8–10 land under `## Invocation Contract` (after the embedded/delegation mode subsections). An agent reading the skill top-to-bottom could scan the Interview Loop section, see "Rule 7: Structured Handoff Contract" as the last rule, and not realise three more interaction rules follow later in a different section. The Anti-Patterns section at the bottom does repeat the key prohibitions, but the canonical rule definitions are split across two sections.

Consider moving Rules 8–10 into `## Interview Loop` alongside Rules 1–7 so the full set of interview interaction rules is co-located.

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_change_and_skills.py
Line: 119-125

Comment:
**Missing test for `deft-directive-review-cycle` SKILL.md change**

Task A of this PR updates `deft-directive-review-cycle` SKILL.md Phase 1 audit item 6 to reference `proposal.vbrief.json` (confirmed present at line 49 of that file). The test suite covers the analogous change in `deft-directive-build`, but there is no corresponding test for the review-cycle skill, leaving that regression unguarded.

```python
def test_review_cycle_skill_references_proposal_vbrief_json() -> None:
    """deft-directive-review-cycle SKILL.md Phase 1 audit must reference proposal.vbrief.json."""
    text = _read("skills/deft-directive-review-cycle/SKILL.md")
    assert "proposal.vbrief.json" in text, (
        "skills/deft-directive-review-cycle/SKILL.md: Phase 1 audit must "
        "reference proposal.vbrief.json"
    )
```

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_change_and_skills.py
Line: 193-205

Comment:
**Broad assertion doesn't anchor to Phase 3**

`"approval" in text.lower() and "vbrief" in text.lower()` passes as long as either word appears anywhere in the entire setup skill file — both words appear many times outside Phase 3. A future edit that removes the approval gate from Phase 3 specifically would not be caught.

Consider checking for a phrase unique to the Phase 3 section, for example:

```python
phase3_start = text.find("## Phase 3")
phase3_end   = text.find("## Phase 4", phase3_start)
if phase3_end == -1:
    phase3_end = len(text)
phase3_text = text[phase3_start:phase3_end]
assert "specification.vbrief.json" in phase3_text
assert "approval" in phase3_text.lower() and "vbrief" in phase3_text.lower()
```

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

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

[MScottAdams]

Rebase-only force-push — no logic changes, rebased onto updated phase2/vbrief-cutover after PR #376 merge.