pi-rules-md 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetalbolicX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# pi-rules-md
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pi extension that discovers markdown rule files and injects conditionally
+matched ones into the system prompt. Rules can activate when the agent touches
+files matching their globs, matching files exist in the project, a selected
+tool or model matches, prompt-derived intent satisfies its glob condition, or
+the rule is always active.
+
+Functional core / imperative shell; pure functions and data, no classes.
+
+## How it works
+
+1. **Discovery** — every turn, rule files are discovered from
+   `<project>/.pi/rules/**/*.md` (when the project is trusted) and
+   `~/.pi/agent/rules/**/*.md` (always), parsed with a strict schema, and
+   cached by mtime.
+2. **Matching** — each rule's activation is evaluated against the live
+   session: touched paths, existing files, selected tools, current model, and
+   prompt-derived intent.
+3. **Selection** — pinned rule bodies are content-deduped, budgeted, and
+   ordered for presentation. On-demand rules are listed by path instead of
+   having their bodies injected.
+4. **Injection** — the selected rules and on-demand index are rendered into a
+   single `pi-rules-md` system-prompt section via
+   `systemPromptOptions.sections` in `before_agent_start`. The section is
+   re-applied every turn while rules are active; identical content produces no
+   prompt diff, and the section is removed when nothing is active.
+
+The complete rule-file contract is specified in [RULE-SPEC.md](RULE-SPEC.md).
+
+## Quick start
+
+```markdown
+---
+description: Follow repo conventions when editing core sources.
+version: 1
+globs:
+  - "src/**/*.ts"
+  - "!src/**/*.test.ts"
+match: touched
+priority: 10
+---
+Use tabs, keep functions pure, and never introduce classes in src/.
+```
+
+Drop that file in `.pi/rules/` and start pi. When you edit any
+non-test `src/**/*.ts` file, the rule is injected into the system prompt
+for the session. Run `/rules` to see every rule, why each is active or
+inactive, what the budget dropped, and any parse errors.
+
+An `alwaysApply: true` rule skips matching entirely. `tools`, `branch`, and
+`model` conditions are AND-ed with the activation mode; absent conditions mean
+"any."
+
+## Pinned and on-demand rules
+
+Rules default to `load: pinned`: when active, their bodies are eligible for
+injection and count toward the token budget. Use pinned rules for concise
+guidance that should be available automatically whenever its conditions match.
+
+Use `load: on-demand` for long references, catalogs, or specialized material
+that should not be inserted into every prompt. A matched on-demand rule adds a
+path-and-description entry under the **Reference rules available on demand**
+index, not its body. The agent can fetch the full body with the `read_rule` tool
+using that rules-relative path. On-demand bodies bypass pinned deduplication
+and budgeting; the rendered index still contributes to the reported token
+estimate.
+
+```markdown
+---
+description: Database migration reference.
+version: 1
+globs:
+  - "docs/database/**/*.md"
+load: on-demand
+keywords: [migration, postgres]
+---
+Detailed migration procedures and reference material...
+```
+
+Use `keywords` when a useful rule should be discoverable from task wording
+that does not mention its file paths. A whole-word, case-insensitive keyword
+match in the current turn prompt donates that rule's positive globs to
+pre-loading. Keywords do not activate a rule by themselves, and donated globs
+do not count as touched paths or expand the filesystem scan. Language words
+also provide built-in intent globs (for example, `python` or `pytest` →
+`*.py`; bare `go` intentionally has no trigger). See [RULE-SPEC.md §5](RULE-SPEC.md#5-activation-semantics)
+for the full list and matching semantics.
+
+## Token budget
+
+Pinned rule bodies use an estimated token budget of 2000 by default. Override
+it for the Pi process with a positive integer value, for example:
+
+```sh
+PI_RULES_MAX_TOKENS=3000 pi
+```
+
+The shell parses the override with `parseInt`; a missing value, a value that
+parses to `NaN`, or a non-positive parsed value uses the default. On-demand
+bodies do not consume this budget; their rendered index contributes to the
+final token estimate.
+
+## Install
+
+Recommended: install the npm package through the CLI wrapper:
+
+```sh
+npx pi-rules-md install
+```
+
+The wrapper invokes the `pi` CLI for package changes; it never edits
+`settings.json` directly.
+
+| Command | Description |
+| --- | --- |
+| `pi-rules install` | Install pi-rules-md. |
+| `pi-rules uninstall` | Remove pi-rules-md. |
+| `pi-rules update` | Update an unpinned npm installation. |
+| `pi-rules status` | Show installation status and available updates. |
+| `pi-rules doctor` | Diagnose installation health. |
+
+Common options: `--local` uses project scope for install, uninstall, and
+update; `--purge` removes the package directory during uninstall; `--dry-run`
+prints actions without changing anything; `--agent-dir <dir>` selects a Pi
+agent directory.
+
+For local development, load the source directly:
+
+```sh
+pi --extension ./index.ts
+```
+
+For a local-path install, run `pnpm build` first; the package manifest loads
+`./dist/extension.js`. Source entries track the working tree; npm entries are
+updated with `pi-rules update`.
+
+## Commands
+
+- `/rules` — report of the last evaluation: active rules with reasons,
+  inactive rules with reasons, budget drops with cause, parse/discovery
+  errors, and the injected content hash.
+
+## Trust model
+
+Project rules (`.pi/rules/`) load only when the project is trusted
+(pi's `isProjectTrusted()`); global rules always load. An unlistable or
+unreadable rule source is reported via `/rules` and never breaks the
+session.
+
+## Development
+
+```sh
+pnpm install
+pnpm typecheck   # strict TS, no emit
+pnpm test        # vitest: co-located unit tests, goldens, property tests, perf guard
+```
+
+- Functional core: `src/` (types, frontmatter parser, conditions, match,
+  select, render, engine, state reducer) — pure, total, property-tested.
+- Imperative shell: `shell/` + `index.ts` (discovery, event collectors,
+  injection, wiring) — thin, dependency-injected, structurally mirrored
+  against the pi SDK types (no runtime pi import).
+- ODD feature tracking: [odd/tasks/pi-rules-md.md](odd/tasks/pi-rules-md.md).

package/RULE-SPEC.md

@@ -0,0 +1,191 @@
+# Rule Format v1.1 (RULE-SPEC)
+
+Normative specification for pi-rules-md rule files and runtime behavior.
+Frontmatter shape and value constraints are enforced by the parser
+(`src/frontmatter.ts`); the discovery, matching, selection, and rendering
+pipeline applies the remaining semantics.
+
+## 1. File placement and identity
+
+| Source | Directory | Loaded when |
+| --- | --- | --- |
+| Project rules | `<project>/.pi/rules/**/*.md` | the project is trusted (`ctx.isProjectTrusted()`) |
+| Global rules | `~/.pi/agent/rules/**/*.md` | always |
+
+- Discovery is recursive (`**/*.md`); non-`.md` files are ignored; VCS
+  internals (`.git/**`) and dependency trees (`node_modules/**`) are never
+  scanned.
+- **Rule id** = file stem, disambiguated across the whole merged pass:
+  on collision the first file in deterministic order (project before
+  global; sorted by path within each source) keeps the bare stem; later
+  collisions get `-2`, `-3`, … (e.g. project `a.md` → `a`, global
+  `a.md` → `a-2`).
+- Project rules come first; within a source, files are sorted by path.
+- An unlistable source (e.g. permission error) produces a
+  `source-unreadable` error entry for `/rules` and contributes no rules;
+  it never breaks the session. An unreadable file produces a
+  `read-failure` entry. A file that vanishes mid-scan is skipped
+  silently.
+
+## 2. Document shape
+
+A rule file is YAML frontmatter plus a markdown body:
+
+```markdown
+---
+description: One line explaining what the rule enforces.
+version: 1
+globs:
+  - "src/**/*.ts"
+  - "!src/**/*.test.ts"
+match: touched
+tools: [edit, write]
+branch: main
+model: sonnet
+priority: 10
+enforcement: enforce
+load: pinned
+keywords: [typescript, style]
+alwaysApply: false
+---
+The rule body: instructions injected verbatim into the system prompt
+section when the rule is active.
+```
+
+## 3. Keys
+
+| Key | Type | Required | Default | Meaning |
+| --- | --- | --- | --- | --- |
+| `description` | string | ✔ | — | Shown in `/rules`; never injected. |
+| `version` | number | ✔ | — | **Exactly `1`** (YAML integer `1`; `1.0` is rejected by strict equality). |
+| `globs` | string[] | see §4 | — | Glob patterns (OR semantics); `!`-prefixed entries are negations. |
+| `match` | `touched` \| `exists` \| `both` | ✘ | `both` | Activation mode (§5). |
+| `tools` | string[] | ✘ | — | Active only when the current tool selection intersects. |
+| `branch` | string | ✘ | — | Active only on this git branch (v1: no live branch source in pi; reserved). |
+| `model` | string | ✘ | — | Active only when the current model name matches. |
+| `priority` | integer | ✘ | `0` | Higher wins in selection; ties keep discovery order (stable). |
+| `enforcement` | `enforce` \| `recommend` \| `inform` | ✘ | `inform` | Parsed and validated; does NOT affect selection or rendering in v1 (reserved for future emphasis). |
+| `load` | `pinned` \| `on-demand` | ✘ | `pinned` | Loading policy metadata; materialized by parsing and does not itself alter condition matching. |
+| `keywords` | string[] | ✘ | — | Intent-donation metadata; trimmed on parse and does not itself gate matching. When a keyword matches a whole word in the current turn prompt (case-insensitive), this rule's positive globs are donated to intent pre-loading. Empty arrays are allowed. |
+| `alwaysApply` | boolean | ✘ | `false` | When true the rule bypasses ALL condition matching (still subject to the trust gate for project rules). |
+
+**Unknown keys are rejected** (strict schema). Types must match exactly
+(`globs` and `keywords` entries are strings; `load` is exactly `pinned` or
+`on-demand`; `priority` is an integer; `version` is the number `1`).
+
+## 4. Activation constraints
+
+A rule must declare at least one activation trigger: non-empty `globs`,
+non-empty `tools`, `branch`, `model`, or `alwaysApply: true`. Otherwise
+the parse fails with `no-activation-condition`.
+
+Special case: an explicit `match` key **requires** `globs`
+(`match-without-globs`) — implicit default `match` without globs is fine
+as long as another trigger exists.
+
+Glob entries are picomatch patterns evaluated against cwd-relative,
+`/`-separated, normalized paths. Positive patterns OR; negations
+(`!pattern`) apply per-rule: a path is a candidate when it matches ≥1
+positive pattern, then excluded if it matches any negation.
+
+## 5. Activation semantics
+
+- `touched` — active when an agent tool's pre-execution arguments name a path
+  matching the globs this session. Paths are captured from `tool_execution_start`
+  events; first occurrence wins, order preserved.
+- `exists` — active when any path matching the globs exists on disk
+  (checked via the scan seam each evaluation).
+- `both` — touched **OR** exists (the default).
+- Condition keys (`tools`, `branch`, `model`) are AND-ed on top of the
+  activation mode; absent means "any".
+- `alwaysApply: true` skips activation and conditions entirely.
+- Before evaluation, the current turn prompt is checked for whole-word, case-insensitive language names: python/pytest → `*.py`, rust → `*.rs`, typescript → `*.ts`, javascript → `*.js`, golang → `*.go`, kotlin → `*.kt`, java → `*.java`, csharp → `*.cs`, ruby → `*.rb`. There is intentionally no bare `go` language trigger.
+- The current turn prompt is also checked for whole-word, case-insensitive matches against each rule's `keywords`; a hit donates that rule's positive globs to the intent set. Keyword metadata does not activate the rule by itself. Intent globs can satisfy a rule's `globs` condition independently of touched/existing path matches, but do not bypass other conditions.
+- **Intent globs never enter the context path pool** (`touchedPaths` or `existingPaths`) and do not expand the filesystem scan. They are a separate input to the globs-condition check.
+
+### Pre-execution path capture
+
+`tool_execution_start` is observed before tool execution. The event's `args` are
+untrusted; missing, malformed, non-object, or non-string path arguments and
+unknown tools are ignored. Recognized paths are normalized and deduplicated by
+the session-state reducer.
+
+| Pi built-in | Captured argument | Behavior |
+| --- | --- | --- |
+| `read`, `edit`, `write` | `path` | Captured as a file path. |
+| `grep` | optional `path` | Captured as the search scope when present. |
+| `find` | optional `path` | Captured as the glob-search scope when present. |
+| `bash` | none | No capture: Pi's schema has only `command` and `timeout`. |
+
+These keys are verified against the installed Pi schemas in
+`dist/core/tools/{read,edit,write,grep,find,bash}.js`. Unlike OpenCode, Pi's
+bash tool has no `workdir` argument. This is a deliberate runtime divergence:
+we do not parse paths from shell command strings.
+
+## 6. Selection, budget, rendering
+
+- Every discovered rule receives a monotonic `index` in discovery order:
+  project rules first, then global rules, retaining each source's order.
+- Content-level dedupe: rules with byte-identical full content are
+  deduplicated; higher `priority` wins, and equal priorities keep the later
+  discovery `index`. Losers are dropped with cause `duplicate`. This
+  supersedes v1's first-occurrence-wins behavior.
+- Budget candidates are considered by `priority` DESC, then `index` ASC.
+  Greedy fill admits each candidate that fits and skips a non-fitting rule
+  while continuing to later candidates. If candidates exist, the first is
+  always kept even when it exceeds the budget; this supersedes v1's stop-at-
+  first-non-fit behavior.
+- After budget selection, presentation order is unconditional rules first
+  (`alwaysApply: true` or no declared activation conditions), then
+  `priority` DESC, then `index` ASC.
+- Token budget defaults to 2000 estimated tokens (`ceil(chars/4)` of each
+  pinned rule body's content). The shell parses `PI_RULES_MAX_TOKENS` with
+  `parseInt`; an absent value, a value that parses to `NaN`, or a non-positive
+  parsed value uses the default. A positive parsed integer overrides it.
+- On-demand rules bypass pinned-rule dedupe and budget selection. Their bodies
+  are never injected or counted against that budget. Instead, the rendered
+  section appends an index headed exactly
+  `## Reference rules available on demand`, with one `- <rules-relative-path>
+  — <description> (fetch with the read_rule tool)` line per rule. No index is
+  rendered when no on-demand rule
+  matched. Each rule's `relativePath` is a POSIX path relative to its source's
+  rules root, never an absolute path.
+- `read_rule` looks up a discovered rule by exact `relativePath` and returns
+  its parsed `content` body directly; it performs no filesystem read. Absolute
+  paths (POSIX or Windows) and any name containing a `..` segment, as well as
+  unknown names, return `Unknown rule: <name>`. The FROZEN tool description is:
+  `Fetch the full content of a reference rule by its rules-relative path. Use
+  when a "Reference rules available on demand" index entry is relevant to the
+  current task.`
+- The evaluation trace partitions matched rules into pinned `active` and
+  `onDemand`, reports all matched rule file paths (including on-demand paths),
+  and estimates tokens over the complete rendered block including its index.
+- Rendered as one `pi-rules-md` system-prompt section: `# Rules` header,
+  framing line, one entry per selected pinned rule (`## <description>`), optional
+  `> Triggered by: <reasons>` when reasons exist, and `---` separators.
+  Pinned rule bodies are injected verbatim with trailing blank-line
+  normalization; the section ends with exactly one trailing newline.
+- The section is re-applied on **every** agent turn while any pinned or
+  on-demand rule is active (Pi rebuilds its prompt sections per turn); identical
+  content produces no prompt diff (zero churn). When no rule is active and one
+  was previously injected, the section is removed.
+
+### v1 behavior superseded by v1.1
+
+- Equal-content pinned rules no longer keep the first occurrence: the higher
+  priority wins, with the later discovery index breaking priority ties.
+- Budget selection no longer stops at the first non-fitting candidate. It skips
+  that candidate and continues; the first priority-sorted candidate is retained
+  even when it exceeds the budget.
+- The pinned entry heading is `## <description>` (not `## <id>`), matching the
+  renderer and its contract tests.
+
+## 7. Errors (visible via `/rules`)
+
+Parse and discovery errors never break the session; they are collected
+and reported: `yaml-syntax`, `missing-frontmatter`, `unknown-key`,
+`invalid-version`, `missing-description`, `invalid-value` (field type),
+`match-without-globs`, `no-activation-condition`, `read-failure`,
+`source-unreadable`. Error entries carry the offending file (or
+directory for `source-unreadable`) and are reused from the mtime cache
+while the file is unchanged.