@cad0p/pi-steering 0.1.0

package/src/plugins/git/README.md

@@ -0,0 +1,485 @@
+# pi-steering/plugins/git
+
+Git plugin for [pi-steering](../../../README.md) — branch
+awareness, upstream checks, and git-specific cwd tracking on top of
+the core steering engine.
+
+> **Opt-in since the v0.1.x monorepo split.** This plugin is NOT
+> registered automatically: `DEFAULT_PLUGINS` is empty. Declare it via
+> `plugins: [gitPlugin]` (import from `pi-steering/plugins/git`) to get
+> the predicates, rules, tracker, and cwd extensions — see
+> [Usage](#usage) below.
+
+## What it ships
+
+| Surface | Names | Purpose |
+|---|---|---|
+| Predicates | `branch`, `upstream`, `commitsAhead`, `hasStagedChanges`, `isClean`, `remote` | New `when.<key>` slots for rules |
+| Rules | `no-main-commit`, `no-main-commit-github` | Block direct commits to protected branches; the `-github` variant emits PR-flow guidance on github.com clones |
+| Trackers | `branch` | Walker-threaded branch state (`git checkout X` advances) |
+| Tracker extensions | `cwd.git` | `--git-dir=` / `--work-tree=` flag parsing on top of the built-in cwd tracker |
+
+## Usage
+
+```ts
+// .pi/steering.ts
+import { defineConfig } from "@cad0p/pi-steering";
+import gitPlugin from "@cad0p/pi-steering/plugins/git";
+
+export default defineConfig({
+  // The plugin is opt-in: declaring it registers it at runtime AND
+  // feeds its rule / predicate names into defineConfig's type unions
+  // (typo-checking on disabledRules / disabledPlugins).
+  plugins: [gitPlugin],
+  rules: [
+    // Custom rule layered on top of the plugin's predicates:
+    {
+      name: "no-push-when-dirty",
+      tool: "bash",
+      field: "command",
+      pattern: "^git\\s+push\\b",
+      when: { isClean: false },
+      reason: "Stash or commit your working changes before pushing.",
+    },
+  ],
+});
+```
+
+Explicit import still works (e.g. in tests driving `loadHarness`
+with `includeDefaults: false`):
+
+```ts
+import { defineConfig } from "@cad0p/pi-steering";
+import gitPlugin from "@cad0p/pi-steering/plugins/git";
+
+export default defineConfig({
+  plugins: [gitPlugin],
+  rules: [...],
+});
+```
+
+### Disabling
+
+Disabling snippets declare `plugins: [gitPlugin]` first — that's what
+feeds the rule / plugin names into `defineConfig`'s generics for
+typo-checking. (Since the monorepo split, `DEFAULT_PLUGINS` is empty:
+there is no default registration to lean on, and disabling an
+undeclared plugin is a compile error.)
+
+Keep the predicates + tracker, drop the shipped rule:
+
+```ts
+import { defineConfig } from "@cad0p/pi-steering";
+import gitPlugin from "@cad0p/pi-steering/plugins/git";
+
+export default defineConfig({
+  plugins: [gitPlugin],
+  disabledRules: ["no-main-commit"],
+});
+```
+
+Drop the whole git plugin (no `branch` / `upstream` / ... predicates,
+no tracker, no cwd extensions, no rule):
+
+```ts
+import { defineConfig } from "@cad0p/pi-steering";
+import gitPlugin from "@cad0p/pi-steering/plugins/git";
+
+export default defineConfig({
+  plugins: [gitPlugin],
+  disabledPlugins: ["git"],
+});
+```
+
+Drop EVERYTHING shipped — `DEFAULT_RULES` (and whatever plugins
+you declared):
+
+```ts
+import { defineConfig } from "@cad0p/pi-steering";
+
+export default defineConfig({
+  disableDefaults: true,
+});
+```
+
+## Predicate reference
+
+### `branch`
+
+Match the current git branch.
+
+```ts
+when: { branch: /^main$/ }
+when: { branch: "^feat-" }                             // string = regex source
+when: { branch: { pattern: /^main$/, onUnknown: "allow" } }
+```
+
+Resolution is a three-way discrimination on what the branch tracker
+knows about the current `tool_call` chain:
+
+1. **value** — the tracker observed an in-chain `git checkout <X>` /
+   `git switch <X>` with a statically-resolvable target. Match the
+   pattern against `X`. This is what makes
+   `git checkout main && git commit` evaluate against `main`, not
+   the pre-chain branch.
+2. **unknown** — the tracker observed a checkout but couldn't
+   resolve the target (e.g. `git checkout $VAR`). Apply `onUnknown`
+   policy WITHOUT shelling out: `git branch --show-current` here
+   would return the PRE-checkout branch and silently defeat the
+   walker — exactly the case the tracker exists to catch.
+3. **missing** — no branch-changing command fired in the current
+   chain. Shell out via `git branch --show-current` in `ctx.cwd`;
+   the shell's current state is the answer the predicate wants.
+
+`onUnknown` defaults to `"block"` (fail-closed) — if the branch
+can't be determined (dynamic checkout, exec failure, detached HEAD
+in the missing case), the predicate reports "match" so the rule
+still fires.
+
+### `upstream`
+
+Match the current branch's configured upstream (`git rev-parse
+--abbrev-ref @{upstream}`). Same shape as `branch`, no tracker today.
+
+```ts
+when: { upstream: /^origin\/main$/ }
+when: { upstream: { pattern: "^origin/", onUnknown: "allow" } }
+```
+
+### `commitsAhead`
+
+Match the count of commits ahead of a revision (default
+`@{upstream}`).
+
+```ts
+when: { commitsAhead: { eq: 1 } }                       // exactly one
+when: { commitsAhead: { gt: 0 } }                       // at least one
+when: { commitsAhead: { gt: 0, lt: 5 } }                // 1..4
+when: { commitsAhead: { wrt: "origin/main", eq: 1 } }
+```
+
+At least one of `eq` / `gt` / `lt` must be specified. Returns
+`false` (rule skips) on exec failure or non-numeric output — pair
+with `upstream` for fail-closed behavior.
+
+### `hasStagedChanges` / `isClean`
+
+Boolean predicates.
+
+```ts
+when: { hasStagedChanges: true }   // staged changes exist
+when: { hasStagedChanges: false }  // no staged changes
+when: { isClean: true }            // working tree clean
+when: { isClean: false }           // working tree dirty
+```
+
+Returns `false` on exec failure. Layer with `upstream` if you need
+fail-closed behavior.
+
+### `remote`
+
+Match the `origin` remote URL. Same shape as `branch`.
+
+```ts
+when: { remote: /github\.com:org\// }
+when: { remote: { pattern: /production/, onUnknown: "block" } }
+```
+
+## Shipped rules
+
+### `no-main-commit`
+
+Blocks direct commits to protected branches (`main`, `master`,
+`mainline`, `trunk`).
+
+```ts
+{
+  name: "no-main-commit",
+  tool: "bash",
+  field: "command",
+  pattern: GIT_COMMIT_PATTERN,
+  when: { branch: PROTECTED_BRANCH_PATTERN },
+  reason: "Don't commit directly to a protected branch...",
+  noOverride: false,
+}
+```
+
+Overridable via `# steering-override: no-main-commit — <reason>` on
+the bash command. Catches `git -C /path commit`, `sh -c 'git
+commit'`, and — thanks to the branch tracker — `git checkout main
+&& git commit`.
+
+The pattern is shared with `no-main-commit-github` via the
+exported `GIT_COMMIT_PATTERN` constant in `rules.ts` (re-exported
+from `pi-steering/plugins/git`), so a regex change to one rule is
+physically forced onto the other (a unit test pins each rule's
+`pattern` field against the constant by value).
+
+The protected-branch list is likewise shared via the exported
+`PROTECTED_BRANCH_PATTERN` constant (also re-exported from
+`pi-steering/plugins/git`). Because it's a `RegExp` (object)
+constant rather than a string source, the pinning test uses
+shared-reference identity (`when.branch === PROTECTED_BRANCH_PATTERN`),
+which also catches future re-inlining of the same bytes — a stricter
+guarantee than the byte-equality pin on `pattern`. Adding a
+vendor-specific default-branch alias is a one-line edit at the
+constant; both rules pick it up.
+
+### `no-main-commit-github`
+
+Specialization of `no-main-commit` for github.com clones. Same
+pattern + protected-branch list, plus a `remote: /github\.com[/:]/`
+clause; the reason text emits PR-flow guidance (`gh pr merge`)
+instead of the generic feature-branch reminder, plus a safety
+reminder against unsolicited PR merges or ready-for-review flips.
+
+```ts
+{
+  name: "no-main-commit-github",
+  tool: "bash",
+  field: "command",
+  pattern: GIT_COMMIT_PATTERN, // shared with no-main-commit
+  when: {
+    branch: PROTECTED_BRANCH_PATTERN, // shared with no-main-commit
+    remote: /github\.com[/:]/,
+  },
+  reason: (ctx) => /* multi-paragraph PR-flow + safety guidance */,
+  noOverride: false,
+}
+```
+
+**First-match-wins ordering is load-bearing.**
+`no-main-commit-github` is registered BEFORE `no-main-commit` in
+the plugin's rule array. On a github clone + on main, both rules'
+`when:` clauses match — first-match-wins routes the
+github-flavored guidance to github users. On non-github contexts
+(Brazil packages, vault paths, /tmp scratch repos with non-github
+remotes) the github rule's `remote:` predicate doesn't match → the
+engine falls through to the generic `no-main-commit`. A unit test
+pins this position so reordering for stylistic reasons trips the
+suite.
+
+Under walker-unknown cwd (`cd "$VAR" && git commit`), the rule
+still fires fail-closed — but the reason text switches to the
+standard `walkerUnknownCwdReason` message instead of claiming
+github-specific context the engine couldn't verify.
+
+## Customization
+
+Three escape valves of increasing scope, ordered most → least
+common. None of these are exemption-by-cwd patterns — see the
+[Cwd-based exemption](#cwd-based-exemption-advanced) advanced
+section below for that case (it has subtle
+walker-unknown-cwd interactions you need to handle explicitly).
+
+```ts
+// 1. Swap the github rule's PR-flow guidance for the generic
+//    feature-branch reminder (keep blocking direct commits to
+//    main, just drop the github-specific message). The generic
+//    `no-main-commit` is still active and fires on a github clone
+//    + main; disabling the github specialization makes the engine
+//    emit the generic message instead.
+import { defineConfig } from "@cad0p/pi-steering";
+import gitPlugin from "@cad0p/pi-steering/plugins/git";
+
+export default defineConfig({
+  plugins: [gitPlugin],
+  disabledRules: ["no-main-commit-github"],
+});
+```
+
+```ts
+// 2. Disable + replace with a freshly-named user rule whose
+//    `reason` text points your agents at an internal skill /
+//    runbook. Spread the original to inherit `pattern`, `when:`,
+//    `tool`, `field`, and `noOverride` — only override the field
+//    you actually want to change. No `when:` changes → no
+//    walker-unknown-cwd interactions to reason about.
+import { defineConfig } from "@cad0p/pi-steering";
+import gitPlugin, { noMainCommitGithub } from "@cad0p/pi-steering/plugins/git";
+import type { Rule } from "@cad0p/pi-steering";
+
+const myNoMainCommitGithub = {
+  ...noMainCommitGithub,
+  // FRESH name — see warning below; reusing the original name has
+  // two failure modes, both bad.
+  name: "myorg-no-main-commit-github",
+  reason:
+    "You're on a github clone's protected branch. " +
+    "Open a PR for review (`gh pr create`); land via `gh pr merge` " +
+    "after approval. See skill `git-discipline@myorg` for our team's " +
+    "PR conventions.\n\n" +
+    "Safety: NEVER merge a PR or mark it ready-for-review unless " +
+    "the user explicitly asks. Wait for explicit user instruction.",
+} as const satisfies Rule;
+
+export default defineConfig({
+  plugins: [gitPlugin],                     // typo-checks the disable below
+  disabledRules: ["no-main-commit-github"], // drop the default
+  rules: [myNoMainCommitGithub],            // replacement on
+});
+```
+
+```ts
+// 3. Disable the entire git plugin (drops all gitPlugin
+//    predicates / rules / trackers / extensions):
+import { defineConfig } from "@cad0p/pi-steering";
+import gitPlugin from "@cad0p/pi-steering/plugins/git";
+
+export default defineConfig({
+  plugins: [gitPlugin],
+  disabledPlugins: ["git"],
+});
+```
+
+### ⚠️ Always use a fresh name when extending or replacing a plugin rule
+
+pi-steering composes user rules and plugin rules as
+`[...userRules, ...pluginRules]` with **no name dedup at the
+user/plugin layer.** Reusing the plugin rule's name in your config
+has two failure modes, **both bad**, depending on whether you also
+use `disabledRules`:
+
+1. **Same name + NO `disabledRules`** → BOTH rules are kept. The
+   plugin rule fires alongside your customized version, so paths
+   you intended to exempt still get the original message. The
+   customization silently fails to apply.
+
+2. **Same name + `disabledRules: ["original-name"]`** → the
+   `disabledRules` filter applies to ALL rules with that name
+   across both the user-config and plugin-rule sources. NEITHER
+   rule fires. Silent fail-OPEN — the worst outcome for a safety
+   rule, since the agent now has no guardrail at all.
+
+Use a fresh name (e.g., `myorg-no-main-commit-github`). Pair it
+with `disabledRules: ["no-main-commit-github"]` so the original is
+dropped and your fresh-named replacement survives the disable
+filter.
+
+### Cwd-based exemption (advanced)
+
+A common request: "don't block commits to main inside my vault
+directory" (vault flows like napkin-distill commit to a `main`
+branch by design). Cwd-based exemptions need care because:
+
+**The generic `no-main-commit` still fires on vault paths.**
+Disabling only the github specialization isn't enough — the
+generic rule's `when:` is just `{ branch: ... }` (no `remote:`
+gate), so it fires on any github clone or any other repo whose
+branch is one of the protected names. To actually exempt a path
+you need to disable BOTH shipped rules and register a
+user-authored rule.
+
+Worked example:
+
+```ts
+import { defineConfig } from "@cad0p/pi-steering";
+import gitPlugin, { noMainCommit } from "@cad0p/pi-steering/plugins/git";
+import type { Pattern, Rule } from "@cad0p/pi-steering";
+
+const VAULT_DIRS: Pattern[] = [
+  /\/Goldmine\//,
+  /\/\.cache\/napkin-distill\//,
+];
+
+const noMainCommitExceptVault = {
+  ...noMainCommit,
+  name: "myorg-no-main-commit-except-vault",
+  when: {
+    ...noMainCommit.when,
+    // Bare `not: { cwd: VAULT_DIRS }` is fail-CLOSED under
+    // walker-unknown cwd via the not-block's default block-level
+    // `onUnknown: "block"` modifier (see Walker-unknown cwd
+    // below). The inner `cwd:` predicate produces an `"unknown"`
+    // verdict, the not-block projects it to `false`, the outer
+    // rule fires — a `cd "$VAR" && git commit` is blocked rather
+    // than slipping past.
+    not: { cwd: VAULT_DIRS },
+  },
+} as const satisfies Rule;
+
+export default defineConfig({
+  plugins: [gitPlugin],                     // typo-checks the disables below
+  // BOTH shipped rules disabled; otherwise the generic
+  // `no-main-commit` fires on vault paths and the carve-out
+  // doesn't deliver on its name.
+  disabledRules: ["no-main-commit-github", "no-main-commit"],
+  rules: [noMainCommitExceptVault],
+});
+```
+
+### Walker-unknown cwd
+
+When the walker can't statically resolve cwd (e.g.
+`cd "$VAR" && git commit`), the inner `cwd:` predicate returns
+`"unknown"` and the not-block applies its block-level
+`onUnknown:` modifier (default `"block"`) to project the verdict.
+Default `"block"` means the not-block evaluates to `false`, the
+outer rule's `not:` flips to `true`, and the rule fires —
+fail-CLOSED. Authors who want walker-unknown vault paths to skip
+the rule (fail-OPEN exemption) opt in with the block-level
+modifier:
+
+```ts
+not: { cwd: VAULT_DIRS, onUnknown: "allow" }
+```
+
+The full truth table for `not: { cwd: ... }` under walker-known
+vs walker-unknown cwd lives in the
+[`dynamic-reason-runtime-cwd` example README][cwd-truth-table].
+
+[cwd-truth-table]: ../../../examples/dynamic-reason-runtime-cwd/README.md
+
+The `Pattern[]` annotation on `VAULT_DIRS` lets you mix string
+patterns and RegExp without TS narrowing the array's element type
+to `RegExp[]`. Annotation is optional for all-RegExp arrays (TS
+infers `RegExp[]`, a subtype of `Pattern[]`); explicit `Pattern[]`
+becomes load-bearing only when mixing strings and RegExp.
+
+## Authoring new plugins
+
+This directory is the canonical reference for plugin authors. The
+file layout separates concerns:
+
+- `branch-tracker.ts` — walker state modifier (one file per tracker).
+- `cwd-extensions.ts` — modifiers layering onto existing trackers.
+- `predicates.ts` — one handler per `when.<key>` slot.
+- `rules.ts` — rule definitions consuming the above.
+- `index.ts` — default export assembling the plugin.
+
+Each file has its own test suite; `integration.test.ts` pins end-to-
+end wiring through `resolvePlugins` and `buildEvaluator`. Copy-adapt
+this layout for your own plugin.
+
+### Composable building blocks
+
+Several pieces are re-exported from `pi-steering/plugins/git` so
+downstream plugins can reuse the engine's walker conventions
+without reimplementing them:
+
+- `walkerString(ctx, key, initialSentinel)` / `WalkerStringResult` —
+  narrows the walker-tracker value read off `ctx.walkerState[key]`
+  into one of `{ kind: "value"; value }` | `{ kind: "unknown" }` |
+  `{ kind: "missing" }`. The three-way discrimination is what the
+  `branch` predicate uses to dispatch on tracker state without
+  string-comparison sentinel checks.
+- `NO_CHECKOUT_IN_CHAIN` — the branch tracker's fall-through
+  sentinel for chains where no in-chain `git checkout` /
+  `git switch` fired. Plugin authors who consume tracker state
+  directly can match this sentinel to know they need to fall back
+  to a shell-out (vs. `"unknown"`, where the tracker observed an
+  unresolvable checkout).
+- `GIT_COMMIT_PATTERN` — the bash-command regex source matching
+  `git commit` (with optional pre-subcommand flag slots). Reuse
+  in plugin rules that want to share applicability with the
+  shipped commit-on-main rules.
+
+Example import:
+
+```ts
+import {
+  walkerString,
+  NO_CHECKOUT_IN_CHAIN,
+  GIT_COMMIT_PATTERN,
+} from "@cad0p/pi-steering/plugins/git";
+```