feat(vbrief): add pre-cutover detection and backward compatibility guard

[MScottAdams]

Summary

Add pre-cutover detection and backward compatibility guard for the Phase 2 vBRIEF Architecture Cutover. Skills detect old-model artifacts and redirect to migration with actionable messages. Post-migration placeholder integrity is validated by task check.

Closes #334

Changes

Old-model detection (3 skills)

• Added Pre-Cutover Detection Guard section to deft-directive-setup, deft-directive-build, and deft-directive-sync
• Detects: SPECIFICATION.md/PROJECT.md without deprecation sentinel, vbrief/ without lifecycle folders
• Redirects to task migrate:vbrief with actionable messages

Actionable error messages

• Missing lifecycle folders: task migrate:vbrief
• Missing PROJECT-DEFINITION.vbrief.json: task project:render
• Scope vBRIEF in wrong folder: task scope:activate

Post-migration placeholder integrity (vbrief_validate.py)

• Warns when SPECIFICATION.md or PROJECT.md exist but lack deprecation redirect sentinel
• Wired into existing vbrief:validate task (runs as part of task check)

Sync model state reporting

• deft-directive-sync Phase 7 summary now includes Document Model line

Greenfield path verification

• deft-directive-setup documents creating vbrief/ with all 5 lifecycle subdirectories

Tests

• 39 tests in tests/cli/test_precutover_guard.py

Checklist

• /deft:change -- N/A (agent-dispatched task)
• CHANGELOG.md -- added entry under [Unreleased]
• ROADMAP.md -- N/A (tracked via RFC RFC: vBRIEF-centric document model for Deft Directive #309)
• Tests pass locally (39 new, 1 pre-existing failure unrelated to PR)

[greptile-apps]

Greptile Summary

This PR adds a Pre-Cutover Detection Guard to three skills (deft-directive-setup, deft-directive-build, deft-directive-sync) and extends vbrief_validate.py with post-migration placeholder integrity checks (Story S / #334). Skills detect old-model artifacts and redirect to task migrate:vbrief; the validator warns when SPECIFICATION.md/PROJECT.md exist without the <!-- deft:deprecated-redirect --> sentinel. 39 tests cover all acceptance criteria.

Confidence Score: 5/5

Safe to merge — all findings are P2 style/polish items with no functional impact

The feature logic is sound, the three skills are consistent, and the validator behaves correctly. The 39 tests accurately exercise the acceptance criteria. Only minor polish issues remain: a duplicate CHANGELOG entry (pre-existing squash artefact, now visible because the file was touched), a slightly imprecise warning message for empty deprecated files, and a silent OSError inconsistency — none affect runtime behavior or correctness.

CHANGELOG.md — duplicate entry on lines 18-19 should be cleaned up before merge

Important Files Changed

Filename	Overview
CHANGELOG.md	Adds feat entry for #334; contains a duplicate ### Changed entry for #314/#319 with corrupted trailing text on the first copy — violates Pre-Commit File Review rule 2
scripts/vbrief_validate.py	Adds validate_deprecated_placeholders() and wires it into validate_all(); minor issues: misleading "contains non-redirect content" message for empty files, and OSError is silenced inconsistently compared to load_vbrief()
skills/deft-directive-build/SKILL.md	Adds Pre-Cutover Detection Guard section with 3 detection criteria, actionable messages, and ⊗ anti-patterns; well-structured and consistent with the other skills
skills/deft-directive-setup/SKILL.md	Adds Pre-Cutover Detection Guard and Greenfield Projects subsections; guard correctly gates all setup phases and the greenfield path documents all 5 lifecycle subdirectories
skills/deft-directive-sync/SKILL.md	Adds Pre-Cutover Detection Guard with correct skip-phases-1-6 behavior and Document Model line added to Phase 7 summary; three model states (legacy / OK / tampered) are well-defined
tests/cli/test_precutover_guard.py	39 tests covering placeholder integrity (subprocess), skill content assertions, actionable messages, anti-patterns, model state reporting, and greenfield path — comprehensive and accurate count matches CHANGELOG claim

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([Skill invoked:\nsetup / build / sync]) --> B{Pre-Cutover\nDetection Guard}

    B --> C{SPECIFICATION.md or\nPROJECT.md exists\nwithout sentinel?}
    B --> D{vbrief/specification.vbrief.json\nexists but no lifecycle\nfolders?}

    C -->|Yes| E[Display actionable message\n+ task migrate:vbrief]
    D -->|Yes| E

    C -->|No| F{All checks\npass?}
    D -->|No| F

    F -->|setup / build| G[Stop — redirect to\nmigration first]
    F -->|sync| H[Skip Phases 1-6\nProceed to Phase 7]

    E --> G
    E --> H

    H --> I[Phase 7 Summary\nDocument Model:\npre-v0.20 legacy]

    F -->|No pre-cutover| J[Continue normally]
    J --> K[Phase 7 Summary\nDocument Model:\nv0.20+ OK or v0.20+ with warnings]

    subgraph vbrief_validate.py
        V1([task check]) --> V2[validate_all]
        V2 --> V3[validate_deprecated_placeholders]
        V3 --> V4{SPECIFICATION.md or\nPROJECT.md exists\nwithout sentinel?}
        V4 -->|Yes| V5[WARN: non-redirect content\nexit 0]
        V4 -->|No| V6[OK: exit 0]
    end

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: CHANGELOG.md
Line: 18-19

Comment:
**Duplicate CHANGELOG entry with corrupted trailing text**

The `### Changed` section contains two entries for the same PR (#314, #319 deft-setup+interview rename). Line 18 additionally has the PR title appended twice after "assertions" (a squash-merge artefact), producing malformed text. Per AGENTS.md Pre-Commit File Review rule 2, modified files must be re-read and checked for accidental double entries before committing.

Line 18 should be removed entirely (or de-corrupted), keeping only the clean copy at line 19.

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

---

This is a comment left during a code review.
Path: scripts/vbrief_validate.py
Line: 537-543

Comment:
**Misleading warning message for empty deprecated files**

When a deprecated file is empty (zero bytes), `DEPRECATED_REDIRECT_SENTINEL not in content` is `True`, so the validator emits `"SPECIFICATION.md contains non-redirect content"`. An empty file contains no content — redirect or otherwise — making the message technically inaccurate. The test `test_empty_deprecated_file_warns` intentionally exercises this path and asserts the current wording, so both the message and the test assertion would need updating together.

Consider a formulation that's accurate for both cases:

```python
warnings.append(
    f"{filename} is missing the deprecation redirect sentinel -- "
    "this file is deprecated; use scope vBRIEFs "
    "in vbrief/ instead"
)
```

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

---

This is a comment left during a code review.
Path: scripts/vbrief_validate.py
Line: 533-535

Comment:
**Silent OSError differs from the rest of the validator's error handling**

`load_vbrief()` appends an error string to the errors list on `OSError`, making read failures visible. Here, an `OSError` (e.g. permission denied on an existing `SPECIFICATION.md`) is silently `continue`d — the warning is never emitted, producing a false-negative. For consistency, consider either adding the path to warnings or errors:

```python
except OSError as exc:
    warnings.append(f"{filename}: cannot read: {exc}")
    continue
```

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

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