feat(toolkit): verify-branch-state skill + /verify + warn-mode hook (DOJ-4872) — v1.31.0

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "make-no-mistakes",
-  "version": "1.30.0",
+  "version": "1.31.0",
   "description": "The disciplined dev lifecycle — implement issues, review PRs, sync releases, test E2E, manage sessions, and stash secrets via OS-native prompts. One plugin to make no mistakes.",
   "owner": {
     "name": "Luis Andres Pena Castillo",
@@ -10,8 +10,8 @@
   "plugins": [
     {
       "name": "make-no-mistakes",
-      "description": "Dev lifecycle orchestrator. Start with /make-no-mistakes:domain-driven-advisor — the canonical entry point that inspects your repo, asks a few plain-language questions, and routes you across the six-family audit engine (schema-drift, contract-drift, ddd, explicit-architecture, strangler, enforcement-hooks), then runs a premortem on the aggregated remediation plan. Also ships disciplined Linear issue execution with worktree isolation, PR review with Greptile gating, team release sync, E2E test generation/execution, test suite previewer, security pentesting, MoSCoW + RICE prioritization, cross-platform secret stash via OS-native GUI prompts (zenity / kdialog / osascript / Get-Credential), and session management. 29 commands, 10 auto-activating skills, 2 specialized agents.",
-      "version": "1.30.0",
+      "description": "Dev lifecycle orchestrator. Start with /make-no-mistakes:domain-driven-advisor — the canonical entry point that inspects your repo, asks a few plain-language questions, and routes you across the six-family audit engine (schema-drift, contract-drift, ddd, explicit-architecture, strangler, enforcement-hooks), then runs a premortem on the aggregated remediation plan. Pair it with /make-no-mistakes:verify-branch-state (and the /verify slash command) before posting any authoritative claim about a branch's contents — working tree is one projection; the ref is the truth. Also ships disciplined Linear issue execution with worktree isolation, PR review with Greptile gating, team release sync, E2E test generation/execution, test suite previewer, security pentesting, MoSCoW + RICE prioritization, cross-platform secret stash via OS-native GUI prompts (zenity / kdialog / osascript / Get-Credential), and session management. 30 commands, 11 auto-activating skills, 2 specialized agents.",
+      "version": "1.31.0",
       "author": {
         "name": "Luis Andres Pena Castillo",
         "email": "lapc506@users.noreply.github.com"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "make-no-mistakes",
-  "version": "1.30.0",
+  "version": "1.31.0",
   "description": "The disciplined dev lifecycle — implement issues, review PRs, sync releases, test E2E, manage sessions, stash secrets, and enforce manifest-driven tool-call hooks. One plugin to make no mistakes.",
   "author": {
     "name": "Luis Andres Pena Castillo",

CHANGELOG.md

@@ -18,6 +18,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.31.0] - 2026-06-03
+
+### Added
+- **New auto-loading skill `verify-branch-state`** ([`skills/verify-branch-state/SKILL.md`](skills/verify-branch-state/SKILL.md)) — operationalizes the rule "working tree is one projection; the ref is the truth" across every repo the toolkit is installed in. Description tuned to auto-trigger on "verify against develop", "does X exist on `<branch>`", "what's on origin/…", "did this land on main", "re-validate the subagent", "before I claim", "post-merge state". Body covers: the rule statement, the canonical ref-explicit commands (`git fetch origin <ref> --quiet`, `git cat-file -e origin/<ref>:<path>`, `git show origin/<ref>:<path>`, `git ls-tree origin/<ref> -- <path>`, `git grep <pattern> origin/<ref> -- src/`, `git diff origin/<a>..origin/<b>`), the anti-patterns (`ls`, `grep -rn src/`, `find`, `git status`), the pre-flight checklist, the multi-worktree context, and a citation of the 2026-06-03 DOJ-4851/4863/4864 retraction that sourced the rule. Cites memory `feedback_working_tree_is_not_truth`.
+- **New slash command `/verify <ref> <path-or-pattern>`** ([`commands/verify.md`](commands/verify.md)) — runs `git fetch origin <ref> --quiet` then `git ls-tree origin/<ref> -- <path>` for paths or `git grep <pattern> origin/<ref> -- src/` for patterns, and emits a single verdict line citing the ref's short SHA in the shape `origin/<ref> @ <sha7> — <path-or-pattern> <PRESENT|NOT PRESENT|N MATCHES>` so the claim can be re-checked. Handles ref-not-found, shell metacharacters in patterns, and squash-merge cache-staleness (always re-fetches).
+- **New plugin-wide PreToolUse hook `pre-tool-use-claim-verification.sh`** ([`hooks/pre-tool-use-claim-verification.sh`](hooks/pre-tool-use-claim-verification.sh)) — warn-mode only, repo-agnostic, no per-repo manifest required. Detects bare-filesystem verification ops (`ls`, `grep -rn src/`, `find src/`, `cat src/`, `head src/`) and, when combined with intent keywords in the recent context envelope (or `CLAUDE_HOOK_CONTEXT` for smoke tests), prints a stderr warning that includes the local checkout's `HEAD` ref + short SHA, the suggested ref-explicit replacement (specific to the detected op), and pointers to the skill + slash command. Always `exit 0`. Defensive `set +e`. Uses `cd -P` + `pwd -P` for path resolution from day 1 (DOJ-4868 PR #2604 lesson). Trailing-newline-safe `while read`. Honors the documented kill switch `CLAUDE_DISABLE_PLUGIN_HOOKS=1`. Shellcheck clean. Wired into `hooks/hooks.json` under the `Bash` PreToolUse matcher with a 3-second timeout, alongside the existing `pre-bash.sh` dispatcher.
+
+### Changed
+- **README "Start here" section grows a peer entry point.** A new "Also start here: `verify-branch-state` + `/verify`" subsection now sits between the existing `domain-driven-advisor` "Start here" block and "What's Inside", quoting the rule verbatim and linking the skill, the slash command, and the warn-mode hook. The Commands table grows from 29 → 30 (adds `/verify`) and the Skills table grows from 10 → 11 (adds `verify-branch-state`).
+- **Marketplace description references the new peer skill.** `marketplace.json` plugin description now reads "Pair it with /make-no-mistakes:verify-branch-state (and the /verify slash command) before posting any authoritative claim about a branch's contents — working tree is one projection; the ref is the truth." Component counts updated to 30 commands / 11 skills / 2 agents.
+
+### Why
+- Cross-repo enforcement. DOJ-4868 shipped repo-level enforcement of the same rule in `dojo-os` (Level 2 of defense-in-depth). DOJ-4872 is the plugin layer (Level 1): the artifacts travel with the toolkit to any other repo it's installed in. Without it, agents using `make-no-mistakes-toolkit` in any other repo have zero guidance about the rule.
+- Warn-mode, not block-mode — same discipline as DOJ-4868. Erosion of habit if block-mode. The skill + slash command provide the right replacement commands; the hook nudges toward them.
+- Origin incident: 2026-06-03 DOJ-4851/4863/4864. A re-audit subagent correctly flagged `usePathwayViewModel.ts` as deleted on `develop`. The orchestrator "corrected" it by running `ls src/hooks/path/usePathwayViewModel.ts` against a local main checkout that had been switched to a different branch in another session; posted authoritative "FRESH — proceed as briefed" comments to Linear; had to retract publicly. Memory `feedback_working_tree_is_not_truth` documents the failure mode + the rule.
+
 ## [1.30.0] - 2026-06-02
 
 ### Changed
@@ -645,7 +661,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Product Owner Extension (SPOPC) roadmap section in README
   ([PR #4](https://github.com/DojoCodingLabs/make-no-mistakes-toolkit/pull/4)).
 
-[Unreleased]: https://github.com/DojoCodingLabs/make-no-mistakes-toolkit/compare/v1.30.0...HEAD
+[Unreleased]: https://github.com/DojoCodingLabs/make-no-mistakes-toolkit/compare/v1.31.0...HEAD
+[1.31.0]: https://github.com/DojoCodingLabs/make-no-mistakes-toolkit/releases/tag/v1.31.0
 [1.30.0]: https://github.com/DojoCodingLabs/make-no-mistakes-toolkit/releases/tag/v1.30.0
 [1.29.0]: https://github.com/DojoCodingLabs/make-no-mistakes-toolkit/releases/tag/v1.29.0
 [1.28.0]: https://github.com/DojoCodingLabs/make-no-mistakes-toolkit/releases/tag/v1.28.0

README.md

@@ -1,6 +1,6 @@
 # make-no-mistakes
 
-**Version: 1.30.0** · [CHANGELOG](./CHANGELOG.md) · [Marketplace](https://github.com/DojoCodingLabs/make-no-mistakes-toolkit)
+**Version: 1.31.0** · [CHANGELOG](./CHANGELOG.md) · [Marketplace](https://github.com/DojoCodingLabs/make-no-mistakes-toolkit)
 
 The disciplined dev lifecycle — implement issues, review PRs, sync releases, test E2E, and manage sessions. One plugin to make no mistakes.
 
@@ -71,9 +71,27 @@ It routes you across the **six audit families** (all live as of 1.29.0):
 
 After the audit(s), it runs a **premortem** on the aggregated remediation plan, so the plan you ship has already survived "it's 6 months later and this failed — why?". Full teaching section [below](#guided-repo-health-domain-driven-advisor).
 
+## Also start here: `verify-branch-state` + `/verify`
+
+**Peer entry point** — load this alongside `/make-no-mistakes:domain-driven-advisor` before posting any authoritative claim about a branch's contents.
+
+> Working tree is ONE projection. The ref is the truth. Verify against the ref.
+
+The `verify-branch-state` skill auto-loads on "verify against develop", "does X exist on `<branch>`", "what's on origin/…", "did this land on main", "re-validate the subagent". Pair it with the `/verify` slash command:
+
+```
+/make-no-mistakes:verify <ref> <path-or-pattern>
+```
+
+The command runs `git fetch origin <ref> --quiet` then `git ls-tree origin/<ref> -- <path>` (for paths) or `git grep <pattern> origin/<ref> -- src/` (for patterns), and prints a single verdict line citing the ref's SHA — so the claim can be re-checked later.
+
+Why this matters: in multi-session, multi-worktree, hook-mediated repos (dojo-os has 12+ active worktrees), the local checkout's HEAD can silently drift between commands. A bare `ls` / `grep -rn src/` / `find` reads **that** projection, not the ref. This skill and slash command — plus a warn-mode PreToolUse hook (`hooks/pre-tool-use-claim-verification.sh`) that nudges you to ref-explicit commands — operationalize the rule across every repo the toolkit is installed in. Origin: 2026-06-03 DOJ-4851/4863/4864 authoritative-but-wrong corrections, retracted publicly; memory `feedback_working_tree_is_not_truth`. Repo-level enforcement sibling: DOJ-4868 in `dojo-os`.
+
+See `skills/verify-branch-state/SKILL.md` for the full anti-pattern catalogue and pre-flight checklist.
+
 ## What's Inside
 
-### Commands (29)
+### Commands (30)
 
 Deliberate actions you invoke explicitly.
 
@@ -108,8 +126,9 @@ Deliberate actions you invoke explicitly.
 | [`/make-no-mistakes:atomic-rules-init`](commands/atomic-rules-init.md) | Scaffold a `.atomic-design-rules.json` at the repo root so the atomic-design hooks (PreToolUse ownership enforcement + PostToolUse drift telemetry) start enforcing. No-op if the file already exists |
 | [`/make-no-mistakes:e2e-test-preview [path]`](commands/e2e-test-preview.md) | Launch a Qt-based visual previewer for `test-suite.json` — interactive table with filtering, detail pane, and CSV export (auto-installs PySide6) |
 | [`/make-no-mistakes:gemini-code-review [target]`](commands/gemini-code-review.md) | Cheap first-pass code review (one-shot via liteLLM) on a parametrizable model — Gemini 3.5 Flash by default; supports `--model` and `--adversarial`, curated against the repo's CLAUDE.md |
+| [`/make-no-mistakes:verify <ref> <path-or-pattern>`](commands/verify.md) | Verify whether a file, directory, or pattern exists on a named git ref. Runs `git fetch origin <ref> --quiet` then `git ls-tree` / `git grep` against `origin/<ref>` and emits a verdict line citing the ref's SHA. Use before posting any authoritative claim about a branch's contents (working tree is one projection; the ref is the truth) |
 
-### Skills (10)
+### Skills (11)
 
 Auto-activate by context — you don't need to remember the command name.
 
@@ -125,6 +144,7 @@ Auto-activate by context — you don't need to remember the command name.
 | [`domain-driven-advisor`](skills/domain-driven-advisor/SKILL.md) | Ask "which audit do I need?" / "where do I start with repo health?" — routes you to the right audit(s) and runs a premortem |
 | [`premortem`](skills/premortem/SKILL.md) | Say "premortem this", "what could kill this", "stress test this plan", "what am I missing", or "find the blind spots" on a plan/launch/decision |
 | [`prioritize`](skills/prioritize/SKILL.md) | Ask to "prioritize issues", "rank the backlog", "apply MoSCoW", or "RICE scoring" for a product pillar (suggests `/make-no-mistakes:prioritize`) |
+| [`verify-branch-state`](skills/verify-branch-state/SKILL.md) | Say "verify against develop", "does X exist on `<branch>`", "what's on origin/…", "did this land on main", or are about to post an authoritative claim about a branch's contents — auto-loads ref-explicit verification rules and routes you to `/make-no-mistakes:verify` (working tree is one projection; the ref is the truth) |
 
 Skills can also be invoked explicitly: `/make-no-mistakes:spec-recommend T0-4`