feat(vbrief): update vbrief.md with vBRIEF-centric document model (#310)

[MScottAdams]

Summary

Updates vbrief/vbrief.md with the new vBRIEF-centric document model defined in RFC #309.

Part of #309. Closes #310. Tracking: #338.

Changes

• File Taxonomy rewrite: Replaced 5-type flat table with comprehensive document model
• Lifecycle folders: proposed/, pending/, active/, completed/, cancelled/ with status mapping
• PROJECT-DEFINITION.vbrief.json: New document type using existing v0.5 schema
• Filename convention: YYYY-MM-DD-descriptive-slug.vbrief.json
• Status-driven moves: plan.status is source of truth
• Origin provenance: Every scope vBRIEF MUST carry references to origin
• Epic-story linking: Bidirectional with examples
• Coexistence: Scope vBRIEFs + plan.vbrief.json + continue.vbrief.json via planRef
• Scope splitting: Agent-driven lifecycle convention
• Anti-patterns: 4 new entries

Checklist

• task check passes
• CHANGELOG.md updated
• Conventional commit
• Feature branch
• Documentation-only (no tests needed)

[greptile-apps]

Greptile Summary

This documentation-only PR rewrites vbrief/vbrief.md to introduce the vBRIEF-centric document model from RFC #309: lifecycle folders (proposed/, pending/, active/, completed/, cancelled/), scope vBRIEFs with status-driven moves, PROJECT-DEFINITION.vbrief.json, origin provenance requirements, bidirectional epic-story linking, and scope splitting conventions. The overall structure is well-reasoned, but two inconsistencies in the new examples need fixing before agents adopt this model as-is.

• The Epic → Stories and Story → Epic JSON examples both omit the items field, which the File Format section marks as MUST — agents using these as templates will produce schema-invalid files.
• planRef is shown as a single string throughout, yet multiple rules reference "scope vBRIEF(s)" (plural) and Scope Splitting step 5 requires pointing to multiple child vBRIEFs — the allowed type (string vs string[]) is never declared.

Confidence Score: 4/5

Safe to merge after fixing the two P1 documentation gaps; the structural model itself is sound.

Two P1 findings: (1) scope vBRIEF JSON examples omit the required items field — agents using these templates will generate schema-invalid files; (2) planRef type is undefined for multi-scope scenarios, causing agent divergence during scope splitting. Both are documentation corrections confined to vbrief/vbrief.md. No code or runtime behaviour is affected, but since this document is the canonical reference agents use to generate files, the inconsistencies will directly produce broken artifacts until corrected.

vbrief/vbrief.md — specifically the Epic-Story Linking examples (lines 94–118) and the planRef multi-scope rules (lines 128, 139, 359, 418).

Important Files Changed

Filename	Overview
vbrief/vbrief.md	Major documentation rewrite introducing lifecycle folders, scope vBRIEFs, and new rules; two P1 issues: scope vBRIEF JSON examples omit the required items field, and planRef type is undefined for the multi-scope case.
CHANGELOG.md	Changelog entry correctly placed under [Unreleased] with appropriate detail; no issues.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([Idea]) --> PROP["proposed/\nstatus: draft | proposed"]
    PROP -->|"approved / pending"| PEND["pending/\nstatus: approved | pending"]
    PEND -->|"running"| ACT["active/\nstatus: running | blocked"]
    ACT -->|"blocked (stays in active/)"| ACT
    ACT -->|"completed"| COMP["completed/\nstatus: completed ✔"]
    ACT -->|"cancelled"| CANC["cancelled/\nstatus: cancelled"]
    PROP -->|"cancelled"| CANC
    PEND -->|"cancelled"| CANC
    CANC -.->|"restorable"| PROP

    subgraph "vbrief/ root (singular files)"
        PD["PROJECT-DEFINITION.vbrief.json\nscope registry + identity"]
        PL["plan.vbrief.json\nsession tactical plan (planRef →)"]
        CONT["continue.vbrief.json\ninterruption checkpoint (planRef →)"]
    end

    ACT -- "planRef ←" --> PL
    ACT -- "planRef ←" --> CONT
    ACT -- "items[].references ←" --> PD

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: vbrief/vbrief.md
Line: 94-118

Comment:
**Scope vBRIEF examples missing required `items` field**

The File Format section marks `items` as MUST for every vBRIEF (`! title (non-empty string), status, items (array of PlanItems)`), but neither the Epic nor Story examples include it. An agent treating these as canonical templates will produce schema-invalid files that tools like vBRIEF-Studio will reject.

At minimum both examples need `"items": []` (or populated items for an epic), e.g.:

```json
{
  "vBRIEFInfo": { "version": "0.5" },
  "plan": {
    "title": "Auth system overhaul",
    "status": "running",
    "items": [],
    "references": [
      { "type": "x-vbrief/plan", "url": "./active/2026-04-12-oauth-flow.vbrief.json" },
      { "type": "x-vbrief/plan", "url": "./active/2026-04-12-session-mgmt.vbrief.json" }
    ]
  }
}
```

Same fix applies to the Story → Epic example below (line 108–118).

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

---

This is a comment left during a code review.
Path: vbrief/vbrief.md
Line: 128

Comment:
**`planRef` type undefined for multiple scope vBRIEFs**

Lines 128, 139, 359, and 418 all use the plural "scope vBRIEF(s)" implying `planRef` can reference more than one file. The Scope Splitting step 5 explicitly says `plan.vbrief.json` should reference **child scope vBRIEFs** (plural) via `planRef`. However, the only concrete example of `planRef` in the document (Story → Epic, line 115) shows it as a single string:

```json
"planRef": "./active/2026-04-10-auth-system-overhaul.vbrief.json"
```

Without a canonical declaration of whether `planRef` is `string | string[]`, agents working on a split scope will diverge — some will produce a string, others an array — causing parse failures when tools that expect a string receive an array, or silently drop all but the first reference when the reverse occurs.

Consider either:
- Declaring `planRef` as `string | string[]` with an example showing the array form, or
- Restricting it to a single string and directing multi-scope plans to list each scope as a separate item in `plan.vbrief.json`'s `references` array 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: vbrief/vbrief.md
Line: 330-342

Comment:
**`references` placement inconsistency: item-level vs plan-level**

The File Format section lists `references` only as an optional field on the `plan` object (`? id, narratives, edges, tags, metadata, references, etc.`), and the Epic → Stories example places `references` at `plan` level. But this `PROJECT-DEFINITION` example places `references` inside individual `items[]` entries.

The document never states whether item-level `references` is valid in the vBRIEF v0.5 schema. If `PlanItem` does not support `references`, the example would produce schema-validation errors when scanned by vBRIEF-Studio or similar tooling.

Consider adding a note confirming that `references` is a supported `PlanItem` field in v0.5, or restructure the example to put the scope registry link at the plan level (consistent with the Epic → Stories pattern).

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

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