@cad0p/pi-steering 0.1.0

package/examples/force-push-strict/steering.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering / examples.
+
+/**
+ * Example: force-push-strict rule pack.
+ *
+ * Equivalent to `steering.json` in this directory but expressed in the
+ * canonical TypeScript form. Drop this file in at
+ * `.pi/steering.ts` (or `.pi/steering/index.ts`) to activate.
+ *
+ * What it enforces: no force pushes of ANY kind, including
+ * `--force-with-lease` (which the shipped `DEFAULT_RULES.no-force-push`
+ * deliberately allows). Useful on teams where shared-branch history
+ * must stay append-only even for "safe" rewrites.
+ *
+ * Shape:
+ *
+ *   - `disabledRules: ["no-force-push"]` drops the default rule so
+ *     it doesn't fire alongside our stricter one (otherwise the
+ *     default's block message would win on `git push --force`).
+ *   - `no-force-push-strict` fires on `--force` (any suffix, any
+ *     position) AND on `-f`. Matches the same pre-subcommand flag
+ *     patterns as the default (`git -C /path push --force`,
+ *     `git -c key=val push --force`, `git --git-dir=/x push -f`).
+ *
+ * Scope note: the git plugin's `no-main-commit` fires on top of this
+ * rule when the plugin is declared (`plugins: [gitPlugin]`, opt-in).
+ * If that's not wanted, omit the plugin or add
+ * `disabledRules: ["no-force-push", "no-main-commit"]`.
+ */
+
+import { defineConfig } from "@cad0p/pi-steering";
+import gitPlugin from "@cad0p/pi-steering/plugins/git";
+
+export default defineConfig({
+  plugins: [gitPlugin],
+  // Disable the shipped default so its less-strict block-reason (
+  // "use --force-with-lease if you must") doesn't leak to the LLM
+  // alongside our stricter variant.
+  disabledRules: ["no-force-push"],
+  rules: [
+    {
+      name: "no-force-push-strict",
+      tool: "bash",
+      field: "command",
+      // Mirrors DEFAULT_RULES.no-force-push's pre-subcommand flag
+      // slot but WITHOUT the `--force-with-lease` allowance.
+      pattern:
+        "^git\\b(?:\\s+-{1,2}[A-Za-z]\\S*(?:\\s+\\S+)?)*\\s+push\\b.*(?:--force\\b|\\s-f(?:\\s|$))",
+      reason:
+        "No force pushes of any kind, including --force-with-lease. Create a new commit, or reset + re-commit via a non-force path.",
+    },
+  ],
+});

package/examples/force-push-strict/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["steering.ts", "steering.test.ts"]
+}

package/examples/no-amend/README.md

@@ -0,0 +1,52 @@
+# no-amend
+
+A rule pack that blocks `git commit --amend`.
+
+> **TypeScript form (canonical):** see [`steering.ts`](./steering.ts) — drop in at `~/.pi/steering.ts` or `<project-root>/.pi/steering.ts`. The loader accepts TypeScript only. The [`steering.json`](./steering.json) form is provided for reference + `pi-steering import-json` migration; the loader does NOT pick up JSON files. See [examples/README.md#json](../README.md#json) for migration steps.
+
+## What it enforces
+
+- `git commit --amend` → blocked
+- `git commit -m "msg"` → allowed
+- `git -C /path commit --amend` → blocked (handles the git pre-subcommand `-C` flag)
+
+The AST backend also sees through wrappers — `sh -c 'git commit --amend'` and `sudo git commit --amend` are blocked.
+
+## Rationale
+
+`--amend` rewrites the last commit's SHA. For code-review workflows that track diffs across pushes, that's a regression:
+
+- Reviewers compare revisions by SHA. An amended commit presents as a brand-new revision with no relation to the previous one, and per-line comments lose their anchor.
+- History lineage matters for bisect and blame. Amending mid-review tangles both.
+- If you genuinely need to fix the last commit's message or contents, a **follow-up commit** (`git commit -m "fix …"`) preserves continuity. Squash-merge at the end of review collapses the chain.
+
+## Variant: cwd-scoped (`steering.cwd-scoped.json`)
+
+If you want to apply the rule only to specific directory trees (e.g. a monorepo where some sub-projects enforce linear history and others don't), use `when.cwd`:
+
+```json
+{
+  "rules": [
+    {
+      "name": "no-amend-in-personal",
+      "tool": "bash",
+      "field": "command",
+      "pattern": "^git\\b(?:\\s+-{1,2}[A-Za-z]\\S*(?:\\s+\\S+)?)*\\s+commit\\b.*--amend\\b",
+      "when": { "cwd": "^/home/[^/]+/projects/personal/" },
+      "reason": "In personal/shared repos, don't rewrite history. Create a new commit instead."
+    }
+  ]
+}
+```
+
+`when.cwd` is the feature that distinguishes this engine from a regex-on-raw approach: it's tested against the **effective** cwd of each extracted command, so even `cd /home/me/projects/personal/site && git commit --amend` — run from a different session cwd — is still caught. The walker handles `&&`, `;`, subshells, and wrapper arguments.
+
+## When to use
+
+- Teams with post-push review (Gerrit, Phabricator, CRUX-style CR tools) where commit-SHA stability matters
+- Projects that rely on bisect / blame history continuity
+- Any workflow where the agent reaching for `--amend` as a "clean up the last commit" reflex hides work from review
+
+## Install
+
+Copy [`steering.ts`](./steering.ts) to `~/.pi/steering.ts` (global) or to `<project-root>/.pi/steering.ts` (scoped via walk-up loader). For the cwd-scoped variant, adapt the `when.cwd` regex inline. The loader accepts TypeScript only; the `steering.cwd-scoped.json` reference can be migrated via `pi-steering import-json` — see [examples/README.md#json](../README.md#json).

package/examples/no-amend/node_modules/.bin/pi-steering

@@ -0,0 +1,43 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+basedir_win="$basedir"
+exe=""
+msys=""
+
+case `uname -a` in
+  *CYGWIN*|*MINGW*|*MSYS*)
+    if command -v cygpath > /dev/null 2>&1; then
+      basedir_win=`cygpath -w "$basedir"`
+    fi
+    exe=".exe"
+    msys="true"
+  ;;
+  *WSL2*)
+    if command -v wslpath > /dev/null 2>&1; then
+      basedir_win="$(wslpath -w "$basedir" 2> /dev/null)"
+      if [ $? -ne 0 ] || [ -z "$basedir_win" ]; then
+        basedir_win="$basedir"
+      else
+        exe=".exe"
+      fi
+    fi
+  ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/pier/open-source/github/pi-steering/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/pier/open-source/github/pi-steering/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -n "$exe" ] && [ -x "$basedir/node.exe" ]; then
+  exec "$basedir/node.exe"  "$basedir_win/../@cad0p/pi-steering/dist/bin/pi-steering.js" "$@"
+elif [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../@cad0p/pi-steering/dist/bin/pi-steering.js" "$@"
+elif command -v node >/dev/null 2>&1; then
+  exec node  "$basedir/../@cad0p/pi-steering/dist/bin/pi-steering.js" "$@"
+elif [ -n "$exe" ] && command -v node.exe >/dev/null 2>&1; then
+  exec node.exe  "$basedir_win/../@cad0p/pi-steering/dist/bin/pi-steering.js" "$@"
+else
+  exec node  "$basedir/../@cad0p/pi-steering/dist/bin/pi-steering.js" "$@"
+fi
+# cmd-shim-target=/home/pier/open-source/github/pi-steering/examples/no-amend/node_modules/@cad0p/pi-steering/dist/bin/pi-steering.js

package/examples/no-amend/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "@examples/no-amend",
+	"version": "0.0.0-example",
+	"private": true,
+	"description": "Rule pack: block git commit --amend.",
+	"type": "module",
+	"peerDependencies": {
+		"@cad0p/pi-steering": "workspace:*"
+	},
+	"devDependencies": {
+		"@cad0p/pi-steering": "workspace:*"
+	},
+	"scripts": {
+		"pretest": "pnpm --filter @cad0p/pi-steering run clean && pnpm --filter @cad0p/pi-steering run build",
+		"test": "node --test --experimental-strip-types 'steering.test.ts'",
+		"typecheck": "tsc --noEmit"
+	}
+}

package/examples/no-amend/steering.cwd-scoped.json

@@ -0,0 +1,12 @@
+{
+  "rules": [
+    {
+      "name": "no-amend-in-personal",
+      "tool": "bash",
+      "field": "command",
+      "pattern": "^git\\b(?:\\s+-{1,2}[A-Za-z]\\S*(?:\\s+\\S+)?)*\\s+commit\\b.*--amend\\b",
+      "when": { "cwd": "^/home/[^/]+/projects/personal/" },
+      "reason": "In personal/shared repos, don't rewrite history. Create a new commit instead."
+    }
+  ]
+}

package/examples/no-amend/steering.json

@@ -0,0 +1,11 @@
+{
+  "rules": [
+    {
+      "name": "no-amend",
+      "tool": "bash",
+      "field": "command",
+      "pattern": "^git\\b(?:\\s+-{1,2}[A-Za-z]\\S*(?:\\s+\\S+)?)*\\s+commit\\b.*--amend\\b",
+      "reason": "Don't rewrite history with --amend. Create a new commit instead. If you need to fix the last commit's message, do it in a follow-up commit — PR reviewers track diffs across pushes and amend confuses that."
+    }
+  ]
+}

package/examples/no-amend/steering.test.ts

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering / examples.
+
+/**
+ * Smoke test for the no-amend rule pack.
+ *
+ * Scope: README drift guard. See `force-push-strict/steering.test.ts`
+ * for the rationale (we're catching compilation drift, not regressing
+ * every rule behavior).
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import config from "./steering.ts";
+
+describe("example: no-amend", () => {
+  it("exports a SteeringConfig with at least one rule", () => {
+    assert.ok(config.rules !== undefined, "config.rules should be defined");
+    assert.ok(
+      config.rules.length >= 1,
+      "config.rules should have at least one rule",
+    );
+  });
+
+  it("registers the no-amend rule", () => {
+    const names = config.rules!.map((r) => r.name);
+    assert.ok(
+      names.includes("no-amend"),
+      `expected no-amend in rules, got: ${names.join(", ")}`,
+    );
+  });
+
+  it("no-amend rule has a bash/command shape and a non-empty reason", () => {
+    const rule = config.rules!.find((r) => r.name === "no-amend");
+    assert.ok(rule);
+    assert.equal(rule!.tool, "bash");
+    assert.ok(
+      typeof rule!.reason === "string" && rule!.reason.length > 0,
+      "reason should be a non-empty string",
+    );
+  });
+
+  it("does not disable any default rules (additive)", () => {
+    assert.ok(
+      config.disabledRules === undefined || config.disabledRules.length === 0,
+      "no-amend is additive; disabledRules should be empty or absent",
+    );
+  });
+});

package/examples/no-amend/steering.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering / examples.
+
+/**
+ * Example: no-amend rule pack.
+ *
+ * Equivalent to `steering.json` in this directory but expressed in the
+ * v0.1.0 canonical TypeScript form. Drop this file in at
+ * `.pi/steering.ts` (or `.pi/steering/index.ts`) to activate.
+ *
+ * What it enforces: blocks `git commit --amend` in any form. Useful
+ * on review-driven workflows where commit-SHA stability matters (an
+ * amend rewrites the SHA, which breaks reviewers' cross-push diff
+ * tracking).
+ *
+ * Scope note: does NOT conflict with any shipped `DEFAULT_RULES`.
+ * The rule is additive.
+ */
+
+import { defineConfig } from "@cad0p/pi-steering";
+
+export default defineConfig({
+  rules: [
+    {
+      name: "no-amend",
+      tool: "bash",
+      field: "command",
+      // Mirrors the pre-subcommand flag slot used by
+      // DEFAULT_RULES.no-force-push so `git -C /path commit --amend`,
+      // `git -c key=val commit --amend`, and
+      // `git --git-dir=/x commit --amend` are all caught.
+      pattern:
+        "^git\\b(?:\\s+-{1,2}[A-Za-z]\\S*(?:\\s+\\S+)?)*\\s+commit\\b.*--amend\\b",
+      reason:
+        "Don't rewrite history with --amend. Create a new commit instead. If you need to fix the last commit's message, do it in a follow-up commit \u2014 PR reviewers track diffs across pushes and amend confuses that.",
+    },
+  ],
+});

package/examples/no-amend/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["steering.ts", "steering.test.ts"]
+}

package/examples/work-item-plugin/README.md

@@ -0,0 +1,103 @@
+# work-item-plugin — example plugin for pi-steering
+
+> **Note**: this is a READABLE REFERENCE, not a plugin for production use. The rules and patterns are domain-generic on purpose — copy the structure, swap the specifics.
+
+A compact plugin that demonstrates every authoring pattern the v0.1.0 release ships. Reading the source top-to-bottom is the fastest way to understand how to build one of these.
+
+## What's in the box
+
+```
+examples/work-item-plugin/
+├── package.json                # peerDep on pi-steering
+├── tsconfig.json               # extends repo base
+├── README.md                   # (this file)
+└── src/
+    ├── index.ts                # default export: Plugin
+    ├── index.test.ts           # end-to-end plugin tests
+    ├── predicates/
+    │   ├── work-item-format.ts       # workItemFormat + [PROJ-N] regex
+    │   └── work-item-format.test.ts
+    ├── observers/
+    │   ├── npm-test-tracker.ts        # TEST_PASSED_EVENT + observer
+    │   ├── npm-test-tracker.test.ts
+    │   ├── retest-required-tracker.ts # RETEST_REQUIRED_EVENT + observer
+    │   └── retest-required-tracker.test.ts
+    └── rules/
+        ├── commit-requires-work-item.ts
+        ├── commit-requires-work-item.test.ts
+        ├── push-requires-tests.ts
+        ├── push-requires-tests.test.ts
+        ├── commit-description-check.ts
+        └── commit-description-check.test.ts
+```
+
+## What each piece demonstrates
+
+| File | Concept |
+| --- | --- |
+| `predicates/work-item-format.ts` | `definePredicate<T>` for typed arg shapes. Quote-aware `input.args` access (ADR §9). |
+| `observers/npm-test-tracker.ts` | Observer encapsulation convention (ADR §14): export `<EVENT>_EVENT` + `mark<Event>(ctx)` helper + the observer. |
+| `observers/retest-required-tracker.ts` | Invalidation-sentinel observer for the `happened.since` pattern. Writes `RETEST_REQUIRED_EVENT` on every successful `git pull`. |
+| `rules/commit-requires-work-item.ts` | Plugin predicate consumed from `when.<key>`. `not:` inversion. |
+| `rules/push-requires-tests.ts` | Observer → rule coupling via shared event constants. `when.happened: { in: "agent_loop", since: ... }` with temporal invalidation. Also demonstrates `&&`-chain speculative allow for `npm test && git push`. |
+| `rules/commit-description-check.ts` | Self-marking rule with `Rule.onFire` (ADR §6). Constant + helper co-located with the rule when no observer corresponds (ADR §14). |
+| `index.ts` | `as const satisfies Plugin` to preserve literal types for `defineConfig`'s compile-time cross-reference checking (ADR §7). |
+
+## ADR references
+
+The canonical references for every pattern this plugin demonstrates live in the repo's ADR log (napkin vault):
+
+- §6 — `Rule.onFire` side-effect hook (self-marking pattern)
+- §7 — `Observer.writes` and `Rule.writes` declarations (compile-time type constraints)
+- §9 — `PredicateToolInput.args` + `basename` (quote-aware structured access)
+- §10 — `definePredicate<T>` helper (typed variance cast)
+- §14 — Observer encapsulation convention (type + helper + consumer pattern)
+- §15 — This example plugin's goals
+
+## Running the tests
+
+```sh
+# From the repo root:
+pnpm install
+pnpm --filter @examples/work-item-plugin test
+```
+
+The `pretest` script builds `@cad0p/pi-steering` first, so the example resolves
+the package through its emitted `dist/` exports. On a fresh clone this
+adds a few seconds on the first run; subsequent runs skip the rebuild if
+nothing changed.
+
+Or `pnpm -r test` runs all packages' suites including this one.
+
+## Consuming this plugin from your own config
+
+```ts
+// .pi/steering/index.ts
+import { defineConfig } from "@cad0p/pi-steering";
+import workItemPlugin from "@examples/work-item-plugin";
+
+export default defineConfig({
+  plugins: [workItemPlugin],
+});
+```
+
+In a real project, you'd replace `@examples/work-item-plugin` with your own published plugin that follows this same layout.
+
+## The rules, in one paragraph each
+
+**`commit-requires-work-item`** — intercepts `git commit -m "..."` and blocks unless the message carries a `[PROJ-N]` token. Uses the `workItemFormat` predicate under `when.not` (the predicate returns "work-item is present" as TRUE; we invert it to mean "fire when missing").
+
+**`push-requires-tests`** — intercepts `git push`. Blocks unless `npm test` has succeeded in the current agent loop AND no subsequent `git pull` has stale-d that success. Combines three features in one rule:
+
+  - `npm-test-tracker` writes `TEST_PASSED_EVENT` on every successful `npm test`.
+  - `retest-required-tracker` writes `RETEST_REQUIRED_EVENT` on every successful `git pull`.
+  - The rule gates via `when.happened: { event: TEST_PASSED_EVENT, in: "agent_loop", since: RETEST_REQUIRED_EVENT }` — fires when tests haven't passed at all in this loop, OR the latest test entry is older than the latest pull entry.
+  - Chain-aware: `npm test && git push` is speculatively allowed pre-execution. `&&` short-circuits on test failure, so the push is guarded without forcing a round-trip through the observer.
+
+**`commit-description-check`** — self-marking reminder. First `git commit` per agent loop blocks with a "re-read your description" message and self-marks via `onFire`. Second `git commit` in the same loop passes (the self-mark satisfies `when.happened`). A new agent loop resets the reminder.
+
+## What's intentionally missing
+
+- **A `Tracker`** — the git plugin (`src/plugins/git/`) is the canonical reference for tracker + trackerExtension authoring. This plugin keeps the surface minimal.
+- **Production-grade regexes** — the `[PROJ-N]` pattern is a placeholder. Real adopters replace with their project's actual ticket format (e.g. `JIRA-\d+`, `AWF-\d+`).
+- **Override customization** — each rule uses the engine defaults around `noOverride`. See the main README's "Authoring rules" section for how overrides work.

package/examples/work-item-plugin/node_modules/.bin/pi-steering

@@ -0,0 +1,43 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+basedir_win="$basedir"
+exe=""
+msys=""
+
+case `uname -a` in
+  *CYGWIN*|*MINGW*|*MSYS*)
+    if command -v cygpath > /dev/null 2>&1; then
+      basedir_win=`cygpath -w "$basedir"`
+    fi
+    exe=".exe"
+    msys="true"
+  ;;
+  *WSL2*)
+    if command -v wslpath > /dev/null 2>&1; then
+      basedir_win="$(wslpath -w "$basedir" 2> /dev/null)"
+      if [ $? -ne 0 ] || [ -z "$basedir_win" ]; then
+        basedir_win="$basedir"
+      else
+        exe=".exe"
+      fi
+    fi
+  ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/pier/open-source/github/pi-steering/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/pier/open-source/github/pi-steering/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -n "$exe" ] && [ -x "$basedir/node.exe" ]; then
+  exec "$basedir/node.exe"  "$basedir_win/../@cad0p/pi-steering/dist/bin/pi-steering.js" "$@"
+elif [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../@cad0p/pi-steering/dist/bin/pi-steering.js" "$@"
+elif command -v node >/dev/null 2>&1; then
+  exec node  "$basedir/../@cad0p/pi-steering/dist/bin/pi-steering.js" "$@"
+elif [ -n "$exe" ] && command -v node.exe >/dev/null 2>&1; then
+  exec node.exe  "$basedir_win/../@cad0p/pi-steering/dist/bin/pi-steering.js" "$@"
+else
+  exec node  "$basedir/../@cad0p/pi-steering/dist/bin/pi-steering.js" "$@"
+fi
+# cmd-shim-target=/home/pier/open-source/github/pi-steering/examples/work-item-plugin/node_modules/@cad0p/pi-steering/dist/bin/pi-steering.js

package/examples/work-item-plugin/package.json

@@ -0,0 +1,19 @@
+{
+	"name": "@examples/work-item-plugin",
+	"version": "0.0.0-example",
+	"private": true,
+	"description": "Canonical example plugin for pi-steering (ADR \u00a715).",
+	"type": "module",
+	"peerDependencies": {
+		"@cad0p/pi-steering": "workspace:*"
+	},
+	"devDependencies": {
+		"@cad0p/pi-steering": "workspace:*",
+		"@cad0p/unbash-walker": "^0.1.0"
+	},
+	"scripts": {
+		"pretest": "pnpm --filter @cad0p/pi-steering run clean && pnpm --filter @cad0p/pi-steering run build",
+		"test": "node --test --experimental-strip-types 'src/**/*.test.ts'",
+		"typecheck": "tsc --noEmit"
+	}
+}

package/examples/work-item-plugin/src/index.test.ts

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * Plugin-level integration test.
+ *
+ * Wires the WHOLE plugin (not just one rule at a time) and exercises
+ * a few end-to-end scenarios. Each per-file test already covers unit
+ * behavior; this suite's job is to catch wiring-level regressions —
+ * e.g. the predicate not being registered, a rule not being listed,
+ * the observer's `writes` declaration not threading through.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  createRecordingHost,
+  expectAllows,
+  expectBlocks,
+  loadHarness,
+  mockExtensionContext,
+} from "@cad0p/pi-steering/testing";
+import workItemPlugin, {
+  DESCRIPTION_REVIEWED_EVENT,
+  TEST_PASSED_EVENT,
+} from "./index.ts";
+
+describe("work-item-plugin (end-to-end)", () => {
+  it("registers the expected predicates, rules, observers", () => {
+    assert.equal(workItemPlugin.name, "work-item");
+    assert.ok(workItemPlugin.predicates?.workItemFormat);
+    assert.equal(workItemPlugin.rules?.length, 3);
+    assert.equal(workItemPlugin.observers?.length, 2);
+
+    const ruleNames = workItemPlugin.rules?.map((r) => r.name);
+    assert.deepEqual(ruleNames, [
+      "commit-requires-work-item",
+      "push-requires-tests",
+      "commit-description-check",
+    ]);
+
+    const observerNames = workItemPlugin.observers?.map((o) => o.name);
+    assert.deepEqual(observerNames, [
+      "npm-test-tracker",
+      "retest-required-tracker",
+    ]);
+  });
+
+  it("blocks a commit without a work-item tag", async () => {
+    const harness = loadHarness({
+      config: { plugins: [workItemPlugin] },
+    });
+    await expectBlocks(
+      harness,
+      { command: 'git commit -m "feat: add thing"' },
+      { rule: "commit-requires-work-item" },
+    );
+  });
+
+  it("blocks git push when tests haven't passed this loop", async () => {
+    const harness = loadHarness({
+      config: { plugins: [workItemPlugin] },
+    });
+    await expectBlocks(
+      harness,
+      { command: "git push" },
+      { rule: "push-requires-tests" },
+    );
+  });
+
+  it("allows a well-formed commit after description-check self-marks", async () => {
+    // This test is intentionally the FULL happy-path: block on
+    // first commit (description-check fires), self-mark, then
+    // allow the second commit that carries a [PROJ-N] tag.
+    const host = createRecordingHost();
+    const ctx = mockExtensionContext("/tmp/test", host.entries);
+    const harness = loadHarness({
+      config: { plugins: [workItemPlugin] },
+      host,
+    });
+
+    // First: commit-description-check fires and self-marks.
+    const first = await harness.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "tc1",
+        toolName: "bash",
+        input: { command: 'git commit -m "feat: [PROJ-1] work"' },
+      } as unknown as Parameters<typeof harness.evaluate>[0],
+      ctx,
+      1,
+    );
+    assert.ok(
+      first !== undefined && first !== null,
+      "first commit should block on the reminder",
+    );
+    assert.ok(
+      host.entries.some((e) => e.customType === DESCRIPTION_REVIEWED_EVENT),
+      "DESCRIPTION_REVIEWED_EVENT should be present after onFire",
+    );
+
+    // Second: well-formed commit passes. `commit-requires-work-item`
+    // also runs; message has the tag so it's fine.
+    const second = await harness.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "tc2",
+        toolName: "bash",
+        input: { command: 'git commit -m "feat: [PROJ-1] work"' },
+      } as unknown as Parameters<typeof harness.evaluate>[0],
+      ctx,
+      1,
+    );
+    assert.equal(second, undefined, "second well-formed commit should pass");
+  });
+
+  it("dispatch → evaluate: npm test success unblocks git push in the same loop", async () => {
+    const host = createRecordingHost();
+    const ctx = mockExtensionContext("/tmp/test", host.entries);
+    const harness = loadHarness({
+      config: { plugins: [workItemPlugin] },
+      host,
+    });
+
+    // Fire npm test success through the dispatcher — observer
+    // writes TEST_PASSED_EVENT into the shared entries store.
+    await harness.dispatch(
+      {
+        type: "tool_result",
+        toolCallId: "tc1",
+        toolName: "bash",
+        input: { command: "npm test" },
+        content: [],
+        details: { exitCode: 0 },
+      } as unknown as Parameters<typeof harness.dispatch>[0],
+      ctx,
+      7,
+    );
+    assert.ok(
+      host.entries.some((e) => e.customType === TEST_PASSED_EVENT),
+      "observer should have written TEST_PASSED_EVENT",
+    );
+
+    // Push now allowed — tests passed this loop.
+    const pushResult = await harness.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "tc2",
+        toolName: "bash",
+        input: { command: "git push" },
+      } as unknown as Parameters<typeof harness.evaluate>[0],
+      ctx,
+      7,
+    );
+    assert.equal(
+      pushResult,
+      undefined,
+      "push-requires-tests should not fire after npm test succeeded",
+    );
+  });
+
+  it("does not fire on unrelated commands", async () => {
+    const harness = loadHarness({
+      config: { plugins: [workItemPlugin] },
+    });
+    await expectAllows(harness, { command: "ls -la" });
+  });
+});