@cad0p/pi-steering 0.1.0

package/examples/dynamic-reason-runtime-cwd/README.md

@@ -0,0 +1,148 @@
+# Example: dynamic-reason + walker-unknown-cwd
+
+Worked example tying together two pi-steering primitives:
+
+- Runtime-cwd predicate trinary surfacing (gitPlugin's `isClean` /
+  `hasStagedChanges` / `remote` / `upstream` / `commitsAhead` all inline a
+  walker-unknown-cwd guard at the top of the handler and surface trinary
+  `"unknown"` when the walker can't statically resolve cwd). The engine's
+  leaf-level (or block-level inside `not:`) `onUnknown:` policy then
+  projects to a definite verdict — default `"block"` (fail-CLOSED, rule
+  fires).
+- `walkerUnknownCwdReason` (from `@cad0p/pi-steering`) — the agent-facing reason
+  text helper for the walker-unknown-cwd fail-CLOSED branch.
+
+Together these give external plugin authors the ergonomics story for
+runtime-cwd predicates: every gitPlugin runtime-cwd predicate gets the
+engine's fail-CLOSED `onUnknown: "block"` semantics for free, and the
+`walkerUnknownCwdReason` helper produces a useful agent-facing message
+that distinguishes "the predicate fired because the state is genuinely
+bad" from "the predicate fired because the walker couldn't tell".
+
+## Pattern
+
+The rule's `reason` is a `ReasonFn` (not a static string). It branches on
+`ctx.walkerState?.cwd === "unknown"`:
+
+```ts
+reason: (ctx) => {
+  if (ctx.walkerState?.cwd === "unknown") {
+    // Walker couldn't statically resolve cwd. The predicate's inline
+    // guard surfaced trinary "unknown"; the engine's default
+    // onUnknown: "block" projected it to true so the rule fired
+    // fail-CLOSED. Produce a generic explanation via the helper, then
+    // append retry guidance.
+    return (
+      walkerUnknownCwdReason(ctx, "working tree status") +
+      " Run from inside the package directory with a literal path."
+    );
+  }
+  // Walker statically resolved cwd; the predicate genuinely fired
+  // (working tree is dirty). Domain-specific reason.
+  return "Working tree has uncommitted changes. Commit or stash before deploying.";
+},
+```
+
+The agent gets a useful next-step in both cases instead of a
+generic "rule blocked" message.
+
+The rule is gated by `when: { isClean: false }`. The next subsection
+explains why this canonical positive form is preferred over
+`when: { not: { isClean: true } }` even though both shapes now produce
+the same fail-CLOSED behavior under walker-unknown cwd by default.
+
+## Why `isClean: false` over `not: { isClean: true }`
+
+Both shapes describe "the working tree is NOT clean". Under the trinary
+engine introduced in v0.1.0, both are fail-CLOSED by default on the
+walker-unknown-cwd branch, so polarity-of-default is no longer the
+deciding factor. The recommendation is now about readability, smaller
+composition surface, and an end-to-end behavior gap on the
+walker-known + git-fails row.
+
+| state                       | `isClean` returns | `when: { isClean: false }`      | `when: { not: { isClean: true } }` |
+|-----------------------------|-------------------|----------------------------------|--------------------------------------|
+| walker-unknown cwd          | `"unknown"`       | fires ✅ (leaf default block)    | fires ✅ (block-level default block) |
+| walker-known + clean        | `true`            | does NOT fire ✅                 | does NOT fire ✅                      |
+| walker-known + dirty        | `false`           | fires ✅                         | fires ✅                              |
+| walker-known + git fails    | `false`           | does NOT fire ❌ (fail-OPEN)     | fires ⚠️ (Kleene-AND-false absorbs)  |
+
+The two shapes agree on every row except `walker-known + git fails`,
+where they diverge:
+
+- `isClean: false`: the handler returns boolean `false` on git failure
+  (`getWorkingTreeClean` returns `null` → handler short-circuits to
+  `false`, NOT `"unknown"`).  Leaf verdict is `false` → rule skips.
+- `not: { isClean: true }`: the handler again returns `false` on git
+  failure.  Inner verdict is `false`, Kleene AND of a single false leaf
+  is `false`, the not-flip yields `true` → rule fires.
+
+The asymmetry is real: `isClean: false` reads as "fire when the
+handler positively asserts dirty"; `not: { isClean: true }` reads as
+"fire when the handler does NOT positively assert clean", and a
+failed git call is a non-clean-assertion under that wording.  Pair
+`isClean` with an `upstream` check to cover the git-fails branch
+uniformly under either shape (handler returns `false` on git failure;
+the `upstream:` leaf surfaces trinary `"unknown"` and the engine's
+`onUnknown:` policy projects).
+
+Why prefer `{ isClean: false }`:
+
+- **Reads forward.** "Block when isClean is false" matches how a human
+  describes the rule out loud.
+- **Smaller composition surface.** A bare leaf takes per-leaf
+  modifiers (`isClean: { value: false, onUnknown: "allow" }`) at the
+  leaf level. A `not:` block takes block-level modifiers and forbids
+  per-leaf modifiers inside; if you ever need a different `onUnknown:`
+  policy on this single leaf, the bare form is the simpler edit.
+- **Idiomatic.** gitPlugin's `predicates.ts` JSDoc documents both
+  polarities of every boolean predicate (`isClean: true` /
+  `isClean: false`, `hasStagedChanges: true` / `hasStagedChanges: false`)
+  exactly so authors can avoid `not:` for negation when a documented
+  inverted shape exists.
+
+### Pair with `upstream:` to cover the git-fails branch
+
+Neither bare-form nor `not:`-form covers the `walker-known + git fails`
+row uniformly.  Put a fail-CLOSED `upstream:` check first in the same
+`when:` to convert the gitfailure into a definite verdict (the
+`upstream:` handler surfaces `"unknown"` instead of returning a
+boolean, so the engine's `onUnknown:` policy projects to fail-CLOSED
+and the rule fires regardless of which `isClean:` shape you used):
+
+```ts
+when: { upstream: /./, isClean: false }
+```
+
+`{ not: { isClean: true } }` is correct under the new engine for the
+walker-unknown row — pick whichever reads cleaner at the call site,
+and pair it with `upstream:` either way.
+
+Rule of thumb for any future plugin author copying this example:
+prefer the predicate's documented inverted shape (e.g., `isClean: false`,
+`hasStagedChanges: false`) when one exists. Reach for `not:` when
+combining multiple leaves under a single negation
+(`not: { branch: "main", remote: /github/ }`) or when no inverted
+shape is available (regex predicates, etc.).
+
+## When to use this pattern
+
+When your rule consumes any runtime-cwd predicate from a plugin
+(gitPlugin's `isClean` / `hasStagedChanges` / `remote` / `upstream` /
+`commitsAhead`, or any external plugin's runtime-cwd predicate that
+inlines a `cwdIsWalkerUnknown` guard).
+
+Without the two-branch ReasonFn, a rule with a static `reason: "..."`
+would print the same message in both cases — uninformative when the
+trigger was a dynamic-cwd target the walker bailed on.
+
+## Cross-references
+
+- `walkerUnknownCwdReason` JSDoc — `src/helpers/walker-unknown-cwd-reason.ts`. Read for the helper's signature, the `verifying` arg contract, and a worked rule snippet.
+- gitPlugin runtime-cwd predicates — `src/plugins/git/predicates.ts`. Each has a `@see {@link walkerUnknownCwdReason}` cross-link in its JSDoc, surfacing the helper at the predicate's hover location.
+
+## Run the tests
+
+```bash
+pnpm --filter @examples/dynamic-reason-runtime-cwd test
+```

package/examples/dynamic-reason-runtime-cwd/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/dynamic-reason-runtime-cwd/node_modules/@cad0p/pi-steering/dist/bin/pi-steering.js

package/examples/dynamic-reason-runtime-cwd/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "@examples/dynamic-reason-runtime-cwd",
+	"version": "0.0.0-example",
+	"private": true,
+	"description": "Worked example: dynamic-reason + walker-unknown-cwd pattern (runtime-cwd predicate trinary surfacing + walkerUnknownCwdReason).",
+	"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/dynamic-reason-runtime-cwd/steering.test.ts

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering / examples.
+
+/**
+ * Tests for the dynamic-reason + walker-unknown-cwd example.
+ *
+ * Pin the two ReasonFn branches:
+ *
+ *   1. Walker-unknown cwd → reason text contains
+ *      `walkerUnknownCwdReason`'s anchor ("current directory:") AND
+ *      the example's appended retry guidance ("literal path"
+ *      reference is in the helper, "package directory" is in the
+ *      append).
+ *   2. Walker-known cwd → reason text is the static "uncommitted
+ *      changes" message.
+ *
+ * Also smoke-test the config shape (registered rule, bash/command,
+ * non-empty reason callable). The third branch (walker-known + clean
+ * tree → no fire) is covered structurally via the rule-shape pin
+ * below — inverting the `when:` clause regresses the test — rather
+ * than via a full engine roundtrip; full-engine coverage of the
+ * three-branch matrix is a v0.1.x candidate.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { PredicateContext } from "@cad0p/pi-steering";
+import { mockContext } from "@cad0p/pi-steering/testing";
+import config from "./steering.ts";
+
+/**
+ * Pull the only rule out of the config. Throws if the example
+ * regresses to a multi-rule shape — the tests below assume one rule.
+ */
+function getDeployRule() {
+  assert.ok(config.rules !== undefined, "config.rules should be defined");
+  const rule = config.rules.find(
+    (r) => r.name === "deploy-requires-clean-tree",
+  );
+  assert.ok(rule, "deploy-requires-clean-tree rule must be registered");
+  return rule;
+}
+
+/**
+ * Invoke the rule's `reason` function. The example uses a function
+ * reason (not a string), so this helper unwraps the callable.
+ */
+async function callReason(ctx: PredicateContext): Promise<string> {
+  const rule = getDeployRule();
+  assert.equal(
+    typeof rule.reason,
+    "function",
+    "this example's reason should be a ReasonFn",
+  );
+  const out = await (
+    rule.reason as (ctx: PredicateContext) => string | Promise<string>
+  )(ctx);
+  return out;
+}
+
+describe("example: dynamic-reason-runtime-cwd", () => {
+  it("rule.when uses the canonical positive form (`isClean: false`)", () => {
+    // Pins the rule's `when:` to `{ isClean: false }`. The equivalent
+    // `{ not: { isClean: true } }` shape produces the same fail-CLOSED
+    // behavior on the walker-unknown branch under the trinary engine's
+    // default block-level `onUnknown: "block"`, but diverges on the
+    // walker-known + git-fails row (see README truth table); the
+    // positive form is preferred for readability and per-leaf modifier
+    // composition. See README "Why isClean: false over not: { isClean: true }".
+    const rule = getDeployRule();
+    assert.deepEqual(rule.when, { isClean: false });
+  });
+
+  it("registers the deploy-requires-clean-tree rule (bash/command)", () => {
+    const rule = getDeployRule();
+    assert.equal(rule.tool, "bash");
+    assert.equal(rule.field, "command");
+  });
+
+  it("walker-unknown cwd → reason composes walkerUnknownCwdReason + retry guidance", async () => {
+    // Walker couldn't statically resolve cwd. The ReasonFn detects
+    // `ctx.walkerState.cwd === "unknown"` and delegates to
+    // `walkerUnknownCwdReason`, then appends domain-specific retry
+    // guidance.
+    const ctx = mockContext({
+      cwd: "/repo/root",
+      walkerState: { cwd: "unknown", env: new Map() },
+    });
+    const reason = await callReason(ctx);
+
+    // Helper anchor — pinned by walker-unknown-cwd-reason.test.ts.
+    assert.ok(
+      reason.includes("current directory:"),
+      `expected helper anchor, got: ${reason}`,
+    );
+    // Helper surfaces the actual ctx.cwd.
+    assert.ok(
+      reason.includes("/repo/root"),
+      `expected ctx.cwd in reason, got: ${reason}`,
+    );
+    // Example's appended retry guidance.
+    assert.ok(
+      reason.includes("package directory"),
+      `expected example's retry guidance ('package directory'), got: ${reason}`,
+    );
+  });
+
+  it("walker-known cwd → reason is the static `uncommitted changes` message", async () => {
+    // Walker statically resolved cwd. The dirty-tree path: gitPlugin's
+    // `isClean` returned false, the rule fires, and the ReasonFn
+    // produces the domain-specific reason text.
+    const ctx = mockContext({
+      cwd: "/repo/root",
+      walkerState: { cwd: "/repo/root", env: new Map() },
+    });
+    const reason = await callReason(ctx);
+
+    // Static text — wording-tweak refactors should not break this
+    // assertion; pin substrings, not exact equality.
+    assert.ok(
+      reason.toLowerCase().includes("uncommitted"),
+      `expected static reason to mention 'uncommitted', got: ${reason}`,
+    );
+    // And the helper anchor MUST be absent on the static branch.
+    assert.ok(
+      !reason.includes("current directory:"),
+      `static branch must not emit the helper anchor, got: ${reason}`,
+    );
+  });
+});

package/examples/dynamic-reason-runtime-cwd/steering.ts

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering / examples.
+
+/**
+ * Example: dynamic-reason + walker-unknown-cwd pattern.
+ *
+ * Demonstrates how external plugin authors compose runtime-cwd
+ * predicates (gitPlugin's `isClean` / `hasStagedChanges` / `remote` /
+ * `upstream` / `commitsAhead` — each inlines a walker-unknown-cwd
+ * guard at the top of its handler and surfaces trinary `"unknown"`)
+ * with informative agent-facing reasons that distinguish two
+ * branches:
+ *
+ *   - Static cwd + predicate fires: domain-specific reason text
+ *     (the working tree is genuinely dirty).
+ *   - Walker-unknown cwd: `walkerUnknownCwdReason()` explains the
+ *     walker couldn't statically resolve cwd, surfaces the actual
+ *     `ctx.cwd`, and prompts a retry with a literal path. The
+ *     example appends a small piece of domain-specific retry
+ *     guidance after the helper's output.
+ *
+ * Drop this file in at `.pi/steering.ts` (or
+ * `.pi/steering/index.ts`) to activate. The example uses gitPlugin's
+ * `isClean` predicate to gate `npm run deploy` on a clean working
+ * tree.
+ */
+
+import { defineConfig, type Rule, walkerUnknownCwdReason } from "@cad0p/pi-steering";
+import gitPlugin from "@cad0p/pi-steering/plugins/git";
+
+/**
+ * Rule: block `npm run deploy` when the working tree isn't clean.
+ *
+ * The `reason` field is a {@link ReasonFn} that branches on
+ * `ctx.walkerState?.cwd === "unknown"` to detect the
+ * walker-unknown-cwd fail-CLOSED branch. gitPlugin's `isClean` inlines
+ * a walker-unknown-cwd guard at the top of its handler and surfaces
+ * trinary `"unknown"` when the walker can't statically resolve cwd;
+ * the engine's leaf-level `onUnknown:` policy (default `"block"`)
+ * projects to a definite `true` and the rule fires fail-CLOSED. On
+ * that branch, `walkerUnknownCwdReason` produces the canonical
+ * agent-facing explanation; the example appends domain-specific
+ * retry guidance after it.
+ */
+const deployRequiresCleanTree = {
+  name: "deploy-requires-clean-tree",
+  tool: "bash",
+  field: "command",
+  pattern: /^npm\s+run\s+deploy\b/,
+  // Canonical positive form: `isClean: false` ("fires when dirty")
+  // reads forward and lets per-leaf modifiers attach at the leaf if
+  // ever needed. The equivalent `not: { isClean: true }` form is also
+  // safe under the new engine — the trinary `"unknown"` from the
+  // inline walker-unknown-cwd guard composes via the not-block's
+  // default block-level `onUnknown: "block"` to fire fail-CLOSED on
+  // the walker-unknown branch — but `isClean: false` is the simpler
+  // shape when no other leaves share the not-block. See README
+  // "Why isClean: false over not: { isClean: true }" for the full
+  // truth table.
+  when: { isClean: false },
+  reason: (ctx) => {
+    if (ctx.walkerState?.cwd === "unknown") {
+      // Walker couldn't statically resolve cwd. The handler's
+      // inline guard surfaced trinary `"unknown"`; the engine's
+      // default leaf-level `onUnknown: "block"` projected it to true
+      // and the rule fired fail-CLOSED. Use the helper for a
+      // consistent agent-facing explanation; append domain-specific
+      // retry guidance.
+      return (
+        walkerUnknownCwdReason(ctx, "working tree status") +
+        " Run from inside the package directory with a literal path."
+      );
+    }
+    // Predicate fired with a known cwd: working tree is genuinely dirty.
+    return "Working tree has uncommitted changes. Commit or stash before deploying.";
+  },
+} as const satisfies Rule;
+
+export default defineConfig({
+  plugins: [gitPlugin],
+  rules: [deployRequiresCleanTree],
+});

package/examples/dynamic-reason-runtime-cwd/tsconfig.json

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

package/examples/force-push-strict/README.md

@@ -0,0 +1,75 @@
+# force-push-strict
+
+A rule pack that blocks **every** form of `git push --force`, including `--force-with-lease`.
+
+## What it enforces
+
+- `git push --force` → blocked
+- `git push -f` → blocked
+- `git push --force-with-lease` → **blocked** (this is the difference from the default)
+- `git push origin main` → allowed
+
+The pattern also handles git pre-subcommand flags (`git -C /other push --force`, `git -c key=val push -f`) and wrapper bypasses (`sh -c 'git push --force'`, `sudo xargs git push --force`, …) — all transparently, via the AST backend.
+
+## How it differs from the default
+
+The built-in `no-force-push` rule permits `--force-with-lease` because the lease flag is the documented "safe" way to update a branch after a rebase. That's fine for most teams, but in environments where:
+
+- the branch is shared broadly (`main`, `develop`, long-lived release branches),
+- history integrity is a compliance requirement, or
+- you want the agent to never reach for any `--force` variant as a first-line fix,
+
+the lease-variant carve-out is an attack surface. This rule pack closes it.
+
+## When to use
+
+- Strict-history environments (shared release branches, regulated contexts)
+- Teams that want a single "never force push" discipline without agent-side judgement calls
+- As a starting point for more restrictive house rules
+
+## Install
+
+Two equivalent forms. Pick whichever matches your setup.
+
+### TypeScript form (canonical)
+
+Copy [`steering.ts`](./steering.ts) to `~/.pi/steering.ts` (or
+`<project-root>/.pi/steering.ts`) for a repo-scoped policy. The
+TypeScript form participates in compile-time checking via
+`defineConfig`. The loader accepts TypeScript only.
+
+### JSON form (for migration)
+
+The loader does **not** load `.pi/steering.json` files directly. The
+[`steering.json`](./steering.json) below is provided as a reference
+shape for `pi-steering import-json` migration — convert it with
+`pi-steering import-json steering.json -o .pi/steering/index.ts` (or
+programmatically via `fromJSON` from `compat.ts`).
+
+JSON is a deliberate subset of the TypeScript shape: pattern-string
+rules, `requires` / `unless`, `when.cwd` (string pattern only), and
+override flags. Plugins, observers, function-valued rule fields,
+plugin-registered predicate keys (`when.<customKey>`), `when.not`,
+and `when.condition` are TypeScript-only — equivalently, any `when`
+clause member other than `when.cwd` is rejected.
+
+The `disable` entry below turns off the built-in `no-force-push`; the
+new `no-force-push-strict` rule takes its place:
+
+```json
+{
+  "disable": ["no-force-push"],
+  "rules": [
+    {
+      "name": "no-force-push-strict",
+      "tool": "bash",
+      "field": "command",
+      "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."
+    }
+  ]
+}
+```
+
+See [examples/README.md#json](../README.md#json) for the full migration
+workflow and the v0 fallback option.

package/examples/force-push-strict/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/force-push-strict/node_modules/@cad0p/pi-steering/dist/bin/pi-steering.js

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

@@ -0,0 +1,18 @@
+{
+	"name": "@examples/force-push-strict",
+	"version": "0.0.0-example",
+	"private": true,
+	"description": "Rule pack: no force pushes of any kind (strict).",
+	"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/force-push-strict/steering.json

@@ -0,0 +1,12 @@
+{
+  "disable": ["no-force-push"],
+  "rules": [
+    {
+      "name": "no-force-push-strict",
+      "tool": "bash",
+      "field": "command",
+      "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/steering.test.ts

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering / examples.
+
+/**
+ * Smoke test for the force-push-strict rule pack.
+ *
+ * Scope: README drift guard. Asserts that `steering.ts` compiles
+ * (covered by `tsc --noEmit` in the typecheck script) and that the
+ * resolved config has the expected shape. Full behavioral coverage
+ * (every pattern, every wrapper form) lives in the engine's own test
+ * suite, not here.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import config from "./steering.ts";
+
+describe("example: force-push-strict", () => {
+  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 strict rule name", () => {
+    const names = config.rules!.map((r) => r.name);
+    assert.ok(
+      names.includes("no-force-push-strict"),
+      `expected no-force-push-strict in rules, got: ${names.join(", ")}`,
+    );
+  });
+
+  it("disables the default `no-force-push` so the stricter variant owns the reason message", () => {
+    assert.ok(
+      config.disabledRules?.includes("no-force-push"),
+      "expected disabledRules to include 'no-force-push'",
+    );
+  });
+
+  it("strict rule has a bash/command shape and a non-empty reason", () => {
+    const strict = config.rules!.find((r) => r.name === "no-force-push-strict");
+    assert.ok(strict, "no-force-push-strict not found");
+    assert.equal(strict!.tool, "bash");
+    assert.ok(
+      typeof strict!.reason === "string" && strict!.reason.length > 0,
+      "reason should be a non-empty string",
+    );
+  });
+});