Skip to content

Release 2.1.2 (2026-06-05)

Bug fixes

  • restore host-container guard after vrg-container-run rename The enforce-host-container-split hook still matched on vrg-docker-run, which no longer exists since the tooling renamed it to vrg-container-run -- both the DENY (host tool wrapped in container) and WARN (bare container tool) guards were silently dead. Rename the pattern in the hook script and HOST_TOOLS list, and drop two HOST_TOOLS entries with no surviving entry point in vergil-tooling (vrg-prepare-release, vrg-merge-when-green). Sweep the same rename through live docs (README hook table and related-repos line, hooks reference, skills-architecture process map) and remove the bootstrap-agent docs' Host Dispatcher check, which the actual agent definition never performed. Historical records (CHANGELOG, releases/, audit commentary in skills-architecture.md) intentionally untouched. Known remaining drift, deferred as a separate bug: vrg-finalize-repo is also gone (successor vrg-finalize-pr changes merge semantics), so the remind-finalize and block-autoclose-linkage hook messages need a semantic rewrite, not a rename.

  • simplify block-agent-merge to unconditional deny Removes the delegation to vrg-check-pr-merge, which was never shipped -- the hook fail-closed on exit 127 with a confusing tool-failed message -- and the release-branch allow-list, since agents have no merge path under 2.1 (credential-enforced), release PRs included. The deny applies to all identities. Spec section 3.2. Ref #441.

  • reword autoclose-linkage rationale for the 2.1 workflow The deny message justified Ref-only linkage via vrg-finalize-repo, which no longer exists. New rationale: issues are closed explicitly by the human after PR finalization, never by merge keywords. Policy unchanged. Spec section 3.2. Ref #441.

  • contents-api deny message: template handoff, human submits The deny message told the agent to submit with vrg-submit-pr; under 2.1 the agent's workflow ends at .vergil/pr-template.yml and the human submits. Also adds the missing hooks-reference section and README row for this hook -- it was entirely undocumented. Spec section 3.2. Ref #441.

  • host tool list: drop vrg-finalize-repo, add 2.1 tools vrg-finalize-repo no longer exists; vrg-finalize-pr replaces it (human tool, but container-wrapping it is still wrong). Adds the 2.1 blocking-wait primitives vrg-await and vrg-pr-await as host-side tools. Spec section 3.2. Ref #441.

Chores

  • migrate vergil pin and workflow refs to v2.1 Bump the vergil.toml dependency pin from v2.0 to v2.1 and update all five consumed vergil-actions workflow refs (ci-quality, ci-security, ci-version-bump, cd-docs, cd-release) from @v2.0 to @v2.1. Part of the fleet-wide 2.0 -> 2.1 migration tracked in issue #428 (playbook: vergil-tooling#1371). No VERSION bump needed: develop (2.1.2) already diverges from main (2.1.1).

  • gitignore agent workspace, build output, local settings Adds .vergil/ (gap flagged by the 2.1 spec section 6), build/ (AUDIT scratch space per the write-guard design, must never sweep into a USER commit), .superpowers/ (fleet-consistent), docs/site/site/ (mkdocs default output), and .claude/settings.local.json (personal Claude Code state). From the 2026-06-05 pushback sweep; the repo_init baseline drift is tracked as vergil-tooling#1425. Ref #441.

Documentation

  • fix stale tool names and missing chore branch type starting-work-on-an-issue.md drift fixes: vrg-docker-run/vrg-docker-cache renamed to vrg-container-run/vrg-container-cache (the old names no longer exist on PATH), add chore to the branch-type guidance and to the existing-remote-branch detection patterns (CLAUDE.md already allows chore/* branches). Found while setting up the worktree for #428.

  • add hooks/2.1 workflow reconciliation design Design spec for the hooks/docs drift repair (#441) and the new AUDIT write-guard hook (#442), produced in the brainstorm session of 2026-06-05. Captures the confirmed ground truth (vrg-finalize-pr is human-only, merges are manual in the GitHub UI today with CLI merge as the target state, issues close explicitly at human finalization), the soft-gate doctrine for all VM-side guards, hook-by-hook target state, doc changes, sequencing, deferred items, and the two companion vergil-tooling issue drafts. Ref #441. Ref #442.

  • fold pushback resolutions into hooks/2.1 reconciliation design Pushback review of 2026-06-05 (paad:pushback), four issues resolved plus one source-control conflict. Sequencing now requires PR 440 (the 428 migration) to merge before 441 implementation starts, with a worktree rebase, since both touch host-container-tools.sh. The gitignore work expands from one entry to five (.vergil/, build/, .superpowers/, docs/site/site/, .claude/settings.local.json) after a three-way sweep against vergil-tooling and the repo_init baseline, which itself has drifted -- captured as critical companion issue A.3. block-agent-merge's unconditional deny is now explicitly identity-independent, backed by a new soft-gate corollary: hooks restrict the agent regardless of identity by default, and Claude under human credentials is a guards-down scenario being eliminated. Hook messages document the about-to-be state (A.1 narrows to CLI merge only; issue closing stays manual, future close-analysis agent noted in deferred). The write-guard's deny conditions are now defined (missing/empty path or normalized path escaping the worktree root). Appendix grows to five companion vergil-tooling issue drafts (gitignore baseline, branch -D heuristic, claude_settings content check). Ref #441. Ref #442.

  • record filed companion issue numbers in appendix A vergil-tooling issues 1423-1427 filed for drafts A.1-A.5. Ref #441.

  • add #441 drift-repair implementation plan Eight bite-sized tasks from the pushback-reviewed reconciliation spec: retire remind-finalize, unconditional block-agent-merge deny, two message fixes, host tool list, five gitignore entries, doc updates, final sweep plus PR-template done-signal. Self-review surfaced three additional doc gaps now covered: README hook table is missing rows for block-agent-merge and block-github-contents-api, the hooks reference has no block-github-contents-api section, and it falsely claims no Write|Edit hooks are active while block-worktree-bypass-write is live. Ref #441.

  • repoint teardown to vrg-finalize-pr; document live hooks; mark lifecycles superseded starting-work-on-an-issue.md teardown note now names the human's vrg-finalize-pr step. skills-architecture.md lifecycle B and C tables get supersession pointers to the 2.1 workflow spec rather than rewrites -- the document is an audit-time record. Also corrects the hooks reference claim that no Write|Edit hooks are active (block-worktree-bypass-write is live) and adds its missing README row. Spec section 4. Ref #441.

  • add #442 audit write-guard implementation plan Five TDD tasks from the pushback-reviewed reconciliation spec sections 2 and 3.3: failing table-driven test script (14 cases), hook implementation, hooks.json registration with NotebookEdit coverage, documentation with the soft-gate framing, final verification plus PR-template done-signal. Plan header names the vergil execution contract per the #443 convention trial. Ref #442.

  • document guard-audit-writes Hooks-reference section (including the soft-gate framing from the reconciliation spec section 2) and README table row. Ref #442.

  • repository-standards: issues close via human finalization Last live reference to the removed vrg-finalize-repo, missed by the #441 sweep because its doc-locating grep used a fixed file list that did not include docs/repository-standards.md. Everything else in #438 was implemented by #441 (PR #444): hook scripts, README, starting-work doc, hooks reference -- with remind-finalize retired outright rather than reworded. Ref #438.

Features

  • add AUDIT identity write-guard PreToolUse guard for Write/Edit/NotebookEdit: when VRG_IDENTITY_MODE=audit, writes are allowed only to .vergil/audit-* and build/ within the worktree; everything else is denied, including the USER agent's .vergil/pr-template.yml. Identity-gate first, managed-repo gated, python3 path normalization shared with block-worktree-bypass-write, fail-closed inside the audit identity and fail-open outside it. Soft gate by design per the spec's soft-gate doctrine. GREEN: all 14 table-driven tests pass. Spec sections 2 and 3.3. Ref #442.

  • register guard-audit-writes for Write/Edit/NotebookEdit Separate matcher entry so NotebookEdit is covered without changing block-worktree-bypass-write's matcher. Ref #442.

Refactoring

  • retire remind-finalize hook Its trigger (vrg-submit-pr in an agent session) no longer occurs under the 2.1 workflow -- the human submits, and vrg-submit-pr emits the next one-liner itself. The hook also instructed agents to run vrg-finalize-repo, which no longer exists. Spec: docs/specs/2026-06-05-hooks-2.1-reconciliation-design.md section 3.2. Ref #441.

Testing

  • add failing table-driven tests for the audit write-guard Fourteen cases across identity (unset/user/audit), allowlist (.vergil/audit-*, build/), the protected pr-template, dot-dot escapes, unmanaged-path gating, the missing-path fail-closed rule, and the NotebookEdit notebook_path field. RED: the hook does not exist yet. Spec section 3.3. Ref #442.