Release 2.1.52 (2026-10-31)

Bug fixes

• state directories and their guards for the review gate (#859)
• fix(agentic-review): keep review state in build/.vergil-state with mode, hash and seal checks

Add the doctrine's state directories (§1.5) under each main clone's build/.vergil-state/, created level by level with mode 700, mode-checked before each write, hashed around each review and sealed between rounds. Mode 2 keeps its round material there, adds pre-dispatch checks on the worktree's paad/ and excludes other tasks' state directories from the stray-write sweep. Mode 1's scratch copy moves there; its failure line must be bare and fails a round on any line that contains it, and the orchestrator creates paad/security/.gitignore before dispatch (#839, #840). The worktree write hook normalises every target path before matching and allows writes under the main clone's build/.vergil-state/.

• fix(agentic-review): tighten state-directory seals, paad/ check order and hook fail-closed scope

Take the end-of-round seal on every path, add a first-round listing check, require a new round subdirectory to be absent and act only on the orchestrator's own files, and hash and seal upstream-report drafts. Run mode 2's real-directory checks before creating paad/security/, and give mode 1 the same paad/ checks. A failed state-directory check in mode 1 stops for the human with no re-run. The sweep leaves each state root out and sweeps the task's own directory on its own. Delete the task's state directory after every summary, only when no round subdirectory remains. The worktree write hook refuses an unnormalisable path when its target or the cwd is in a managed repo. Bring the hook's design spec up to date.

• fix(agentic-review): fail the write hook closed without python3 and narrow state-directory checks

The worktree write hook denies every Write and Edit when python3 is unavailable or a path cannot be normalised. The doctrine runs the paad/ symlink and ls-files checks before anything is created in both modes, checks each state level before install -d, compares permission bits only, creates a round's state subdirectory once per round, and hashes kept details files and upstream drafts after writes and deletions. A run returns its seal hash, and a resumed run checks against it. The sweep excludes only other tasks' state directories in verified main clones, and the doctrine states what the hash checks cover. issue-implement pauses when a round subdirectory remains at deletion; epic-create takes the end-of-round hash; mode 1 state paths use . The hook's design spec and the audit guard's comment match the code.

• fix(agentic-review): keep the state-directory seal within a session and deny relative hook targets

A resumed run, or any new session that finds kept material, starts from the human's confirmation of the state-directory listing, passed with the rulings; no seal hash is carried across sessions. Each details file is hashed when written and checked right before it is read or passed to vrg-security-record, and the doctrine states what the checks cover. The summary is posted only after the check for a remaining round subdirectory. The worktree write hook denies relative target paths, its python3 failure message no longer assumes python3 is missing, and the docs say both exceptions apply in any repo. epic-create takes the seal on every exit and deletes the planning issue's state directory after the docs PR; the round comment and the pause step carry the kept files' hashes; build/ only gets the real-directory checks; the sweep step names how it finds candidate clones.

• fix(agentic-review): isolate the write hook's python3 run and close remaining wording gaps

The worktree write hook runs python3 isolated, keeps its stderr apart from the printed path, and denies anything but a single absolute path, with test rows for a python3 that writes to stderr. The hook docs separate the two python3 cases and the design spec covers the missing-path rule and every deny reason. The doctrine creates a missing build/ with mkdir and defines and validates mode 2's round directory name. The skills take the seal and kept-file hashes after a state-directory stop only once the human confirms the contents, and epic-create's first round and resume use the confirmed listing and the kept files' hashes.

• fix(hooks): deny control characters in write-guard paths

The worktree write guard denies a target path that contains a control character, checked on the raw hook input, with a test row. A kept details file with no recorded hash means stop, in the doctrine and in issue-implement.

• mode 2 findings that need the human pause the round, and every fix is reviewed (#862)
• fix(agentic-review): findings that need the human pause the whole round, and every fix is reviewed

Mode 2 now sorts every finding (security, expansion of work, behaviour change outside the plan, not acted on, unsure), pauses the whole round when any needs the human, acts on the whole round after the ruling, and always reviews what it changed. Rulings use a closed word set with timestamps; the records carry review cost and times; a paused round keeps its material in its state subdirectory, named by Kept lines. One security definition (paad's) lives in the common core, with screening and the security-fix hold-back in mode 2.

• fix(agentic-review): make the mode 2 pause, ruling and resume paths precise

Define a live pause, the branch rulings' ending of the loop, the round cap, how a failed check and other non-finding pauses are ruled and finished, how a paused round's response comment is edited, replay-safe carrying out of rulings, the ruling record's format, and the confirmations a run resumed under epic-implement receives. Align the skills and the paad usage policy with these rules.

• fix(agentic-review): close the gaps in mode 2's failure, replay, counts and confirmation paths

A ruling that cannot be carried out leaves a live pause; the remaining-subdirectory check precedes Finished; accept and drop make no fixes; replays search before filing and skip Recorded items; recording uses one details file per finding; counts and IDs are computed after screening; noticed items are screened; held-back findings end automatically only within the session that holds the approved fix; epic-implement gathers trusted, attributed confirmations for every run it dispatches. The policy and the docs site follow.

• fix(agentic-review): define how mode 2 resumes each kind of pause and guard comment edits

A dismissed failed check, a pause before dispatch and a pause inside step 7 each have a defined resume; --edit-last first confirms the latest comment is the unfinished response; the cap counts a combined grant once; validation repairs that need the human pause; an empty state directory is not leftover; epic-implement passes the listing confirmation for every dispatched run; the round count is described as three before the human decides.

Documentation

• show the design-review rounds in the epic-create skills row (#822) Match the catalogue row in docs/site/docs/skills/index.md so the README summary names the spec pushback, plan pushback and alignment rounds.

• record child F's decisions on the remaining paad skills (#826)

• docs(paad-policy): record the decisions on the remaining paad skills

Add an Other paad skills section with the adopt, by-hand and deviation decisions for rethink, agentic-architecture, fix-architecture, test-roadmap, agentic-owasp, agentic-dedup and backlog. Add the paad:backlog row to the deviations register and renumber the later sections. Ref #823

• docs(paad-policy): name the three outcomes and the skills child F covered

Say that each listed skill is adopted, used by hand or recorded as a deviation, scope the section to the skills in umbrella spec section 4.F, and keep backlog out of the use-by-hand reason. Ref #823

• sync the template's build/ exception line (#855)
• consumers follow the floating v2.1 tag (#863)

• docs(distribution): consumers follow the floating v2.1 tag

• docs(distribution): describe updating, verifying and switching for the v2.1 tag

• docs(distribution): keep the Update section and the switching guide out of the distribution pages

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