@cad0p/pi-steering 0.1.0

package/examples/work-item-plugin/src/predicates/work-item-format.ts

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * `workItemFormat` — example plugin predicate.
+ *
+ * Demonstrates two things at once:
+ *
+ *   1. How to use `definePredicate<T>` for a typed arg shape.
+ *   2. How to read structured args via `input.args` (ADR §9).
+ *
+ * Accepted arg shape:
+ *
+ *   ```ts
+ *   when: { workItemFormat: { pattern: /\[PROJ-\d+\]/ } }
+ *   ```
+ *
+ * Semantics:
+ *
+ *   - Extracts the commit message from a `-m` flag in `input.args`.
+ *     This is the preferred path because `input.args` preserves
+ *     quoting via `Word.value` — `-m "feat: [PROJ-42]"` lands as a
+ *     single Word with `value === "feat: [PROJ-42]"`.
+ *   - If `-m` can't be found in `input.args` (the user authored a
+ *     rule for a non-commit command, or args is absent for some
+ *     reason), falls back to testing `input.command` directly. The
+ *     fallback is conservative: it just checks if the pattern
+ *     appears anywhere in the flattened command string.
+ *
+ * Fail-closed: if the predicate can't determine a message at all,
+ * returns `false` (rule does NOT fire) so authoring typos don't
+ * spuriously block every commit.
+ */
+
+import type { Word } from "@cad0p/pi-steering";
+import { definePredicate } from "@cad0p/pi-steering";
+
+/** Argument shape the `when.workItemFormat` slot accepts. */
+export interface WorkItemFormatArgs {
+  /** Required regex the commit message must match. */
+  pattern: RegExp;
+}
+
+/**
+ * Walk `args` looking for a `-m` / `--message` flag and return the
+ * message value (the Word that FOLLOWS the flag). Returns `null` if
+ * no `-m`-like flag is present.
+ *
+ * Notes:
+ *   - `.value` is the quote-unwrapped lexical value (`feat: x`),
+ *     `.text` is the raw source (`"feat: x"`). Rules care about
+ *     lexical content.
+ *   - The combined form `-m"msg"` is not parsed as a single Word by
+ *     unbash (shell doesn't either — the quotes end the flag token
+ *     prematurely). We treat `-m` and `--message` as space-separated
+ *     only, which matches 99% of human usage.
+ */
+function extractMessage(args: readonly Word[]): string | null {
+  for (let i = 0; i < args.length; i++) {
+    const w = args[i];
+    if (w === undefined) continue;
+    if (w.value === "-m" || w.value === "--message") {
+      const next = args[i + 1];
+      if (next !== undefined) {
+        return next.value;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * The predicate handler itself. See module doc for the arg shape and
+ * fallback policy.
+ */
+export const workItemFormat = definePredicate<WorkItemFormatArgs>(
+  (args, ctx) => {
+    if (!(args?.pattern instanceof RegExp)) return false;
+
+    // Preferred: structured args with quote-awareness.
+    if (ctx.input.args !== undefined) {
+      const msg = extractMessage(ctx.input.args);
+      if (msg !== null) {
+        return args.pattern.test(msg);
+      }
+    }
+
+    // Fallback: match anywhere in the flattened command string.
+    // Conservative — a rule whose `pattern` already anchored on
+    // `git commit -m` has narrowed the scope, so arbitrary
+    // command content shouldn't match the ticket regex by
+    // accident.
+    if (ctx.input.command !== undefined) {
+      return args.pattern.test(ctx.input.command);
+    }
+
+    return false;
+  },
+);

package/examples/work-item-plugin/src/rules/commit-description-check.test.ts

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * Tests for `commit-description-check`. The critical path is the
+ * two-call sequence within one agent loop:
+ *   1. First commit blocks, onFire writes the self-mark.
+ *   2. Second commit in the same loop passes.
+ *   3. A commit in the NEXT agent loop blocks again.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  createRecordingHost,
+  expectAllows,
+  loadHarness,
+  mockExtensionContext,
+} from "@cad0p/pi-steering/testing";
+import {
+  commitDescriptionCheck,
+  DESCRIPTION_REVIEWED_EVENT,
+} from "./commit-description-check.ts";
+
+describe("commit-description-check", () => {
+  it("blocks the first commit per loop, allows the second (self-mark)", async () => {
+    // Recording host + shared ExtensionContext: writes via
+    // host.appendEntry flow back into ctx.sessionManager.getEntries
+    // so later evaluate() calls see the self-mark the previous call
+    // wrote. Same plumbing the real pi runtime wires, minus the
+    // child-process bits.
+    const host = createRecordingHost();
+    const ctx = mockExtensionContext("/tmp/test", host.entries);
+
+    const harness = loadHarness({
+      config: { rules: [commitDescriptionCheck] },
+      host,
+    });
+
+    // First commit in loop 1 — blocks AND self-marks.
+    const first = await harness.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "tc1",
+        toolName: "bash",
+        input: { command: 'git commit -m "first"' },
+      } as unknown as Parameters<typeof harness.evaluate>[0],
+      ctx,
+      1,
+    );
+    assert.ok(
+      first !== undefined && first !== null,
+      "first commit should block",
+    );
+
+    // `onFire` wrote the reminder entry.
+    assert.ok(
+      host.entries.some((e) => e.customType === DESCRIPTION_REVIEWED_EVENT),
+      "onFire did not self-mark the DESCRIPTION_REVIEWED_EVENT entry",
+    );
+
+    // Second commit in the same loop — the reminder entry is now
+    // present, so `when.happened` no longer fires; the rule
+    // passes.
+    const second = await harness.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "tc2",
+        toolName: "bash",
+        input: { command: 'git commit -m "second"' },
+      } as unknown as Parameters<typeof harness.evaluate>[0],
+      ctx,
+      1,
+    );
+    assert.equal(
+      second,
+      undefined,
+      "second commit in the same loop should pass after self-mark",
+    );
+
+    // New agent loop (index bumps) — the entry's
+    // `_agentLoopIndex` is 1, but this is loop 2, so
+    // `when.happened` filters it out and the reminder fires
+    // again.
+    const nextLoop = await harness.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "tc3",
+        toolName: "bash",
+        input: { command: 'git commit -m "new loop"' },
+      } as unknown as Parameters<typeof harness.evaluate>[0],
+      ctx,
+      2,
+    );
+    assert.ok(
+      nextLoop !== undefined && nextLoop !== null,
+      "new-loop commit should block — stale reminder doesn't carry over",
+    );
+  });
+
+  it("does NOT fire on a non-commit command", async () => {
+    const harness = loadHarness({
+      config: { rules: [commitDescriptionCheck] },
+    });
+    await expectAllows(harness, { command: "git status" });
+  });
+});

package/examples/work-item-plugin/src/rules/commit-description-check.ts

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * `commit-description-check` — self-marking reminder rule.
+ *
+ * Demonstrates `Rule.onFire` + self-marking (ADR §6, §14):
+ *
+ *   - Pattern `/^git\s+commit\b/` matches any commit command.
+ *   - `when.happened: { event: DESCRIPTION_REVIEWED_EVENT, in: "agent_loop" }`
+ *     fires when the reminder entry has NOT been written this loop.
+ *   - `onFire: markDescriptionReviewed` writes that entry when the
+ *     rule blocks. First commit per agent loop → blocks with the
+ *     reminder, self-marks. Second commit in the same loop → the
+ *     entry is now present, `when.happened` no longer fires, commit
+ *     is allowed.
+ *
+ * ## Encapsulation (ADR §14)
+ *
+ * No corresponding observer ships the `DESCRIPTION_REVIEWED_EVENT`
+ * event — the rule is the producer and the consumer. The convention
+ * for that case is: the constant + helper live IN THE RULE FILE
+ * itself. Observer files own their constants; self-marking rule
+ * files own theirs.
+ *
+ * Override: allowed. Skipping the reminder is a workflow choice.
+ */
+
+import type { PredicateContext, Rule } from "@cad0p/pi-steering";
+
+/**
+ * Session-entry type written by this rule's `onFire`. Exported so
+ * tests (or any other rule / observer in the same plugin) can
+ * reference the same literal.
+ */
+export const DESCRIPTION_REVIEWED_EVENT =
+  "example-description-reviewed" as const;
+
+/**
+ * Shape of the payload written on self-mark. Minimal — the rule just
+ * needs a presence marker; the timestamp the engine attaches via
+ * `findEntries` is enough for any downstream logic.
+ */
+interface DescriptionReviewedPayload {
+  /** Which commit command variant the reminder fired on. */
+  command: string;
+}
+
+/**
+ * Helper that writes the reminder entry. The ADR §14 pattern: both
+ * the constant and the writer live with the producing rule. If a
+ * future observer needed to ALSO write this type, we'd move both into
+ * an observer file; here, the rule is the sole writer so the rule
+ * file owns it.
+ */
+export function markDescriptionReviewed(
+  ctx: PredicateContext,
+  payload: DescriptionReviewedPayload = { command: "" },
+): void {
+  ctx.appendEntry<DescriptionReviewedPayload>(
+    DESCRIPTION_REVIEWED_EVENT,
+    payload,
+  );
+}
+
+export const commitDescriptionCheck = {
+  name: "commit-description-check",
+  tool: "bash",
+  field: "command",
+  pattern: /^git\s+commit\b/,
+  when: {
+    happened: { event: DESCRIPTION_REVIEWED_EVENT, in: "agent_loop" },
+  },
+  reason:
+    "Re-read the commit description before committing. This reminder fires once per agent loop — your next commit in this loop will go through.",
+  noOverride: false,
+  writes: [DESCRIPTION_REVIEWED_EVENT],
+  onFire: (ctx) => {
+    markDescriptionReviewed(ctx, {
+      command: ctx.input.command ?? "",
+    });
+  },
+} as const satisfies Rule;

package/examples/work-item-plugin/src/rules/commit-requires-work-item.test.ts

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * Integration tests for `commit-requires-work-item`.
+ *
+ * Uses `loadHarness` + `expectBlocks` / `expectAllows` — same shape
+ * a real plugin's test would take. Builds a minimal config with just
+ * this rule + the `workItemFormat` predicate wired through a fake
+ * plugin. Keeps the test isolated from any upstream plugin behavior.
+ */
+
+import { describe, it } from "node:test";
+import type { Plugin } from "@cad0p/pi-steering";
+import { expectAllows, expectBlocks, loadHarness } from "@cad0p/pi-steering/testing";
+import { workItemFormat } from "../predicates/work-item-format.ts";
+import { commitRequiresWorkItem } from "./commit-requires-work-item.ts";
+
+/**
+ * Minimal test plugin registering the predicate. We could use the
+ * whole `work-item` plugin default export here, but wiring the single
+ * predicate keeps each rule test focused on its own behavior without
+ * pulling in unrelated observers / rules.
+ */
+const testPlugin: Plugin = {
+  name: "test",
+  predicates: { workItemFormat },
+};
+
+describe("commit-requires-work-item", () => {
+  const harness = loadHarness({
+    config: {
+      plugins: [testPlugin],
+      rules: [commitRequiresWorkItem],
+    },
+  });
+
+  it("blocks a commit missing the work-item tag", async () => {
+    await expectBlocks(
+      harness,
+      { command: 'git commit -m "feat: add thing"' },
+      { rule: "commit-requires-work-item" },
+    );
+  });
+
+  it("allows a commit containing [PROJ-N]", async () => {
+    await expectAllows(harness, {
+      command: 'git commit -m "feat: add thing [PROJ-42]"',
+    });
+  });
+
+  it("allows commits using --message long form", async () => {
+    await expectAllows(harness, {
+      command: 'git commit --message "fix [PROJ-1] bad thing"',
+    });
+  });
+
+  it('does NOT fire on git log --grep="commit"', async () => {
+    // Make sure the pattern doesn't spuriously match arbitrary
+    // commit-containing text.
+    await expectAllows(harness, {
+      command: 'git log --grep="commit"',
+    });
+  });
+
+  it("does NOT fire on `git commit` without -m (the rule's pattern requires -m)", async () => {
+    // The rule pattern anchors on `-m\s`, so this never even
+    // reaches the predicate.
+    await expectAllows(harness, { command: "git commit --amend" });
+  });
+
+  it("blocks a commit whose [PROJ- tag uses the wrong format", async () => {
+    await expectBlocks(
+      harness,
+      { command: 'git commit -m "feat [PROJXX] oops"' },
+      { rule: "commit-requires-work-item" },
+    );
+  });
+});

package/examples/work-item-plugin/src/rules/commit-requires-work-item.ts

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * `commit-requires-work-item` — example rule.
+ *
+ * Demonstrates:
+ *   - A plugin-registered predicate (`workItemFormat`) in use from a
+ *     rule's `when.*` slot.
+ *   - `when.not` for inversion — the predicate reports "the commit
+ *     message MATCHES `[PROJ-N]`" (positive), so we wrap it in `not`
+ *     to get "the message does NOT match" (the firing condition).
+ *   - The typed-arg authoring pattern — `{ pattern: /\[PROJ-\d+\]/ }`.
+ *   - A `pattern` anchored on the subcommand slot so `git log --grep
+ *     "commit"` doesn't spuriously match.
+ *
+ * Semantics:
+ *   - Fires on `git commit [...] -m <msg>` where `<msg>` does NOT
+ *     contain a `[PROJ-N]` token.
+ *   - The predicate's fallback path keeps us safe: if someone writes
+ *     a commit with no `-m` reachable (e.g. `git commit
+ *     --file /tmp/msg.txt`), the predicate falls back to
+ *     pattern-matching the whole command — which will miss, so
+ *     `not` makes this rule FIRE. That's the conservative default
+ *     for a plugin whose whole purpose is "require a ticket".
+ *
+ * Override: allowed (workflow rule, not inherent-destructive). The
+ * engine's default is `noOverride: true`; rule authors opt out
+ * explicitly.
+ */
+
+import type { Rule } from "@cad0p/pi-steering";
+
+export const commitRequiresWorkItem = {
+  name: "commit-requires-work-item",
+  tool: "bash",
+  field: "command",
+  // Anchored on `git commit` — the pre-subcommand flag slot (`git -C
+  // /other commit …`) is intentionally omitted to keep the example
+  // compact. The git plugin's `no-main-commit` rule in the package
+  // shows the full slot pattern for production use.
+  pattern: /^git\s+commit\b.*-m\s/,
+  when: {
+    // Invert the predicate: fire when the work-item tag is MISSING.
+    not: {
+      // The plugin-registered `workItemFormat` predicate — see
+      // ../predicates/work-item-format.ts. `[PROJ-N]` is the
+      // placeholder — a real adopter replaces with e.g.
+      // `[PROJECT-\d+]` / `[JIRA-\d+]`.
+      workItemFormat: { pattern: /\[PROJ-\d+\]/ },
+    },
+  },
+  reason:
+    "Commit messages must reference a work item ticket, e.g., [PROJ-123].",
+  noOverride: false,
+} as const satisfies Rule;

package/examples/work-item-plugin/src/rules/push-requires-tests.test.ts

@@ -0,0 +1,245 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * Integration tests for `push-requires-tests`.
+ *
+ * Exercises the observer → rule handoff end-to-end via `loadHarness`:
+ *
+ *   1. Push without a prior TEST_PASSED_EVENT entry → block.
+ *   2. Dispatch an `npm test` success event through the harness →
+ *      the observer writes TEST_PASSED_EVENT into the session entries.
+ *   3. Push in the same agent loop → allow.
+ *   4. Dispatch a `git pull` → observer writes RETEST_REQUIRED_EVENT,
+ *      stale-ing the test entry. Push now blocks again (PR §4 `since`).
+ *   5. Chain-aware: `npm test && git push` allowed pre-execution
+ *      because the prior `&&` ref matches the npm-test observer (PR §4).
+ *
+ * Step (2) uses `harness.dispatch` — the same call production uses on
+ * `tool_result`. `createRecordingHost` + `mockExtensionContext` share
+ * a single entries array so writes via `harness.dispatch` flow back
+ * into `harness.evaluate`'s view of the session.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { Plugin } from "@cad0p/pi-steering";
+import {
+  createRecordingHost,
+  expectAllows,
+  expectBlocks,
+  loadHarness,
+  mockExtensionContext,
+} from "@cad0p/pi-steering/testing";
+import {
+  npmTestTracker,
+  TEST_PASSED_EVENT,
+} from "../observers/npm-test-tracker.ts";
+import {
+  RETEST_REQUIRED_EVENT,
+  retestRequiredTracker,
+} from "../observers/retest-required-tracker.ts";
+import { pushRequiresTests } from "./push-requires-tests.ts";
+
+/**
+ * Plugin bundling the two observers this rule interacts with. Keeps
+ * the test config focused on what's under exercise — no unrelated
+ * rules from the work-item plugin.
+ */
+const testPlugin: Plugin = {
+  name: "test",
+  observers: [npmTestTracker, retestRequiredTracker],
+};
+
+describe("push-requires-tests", () => {
+  it("blocks git push when no TEST_PASSED entry exists", async () => {
+    const harness = loadHarness({
+      config: {
+        plugins: [testPlugin],
+        rules: [pushRequiresTests],
+      },
+    });
+    await expectBlocks(
+      harness,
+      { command: "git push origin feat/x" },
+      { rule: "push-requires-tests" },
+    );
+  });
+
+  it("does NOT fire on unrelated commands", async () => {
+    const harness = loadHarness({
+      config: {
+        plugins: [testPlugin],
+        rules: [pushRequiresTests],
+      },
+    });
+    await expectAllows(harness, { command: "git status" });
+  });
+
+  it("allows git push after observer records a TEST_PASSED entry", async () => {
+    // Recording host + shared ExtensionContext: writes via
+    // host.appendEntry (from the dispatcher) flow into
+    // ctx.sessionManager.getEntries so the later evaluate() sees
+    // the TEST_PASSED entry the observer recorded. Mirrors the
+    // bridge the real pi runtime builds in `src/index.ts`.
+    const host = createRecordingHost();
+    const ctx = mockExtensionContext("/tmp/test", host.entries);
+
+    const harness = loadHarness({
+      config: {
+        plugins: [testPlugin],
+        rules: [pushRequiresTests],
+      },
+      host,
+    });
+
+    // Simulate: pi emits a tool_result for a successful `npm test`.
+    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,
+      0,
+    );
+
+    // The observer should have written TEST_PASSED_EVENT.
+    assert.ok(
+      host.entries.some((e) => e.customType === TEST_PASSED_EVENT),
+      "observer did not record TEST_PASSED_EVENT",
+    );
+
+    // Now the push should be allowed — the rule's
+    // `when.happened` finds the entry in the current agent loop.
+    const result = await harness.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "tc2",
+        toolName: "bash",
+        input: { command: "git push origin feat/x" },
+      } as unknown as Parameters<typeof harness.evaluate>[0],
+      ctx,
+      0,
+    );
+    assert.equal(result, undefined);
+  });
+
+  it("re-blocks push after `git pull` stale-s the test entry (happened.since)", async () => {
+    // Demonstrates the PR #4 `since` invalidation sentinel. The
+    // rule is gated on `TEST_PASSED_EVENT` but `since: RETEST_REQUIRED_EVENT`
+    // means a later pull stale-s the test state.
+    const host = createRecordingHost();
+    const ctx = mockExtensionContext("/tmp/test", host.entries);
+
+    const harness = loadHarness({
+      config: {
+        plugins: [testPlugin],
+        rules: [pushRequiresTests],
+      },
+      host,
+    });
+
+    // 1. Tests pass.
+    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,
+      0,
+    );
+
+    // 2. Pull stale-s the test state.
+    await harness.dispatch(
+      {
+        type: "tool_result",
+        toolCallId: "tc2",
+        toolName: "bash",
+        input: { command: "git pull" },
+        content: [],
+        details: { exitCode: 0 },
+      } as unknown as Parameters<typeof harness.dispatch>[0],
+      ctx,
+      0,
+    );
+
+    assert.ok(
+      host.entries.some((e) => e.customType === RETEST_REQUIRED_EVENT),
+      "retest observer did not record RETEST_REQUIRED_EVENT",
+    );
+
+    // 3. Push blocked now — the most-recent TEST_PASSED_EVENT is
+    // older than the most-recent RETEST_REQUIRED_EVENT.
+    const result = await harness.evaluate(
+      {
+        type: "tool_call",
+        toolCallId: "tc3",
+        toolName: "bash",
+        input: { command: "git push origin feat/x" },
+      } as unknown as Parameters<typeof harness.evaluate>[0],
+      ctx,
+      0,
+    );
+    assert.ok(result && "block" in result, "post-pull push should block");
+  });
+
+  it("`&&`-chain: `npm test && git push` is allowed pre-execution", async () => {
+    // Demonstrates the PR #4 speculative allow. The
+    // evaluator runs BEFORE the chain executes, so the observer
+    // hasn't written TEST_PASSED_EVENT yet — but because the prior
+    // `&&` ref matches the npm-test observer's watch, the engine
+    // speculatively allows. Safe: if `npm test` fails, `&&` short-
+    // circuits and `git push` never runs.
+    const harness = loadHarness({
+      config: {
+        plugins: [testPlugin],
+        rules: [pushRequiresTests],
+      },
+    });
+    await expectAllows(harness, {
+      command: "npm test && git push origin feat/x",
+    });
+  });
+
+  it("`&&`-chain: `git push && npm test` is NOT allowed (push is first)", async () => {
+    // Order matters — the speculative allow looks at PRIOR && refs
+    // only. Here push is first, so there's no prior observer to
+    // cite; the rule fires normally.
+    const harness = loadHarness({
+      config: {
+        plugins: [testPlugin],
+        rules: [pushRequiresTests],
+      },
+    });
+    await expectBlocks(
+      harness,
+      { command: "git push origin feat/x && npm test" },
+      { rule: "push-requires-tests" },
+    );
+  });
+
+  it("`&&`-chain: `npm test ; git push` still blocks (`;` does not qualify)", async () => {
+    // Only `&&` predecessors qualify for speculative allow. A
+    // `;`-joined prior doesn't short-circuit, so granting the
+    // allow would be unsafe.
+    const harness = loadHarness({
+      config: {
+        plugins: [testPlugin],
+        rules: [pushRequiresTests],
+      },
+    });
+    await expectBlocks(
+      harness,
+      { command: "npm test ; git push origin feat/x" },
+      { rule: "push-requires-tests" },
+    );
+  });
+});