Skip to content

Release 2.1.284 (2026-11-03)

Documentation

  • build/ exception, mode 2 security records and the review delegate (#3901)
  • docs(worktrees): state the build/ exception where the main worktree is called read-only

Features

  • epic_docs library and vrg-epic-docs set (#3899)
  • feat(epic-docs): epic Documents section library and vrg-epic-docs set

Adds lib/epic_docs.py, which owns the epic Documents section format (render, parse, legacy-line removal, upsert, body read/write), and the vrg-epic-docs set subcommand, which writes one epic's section under the epic owner's App token. Registers the command and gives it a CLI tools overview entry, which the overview gate requires. Ref #3896

  • fix(epic-docs): tighten fence, legacy-line and link parsing in epic_docs

Fences close only on a run of the same character at least as long as the opener, with no info string, so nested examples stay fenced. A standalone Spec:/Plan:/Retrospective: line is removed only when its value is a path, a link or a note, so prose that starts with the label is kept. A legacy Documents: list with blank lines between its bullets is removed whole. parse() takes an optional home repo, which makes a link's path and branch split exact; without it an ambiguous link is refused instead of guessed. read_body() refuses an API answer with no body field.

  • fix(epic-docs): validate vrg-epic-docs set paths and look up branches before the read

A : value must name a valid repo, and an /: value is refused, both before any API call. The default-branch lookups now run before the body is read, keeping the read and the write together. set parses the section with the epic's home repo. The existence test also patches subprocess.run, so a probe through any gh wrapper is caught.

  • fix(epic-docs): match whole legacy lines, ignore indented markers and compare repos without case

A standalone Spec/Plan/Retrospective line is removed only when its whole value is one backticked path, link or note, so prose such as a backticked command name is kept. Lines split only on newlines, so a form feed or U+2028 never starts a line. A marker indented four spaces or a tab is an indented code example, not the section. Repo names compare without case, so a section written under a differently cased home repo parses back. Tests now exercise the info-string fence closer and tilde-fence protection.

  • fix(epic-docs): refuse non-epic issues and report API failures in vrg-epic-docs set

set checks that --epic carries the epic label (epics.is_epic) before any other call, so a mistyped number cannot rewrite a task or pull request body. A GitHub API error or malformed API answer before the write is reported with the epic and 'nothing was edited', exit 1; a failed write is reported as such. The reference entry documents the epic check, that only an owner-qualified value naming the epic's owner is refused, and the path and repo-name rules.

  • vrg-epic-docs backfill (#3902)
  • feat(epic-docs): vrg-epic-docs backfill

Add backfill (--org ORG | --repo OWNER/REPO) [--apply]: list every epic through the paginated issues API, skip container and [archived] epics, discover each epic's spec, plan and retrospective, keep existing links, decide the remaining entries by the entry rules and cutoffs, name ambiguous epics without guessing, and remove legacy document lines. A dry run unless --apply; exits 1 when any epic needs a decision or failed.

  • check every epic's Documents section, and document it (#3911)
  • feat(epic-audit): check every epic's Documents section

Adds an Epic documents section to vrg-epic-audit: every non-standing epic needs a well-formed Documents section, and on a closed epic no entry may be pending and every link must resolve on its repo's default branch. The closed-epic-with-open-child check now reads the same epic listing, so the audit lists the home's epics once. Documents the section, its entry rules, vrg-epic-docs set and backfill, and the new invariant on the site.

  • fix(epic-audit): require a closed epic's links to name files, and list epics under the home's token

A closed epic's Documents link now passes only when the contents API answers with a file; a directory, symlink or submodule is reported. The audit lists the home's epics under the home owner's App token, names a malformed section once, and documents that the check runs only without --close.

  • docs(epic-docs): correct the vrg-epic-docs and Epic documents audit reference

State backfill's exit codes accurately (a dry run with changes pending exits 0; bad arguments exit 2), when two candidate directories are ambiguous, and when the body is re-read under --apply. Note that the audit check reports directory links and runs only without --close.

CI Evidence: All gates passed — full audit bundle available. Download →