@cad0p/pi-steering 0.1.0

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

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * Work-item example plugin — canonical reference for pi-steering
+ * plugin authors (ADR §15).
+ *
+ * What this plugin demonstrates, file-by-file:
+ *
+ *   - `predicates/work-item-format.ts`
+ *       - `definePredicate<T>` for typed predicate-arg variance.
+ *       - Structured arg access via `input.args` (quote-aware).
+ *   - `observers/npm-test-tracker.ts`
+ *       - ADR §14 encapsulation convention: file exports the
+ *         `<EVENT>_EVENT` constant AND a `mark<Event>(ctx)` helper;
+ *         observer uses the helper.
+ *       - `writes` declaration threading through for
+ *         `defineConfig`'s compile-time type checking.
+ *   - `observers/retest-required-tracker.ts`
+ *       - Invalidation-sentinel pattern: observer writes
+ *         `RETEST_REQUIRED_EVENT` on `git pull`, which stale-s
+ *         prior `TEST_PASSED_EVENT` entries via `happened.since`.
+ *   - `rules/commit-requires-work-item.ts`
+ *       - Plugin-registered predicate consumption via `when.<key>`.
+ *       - `not:` inversion in a {@link TopLevelWhenClause}.
+ *   - `rules/push-requires-tests.ts`
+ *       - `when.happened: { in: "agent_loop" }` gating.
+ *       - Observer → rule coupling via the shared EVENT constants.
+ *       - Temporal invalidation via `happened.since`.
+ *       - Chain-aware speculative allow for `npm test && git push`.
+ *   - `rules/commit-description-check.ts`
+ *       - Self-marking rules with `onFire`.
+ *       - Constant + helper co-located with the rule when no
+ *         observer corresponds (ADR §14).
+ *
+ * Copy-adapt this layout. A real plugin likely ships more rules and
+ * possibly a tracker too — see `src/plugins/git/`
+ * for the tracker + tracker-extension pattern.
+ *
+ * ## Consuming this plugin
+ *
+ * ```ts
+ * import { defineConfig } from "@cad0p/pi-steering";
+ * import workItemPlugin from "@examples/work-item-plugin";
+ *
+ * export default defineConfig({
+ *   plugins: [workItemPlugin],
+ * });
+ * ```
+ */
+
+import type { Plugin, PredicateShape } from "@cad0p/pi-steering";
+import {
+  npmTestTracker,
+  TEST_PASSED_EVENT,
+} from "./observers/npm-test-tracker.ts";
+import {
+  RETEST_REQUIRED_EVENT,
+  retestRequiredTracker,
+} from "./observers/retest-required-tracker.ts";
+import type { WorkItemFormatArgs } from "./predicates/work-item-format.ts";
+import { workItemFormat } from "./predicates/work-item-format.ts";
+import {
+  commitDescriptionCheck,
+  DESCRIPTION_REVIEWED_EVENT,
+} from "./rules/commit-description-check.ts";
+import { commitRequiresWorkItem } from "./rules/commit-requires-work-item.ts";
+import { pushRequiresTests } from "./rules/push-requires-tests.ts";
+
+declare global {
+  /**
+   * Plugin author registers `workItemFormat:` so the engine's mapped
+   * type ({@link TopLevelWhenClause}) accepts it as a leaf-level key
+   * with a typed argument shape. Without this augmentation, rules in
+   * this plugin (or any consumer's rules) referencing `workItemFormat:`
+   * would fail typecheck against the strict registry-driven type.
+   *
+   * @see PredicateShape, PiSteeringPredicates in pi-steering's schema.
+   */
+  interface PiSteeringPredicates {
+    workItemFormat: PredicateShape<WorkItemFormatArgs>;
+  }
+}
+
+// Re-export the type constants so consumers (e.g. another plugin or
+// a user's custom rule) can gate on the same events without
+// rediscovering the literal strings.
+export { DESCRIPTION_REVIEWED_EVENT, RETEST_REQUIRED_EVENT, TEST_PASSED_EVENT };
+
+/**
+ * The plugin. `as const satisfies Plugin` preserves the literal
+ * `name: "work-item"` and the `writes` tuples from rules/observers
+ * so `defineConfig` can cross-reference `when.happened.event` usages
+ * against this plugin's declared writes. See the ADR §7 footgun
+ * about bare `: Plugin` annotations.
+ */
+const workItemPlugin = {
+  name: "work-item",
+  predicates: { workItemFormat },
+  rules: [commitRequiresWorkItem, pushRequiresTests, commitDescriptionCheck],
+  observers: [npmTestTracker, retestRequiredTracker],
+} as const satisfies Plugin;
+
+export default workItemPlugin;
+
+export {
+  markTestPassed,
+  npmTestTracker,
+} from "./observers/npm-test-tracker.ts";
+export {
+  markRetestRequired,
+  retestRequiredTracker,
+} from "./observers/retest-required-tracker.ts";
+// Named re-exports — pick-your-piece imports for authors who want
+// just one rule or the predicate.
+export { workItemFormat } from "./predicates/work-item-format.ts";
+export {
+  commitDescriptionCheck,
+  markDescriptionReviewed,
+} from "./rules/commit-description-check.ts";
+export { commitRequiresWorkItem } from "./rules/commit-requires-work-item.ts";
+export { pushRequiresTests } from "./rules/push-requires-tests.ts";

package/examples/work-item-plugin/src/observers/npm-test-tracker.test.ts

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * Unit tests for the `npm-test-tracker` observer.
+ *
+ * Exercises the watch-filter + write-on-match contract via
+ * `testObserver`, which captures `appendEntry` calls for inspection.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { testObserver } from "@cad0p/pi-steering/testing";
+import { npmTestTracker, TEST_PASSED_EVENT } from "./npm-test-tracker.ts";
+
+describe("npm-test-tracker observer", () => {
+  it("records a TEST_PASSED_EVENT entry on successful `npm test`", async () => {
+    const { entries, watchMatched } = await testObserver(npmTestTracker, {
+      toolName: "bash",
+      input: { command: "npm test" },
+      output: {},
+      exitCode: 0,
+    });
+
+    assert.equal(watchMatched, true);
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0]?.customType, TEST_PASSED_EVENT);
+    assert.deepEqual(entries[0]?.data, {
+      command: "npm test",
+      // The dispatcher auto-tags plain-object payloads with
+      // `_agentLoopIndex` — default mockObserverContext has index
+      // 0.
+      _agentLoopIndex: 0,
+    });
+  });
+
+  it("does NOT fire on a failed `npm test` (exitCode non-zero)", async () => {
+    const { entries, watchMatched } = await testObserver(npmTestTracker, {
+      toolName: "bash",
+      input: { command: "npm test" },
+      output: {},
+      exitCode: 1,
+    });
+    assert.equal(watchMatched, false);
+    assert.equal(entries.length, 0);
+  });
+
+  it("does NOT fire on an unrelated command", async () => {
+    const { entries, watchMatched } = await testObserver(npmTestTracker, {
+      toolName: "bash",
+      input: { command: "npm install" },
+      output: {},
+      exitCode: 0,
+    });
+    assert.equal(watchMatched, false);
+    assert.equal(entries.length, 0);
+  });
+
+  it("fires on `npm test -- --grep foo` (watch regex unanchored to suffix)", async () => {
+    const { entries, watchMatched } = await testObserver(npmTestTracker, {
+      toolName: "bash",
+      input: { command: "npm test -- --grep foo" },
+      output: {},
+      exitCode: 0,
+    });
+    assert.equal(watchMatched, true);
+    assert.equal(entries.length, 1);
+  });
+
+  it("records the original command in the payload", async () => {
+    const { entries } = await testObserver(npmTestTracker, {
+      toolName: "bash",
+      input: { command: "npm test -- --reporter dot" },
+      output: {},
+      exitCode: 0,
+    });
+    const data = entries[0]?.data as { command: string };
+    assert.equal(data.command, "npm test -- --reporter dot");
+  });
+
+  it("tags writes with the agent-loop index from ctx", async () => {
+    const { entries } = await testObserver(
+      npmTestTracker,
+      {
+        toolName: "bash",
+        input: { command: "npm test" },
+        output: {},
+        exitCode: 0,
+      },
+      { agentLoopIndex: 42 },
+    );
+    const data = entries[0]?.data as { _agentLoopIndex: number };
+    assert.equal(data._agentLoopIndex, 42);
+  });
+});

package/examples/work-item-plugin/src/observers/npm-test-tracker.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * `npm-test-tracker` — example observer.
+ *
+ * Watches `bash` tool_results where the command matches `/^npm test/`
+ * with `exitCode: "success"`. On match, records a `TEST_PASSED_EVENT`
+ * session entry so rules can later consult whether tests have passed
+ * this agent loop.
+ *
+ * ## What this file demonstrates (ADR §14)
+ *
+ * The canonical observer encapsulation convention — every observer
+ * file exports three things:
+ *
+ *   1. A `<EVENT>_EVENT` constant (the session-entry event type).
+ *   2. A `mark<Event>` helper that calls `ctx.appendEntry(<TYPE>)`
+ *      with the right shape.
+ *   3. The observer itself, using the helper.
+ *
+ * Rules that gate on this event import `TEST_PASSED_EVENT` (not the
+ * raw string) and/or call `markTestPassed` from their own `onFire`.
+ * The raw string literal lives in exactly one place — here — and
+ * downstream typos become compile errors.
+ */
+
+import type { Observer, ObserverContext, PredicateContext } from "@cad0p/pi-steering";
+
+/**
+ * Session-entry type written when `npm test` succeeds. Rules gate via
+ * `when: { happened: { event: TEST_PASSED_EVENT, in: "agent_loop" } }`.
+ */
+export const TEST_PASSED_EVENT = "example-npm-test-passed" as const;
+
+/**
+ * Typed shape for the payload we write. Observers that need richer
+ * state (e.g. the test command variant, time-stamp, etc.) extend this
+ * interface; keeping the write helper as the one-stop shape definition
+ * keeps rule authors reading just the observer file to understand the
+ * contract.
+ */
+export interface TestPassedPayload {
+  /** Which command variant passed. Handy for debugging / filtering. */
+  command: string;
+}
+
+/**
+ * Record a "tests passed" session entry. Callable from either an
+ * observer (`tool_result` hook) or a rule's `onFire` hook — both
+ * receive a ctx with `appendEntry`. The loose context type here keeps
+ * the helper reusable across both.
+ */
+export function markTestPassed(
+  ctx: ObserverContext | PredicateContext,
+  payload: TestPassedPayload = { command: "npm test" },
+): void {
+  ctx.appendEntry<TestPassedPayload>(TEST_PASSED_EVENT, payload);
+}
+
+/**
+ * The observer itself. `as const satisfies Observer` preserves the
+ * literal `name: "npm-test-tracker"` and the `writes` tuple so
+ * `defineConfig`'s compile-time cross-reference checking works —
+ * rules referencing `happened: { event: TEST_PASSED_EVENT }` get
+ * validated against this observer's declared writes.
+ *
+ * See ADR §7 (`writes` declarations) for the authoring-pattern
+ * footgun around bare `: Observer` annotations.
+ */
+export const npmTestTracker = {
+  name: "npm-test-tracker",
+  writes: [TEST_PASSED_EVENT],
+  watch: {
+    toolName: "bash",
+    inputMatches: { command: /^npm\s+test\b/ },
+    exitCode: "success",
+  },
+  onResult: (event, ctx) => {
+    // Pull the command out of the raw event for the payload. The
+    // watch filter already guaranteed we're on a bash event whose
+    // `input.command` matches our regex — the cast is safe.
+    const input = event.input as { command?: string } | undefined;
+    markTestPassed(ctx, {
+      command: input?.command ?? "npm test",
+    });
+  },
+} as const satisfies Observer;

package/examples/work-item-plugin/src/observers/retest-required-tracker.test.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * Unit tests for the `retest-required-tracker` observer.
+ *
+ * Mirrors the structure of `npm-test-tracker.test.ts` — exercises
+ * the watch-filter + write-on-match contract via `testObserver`.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { testObserver } from "@cad0p/pi-steering/testing";
+import {
+  RETEST_REQUIRED_EVENT,
+  retestRequiredTracker,
+} from "./retest-required-tracker.ts";
+
+describe("retest-required-tracker observer", () => {
+  it("records a RETEST_REQUIRED_EVENT entry on successful `git pull`", async () => {
+    const { entries, watchMatched } = await testObserver(
+      retestRequiredTracker,
+      {
+        toolName: "bash",
+        input: { command: "git pull" },
+        output: {},
+        exitCode: 0,
+      },
+    );
+
+    assert.equal(watchMatched, true);
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0]?.customType, RETEST_REQUIRED_EVENT);
+    assert.deepEqual(entries[0]?.data, {
+      command: "git pull",
+      _agentLoopIndex: 0,
+    });
+  });
+
+  it("does NOT fire on failed `git pull`", async () => {
+    const { entries, watchMatched } = await testObserver(
+      retestRequiredTracker,
+      {
+        toolName: "bash",
+        input: { command: "git pull" },
+        output: {},
+        exitCode: 1,
+      },
+    );
+    assert.equal(watchMatched, false);
+    assert.equal(entries.length, 0);
+  });
+
+  it("does NOT fire on unrelated commands", async () => {
+    const { entries, watchMatched } = await testObserver(
+      retestRequiredTracker,
+      {
+        toolName: "bash",
+        input: { command: "git push" },
+        output: {},
+        exitCode: 0,
+      },
+    );
+    assert.equal(watchMatched, false);
+    assert.equal(entries.length, 0);
+  });
+
+  it("fires on `git pull --rebase` (watch regex unanchored to suffix)", async () => {
+    const { entries, watchMatched } = await testObserver(
+      retestRequiredTracker,
+      {
+        toolName: "bash",
+        input: { command: "git pull --rebase" },
+        output: {},
+        exitCode: 0,
+      },
+    );
+    assert.equal(watchMatched, true);
+    assert.equal(entries.length, 1);
+  });
+});

package/examples/work-item-plugin/src/observers/retest-required-tracker.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * `retest-required-tracker` — invalidation observer for the `since`
+ * sentinel pattern.
+ *
+ * ## What this file demonstrates (commit-4 polish, ADR §5 `since`)
+ *
+ * Observers can write "invalidator" events whose presence stale-s an
+ * earlier satisfied `happened` clause:
+ *
+ *   - `npm-test-tracker`       writes `TEST_PASSED_EVENT` on `npm test`
+ *                               success.
+ *   - `retest-required-tracker` (this file) writes `RETEST_REQUIRED_EVENT`
+ *                               on `git pull` success \u2014 the workspace
+ *                               just changed; prior test state is stale.
+ *   - `push-requires-tests` gates via
+ *       `happened: { event: TEST_PASSED_EVENT, in: "agent_loop",
+ *                    since: RETEST_REQUIRED_EVENT }`
+ *     which fires when the most-recent `TEST_PASSED_EVENT` is older
+ *     than the most-recent `RETEST_REQUIRED_EVENT` (or the tests
+ *     never ran at all in this agent loop).
+ *
+ * Same encapsulation convention as `npm-test-tracker`: this file
+ * owns the `RETEST_REQUIRED_EVENT` constant + `markRetestRequired`
+ * helper + the observer, so `defineConfig` type-checks references
+ * from downstream rules.
+ */
+
+import type { Observer, ObserverContext, PredicateContext } from "@cad0p/pi-steering";
+
+/**
+ * Session-entry event written when `git pull` succeeds. Rules that
+ * previously satisfied `TEST_PASSED_EVENT` become stale relative to
+ * this event; `push-requires-tests` compares the two via
+ * `happened.since` to require a re-run after any pull.
+ */
+export const RETEST_REQUIRED_EVENT = "example-retest-required" as const;
+
+/**
+ * Payload shape. Minimal \u2014 we just need a presence marker with a
+ * timestamp (engine-attached via `findEntries`).
+ */
+export interface RetestRequiredPayload {
+  /** Which pull command triggered the invalidation. Debug-only. */
+  command: string;
+}
+
+/**
+ * Record a "retest required" session entry. Callable from an observer
+ * or a rule's `onFire` \u2014 both receive a ctx with `appendEntry`.
+ */
+export function markRetestRequired(
+  ctx: ObserverContext | PredicateContext,
+  payload: RetestRequiredPayload = { command: "git pull" },
+): void {
+  ctx.appendEntry<RetestRequiredPayload>(RETEST_REQUIRED_EVENT, payload);
+}
+
+/**
+ * The observer. `as const satisfies Observer` preserves the literal
+ * `writes` tuple so `defineConfig` threads `RETEST_REQUIRED_EVENT`
+ * into the `AllWrites` union \u2014 letting rules reference it from
+ * `when.happened.since` with a compile-time typo check.
+ */
+export const retestRequiredTracker = {
+  name: "retest-required-tracker",
+  writes: [RETEST_REQUIRED_EVENT],
+  watch: {
+    toolName: "bash",
+    inputMatches: { command: /^git\s+pull\b/ },
+    exitCode: "success",
+  },
+  onResult: (event, ctx) => {
+    const input = event.input as { command?: string } | undefined;
+    markRetestRequired(ctx, {
+      command: input?.command ?? "git pull",
+    });
+  },
+} as const satisfies Observer;

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

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: MIT
+// Part of the pi-steering work-item-plugin example.
+
+/**
+ * Unit tests for the `workItemFormat` predicate.
+ *
+ * Uses `testPredicate` from `@cad0p/pi-steering/testing` — the lightest
+ * possible way to exercise a predicate: construct a `PredicateContext`,
+ * call the handler, get the boolean verdict.
+ *
+ * We do NOT spin up a full harness here; `index.test.ts` covers the
+ * end-to-end path. Per-file unit tests focus on the one thing the file
+ * owns.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { Word } from "@cad0p/pi-steering";
+import { testPredicate } from "@cad0p/pi-steering/testing";
+import { workItemFormat } from "./work-item-format.ts";
+
+/**
+ * Tiny Word factory. Real Words carry `pos` / `end` / `parts` too, but
+ * the predicate only ever reads `.value`; omitting the rest keeps the
+ * test concise.
+ */
+function W(value: string): Word {
+  return { value, text: value, pos: 0, end: value.length } as Word;
+}
+
+describe("workItemFormat", () => {
+  it("matches when the -m value contains the pattern", async () => {
+    const fires = await testPredicate(
+      workItemFormat,
+      { pattern: /\[PROJ-\d+\]/ },
+      {
+        input: {
+          tool: "bash",
+          command: 'git commit -m "feat: [PROJ-42] subject"',
+          basename: "git",
+          args: [W("commit"), W("-m"), W("feat: [PROJ-42] subject")],
+        },
+      },
+    );
+    assert.equal(fires, true);
+  });
+
+  it("does NOT match when the -m value lacks the pattern", async () => {
+    const fires = await testPredicate(
+      workItemFormat,
+      { pattern: /\[PROJ-\d+\]/ },
+      {
+        input: {
+          tool: "bash",
+          command: 'git commit -m "feat: subject only"',
+          basename: "git",
+          args: [W("commit"), W("-m"), W("feat: subject only")],
+        },
+      },
+    );
+    assert.equal(fires, false);
+  });
+
+  it("supports the --message long form", async () => {
+    const fires = await testPredicate(
+      workItemFormat,
+      { pattern: /\[PROJ-\d+\]/ },
+      {
+        input: {
+          tool: "bash",
+          command: 'git commit --message "[PROJ-1] fix"',
+          basename: "git",
+          args: [W("commit"), W("--message"), W("[PROJ-1] fix")],
+        },
+      },
+    );
+    assert.equal(fires, true);
+  });
+
+  it("preserves quote-aware value through -m (no whitespace munging)", async () => {
+    // Real-world-ish: a message with internal spaces. The Word's
+    // .value gives us the unwrapped literal — we don't have to
+    // un-quote ourselves.
+    const fires = await testPredicate(
+      workItemFormat,
+      { pattern: /\[PROJ-\d+\]/ },
+      {
+        input: {
+          tool: "bash",
+          command:
+            'git commit -m "longer subject with spaces and [PROJ-7] mid-sentence"',
+          basename: "git",
+          args: [
+            W("commit"),
+            W("-m"),
+            W("longer subject with spaces and [PROJ-7] mid-sentence"),
+          ],
+        },
+      },
+    );
+    assert.equal(fires, true);
+  });
+
+  it("falls back to command string when no -m flag is found in args", async () => {
+    // Rule author wrote a `workItemFormat` predicate on a command
+    // whose args don't carry `-m` (e.g. `git commit` with no -m).
+    // Fallback matches against `input.command`.
+    const fires = await testPredicate(
+      workItemFormat,
+      { pattern: /\[PROJ-\d+\]/ },
+      {
+        input: {
+          tool: "bash",
+          command: "git commit",
+          basename: "git",
+          args: [W("commit")],
+        },
+      },
+    );
+    // No `-m`, and `"git commit"` has no PROJ token — does not fire.
+    assert.equal(fires, false);
+  });
+
+  it("returns false when args and command are both absent", async () => {
+    const fires = await testPredicate(
+      workItemFormat,
+      {
+        pattern: /\[PROJ-\d+\]/,
+      },
+      {
+        input: { tool: "bash" },
+      },
+    );
+    assert.equal(fires, false);
+  });
+
+  it("returns false when the arg shape is malformed", async () => {
+    // A rule author who passed a plain string instead of
+    // { pattern }. Fail-closed: predicate returns false rather than
+    // throwing.
+    const fires = await testPredicate(
+      workItemFormat,
+      // Intentionally wrong shape — widened via `as unknown` so the
+      // test isn't a type error (the predicate itself handles bad
+      // args defensively).
+      "not-an-object" as unknown as { pattern: RegExp },
+      {
+        input: {
+          tool: "bash",
+          command: 'git commit -m "[PROJ-1] x"',
+          args: [W("commit"), W("-m"), W("[PROJ-1] x")],
+        },
+      },
+    );
+    assert.equal(fires, false);
+  });
+});