@nklisch/pi-enhanced 0.1.0

package/node_modules/@nklisch/pi-clearance/docs/REFERENCE_PATTERNS.md

@@ -0,0 +1,335 @@
+# REFERENCE PATTERNS — Pi Clearance
+
+## Purpose statement
+
+This document is the durable bridge from two reference sources into the clean
+pi-clearance product:
+
+- the local `pi-config` clearance proof of concept; and
+- the old fork-shaped permission-system scaffold currently being retired.
+
+These sources are **command-pattern, fixture-vocabulary, package-shape, and
+tune-report inspiration only**. They are not runtime architecture for
+pi-clearance. The product remains a clean configurable Pi clearance built around
+parsed command shapes, composable rule packs, approved policy growth, and optional review
+fallback. It is not a maintained permission-system fork.
+
+The durable translation rule is: capture reference intent as fixtures and prose, then
+implement future behavior through this repo's parsed `BashCommandShape`, policy DSL, rule
+packs, fixture harness, replay validation, and user-approved policy growth. Raw
+full-command regexes, hand-rolled tokenizers, shell splitters, wildcard permission maps,
+permission-session machinery, and POC classifier helper implementations are not runtime
+building blocks for this project.
+
+## Captured fixture vocabulary and destinations
+
+Captured command rows normalize to this JSON-compatible fixture vocabulary:
+
+```json
+{ "command": "<shell string>", "expected": "fast_path|review|hard_block", "reason": "<short prose>" }
+```
+
+Rules for this vocabulary:
+
+- `command` is the exact shell string under evaluation. It may contain real newlines,
+  quoted operators, redirects, substitutions, chains, pipelines, semicolon-separated
+  blocks, or path tricks because those structures are the behavior under test.
+- `expected` is one of exactly three captured labels:
+  - `fast_path` — the reference expected deterministic allow-through.
+  - `review` — the reference expected human/model review rather than automatic allow.
+  - `hard_block` — the reference expected deterministic denial for a catastrophic or
+    sealed-floor-like case.
+- `reason` is short human prose explaining the structural lesson.
+- Fixture JSON is a top-level array and contains no provenance fields, comments, or extra
+  keys. Provenance belongs in sibling files, not inside the corpus rows.
+
+Reference-capture destinations:
+
+- `test/fixtures/corpus/pi-config-classifier.json` — verbatim frozen POC classifier corpus
+  using the shape above.
+- `test/fixtures/corpus/pi-config-classifier.README.md` — provenance and license note for
+  the frozen POC corpus.
+- `test/fixtures/corpus/fork-derived.json` — curated old-fork command-shape cases using
+  the same vocabulary.
+
+Downstream fixture harnesses may map `fast_path` to `allow`, `review` to `review`, and
+`hard_block` to `deny`, but this capture layer does not define the final interpreter.
+
+## Source inventory
+
+These paths describe where the lessons came from on the capture machine. They are
+provenance pointers, not load-bearing instructions for future agents; the sections below
+are self-sufficient even after the local POC tree or fork-shaped files are deleted.
+
+| Source | Local path | Remote | Commit | Provenance / license note | Captured use |
+|---|---|---|---|---|---|
+| POC classifier corpus | `../pi-config/tests/fixtures/clearance-classifier-policy.json` | `git@github.com:nklisch/pi-config.git` | `ddf3a60641cbbb1e5761865f6bca702b19a5267b` | Owner: nklisch. `../pi-config` has no LICENSE file or package metadata at the captured commit; no license is invented here. This copy is reference material and defers to owner-supplied license text. | Verbatim fixture-vocabulary anchor copied to `test/fixtures/corpus/pi-config-classifier.json`. |
+| POC runtime reference | `../pi-config/pi/extensions/clearance.ts` | `git@github.com:nklisch/pi-config.git` | `ddf3a60641cbbb1e5761865f6bca702b19a5267b` | Same no-license/provenance note as the POC corpus. Read-only reference only. | Command-family intent, risky-behavior names, compound-command guard rationale, local-tool approvals, and fast-path caveats. |
+| POC tune reference | `../pi-config/bin/clearance-tune` | `git@github.com:nklisch/pi-config.git` | `ddf3a60641cbbb1e5761865f6bca702b19a5267b` | Same no-license/provenance note as the POC corpus. Read-only reference only. | Dry-run report fields, before/after compare shape, Markdown report sections, and fixture-runner ergonomics. |
+| POC fast-path tests | `../pi-config/tests/clearance-fastpath.test.mjs` | `git@github.com:nklisch/pi-config.git` | `ddf3a60641cbbb1e5761865f6bca702b19a5267b` | Same no-license/provenance note as the POC corpus. Read-only reference only. | Concrete safe and unsafe command examples used to derive grouped lessons. |
+| POC tune skill | `../pi-config/.pi/skills/clearance-tune/SKILL.md` | `git@github.com:nklisch/pi-config.git` | `ddf3a60641cbbb1e5761865f6bca702b19a5267b` | Same no-license/provenance note as the POC corpus. Read-only reference only. | Historical workflow precedent: baseline, inspect misses, show changes, rerun compare, then challenge with adversarial fixtures. Current tune batches are sized to evidence rather than inherently one change. |
+| Old fork tests | `test/bash-external-directory.test.ts`, `test/handlers/external-directory-*.test.ts`, `test/detect-permissive-bash-fallback.test.ts`, wider `test/` tree | `git@github.com:nklisch/pi-clearance.git` | `234d1c22c4f959e67f5cb6d2984ce53f17ff0873` plus current working tree during cleanup | Historical mining provenance only; these tests are from the fork-shaped scaffold and do not define the new behavior contract. | Command strings and structural cases curated into `test/fixtures/corpus/fork-derived.json`. |
+| Old fork package metadata | `package.json` | `git@github.com:nklisch/pi-clearance.git` | `234d1c22c4f959e67f5cb6d2984ce53f17ff0873` plus current working tree during cleanup | Historical mining provenance only. Fork name/version/description are cleanup inputs, not product identity. | Package-shape facts for the note below: Pi extension entry, ESM type, peer/runtime dependencies, and Node engine. |
+
+Captured POC corpus provenance also lives beside the copied corpus in
+`test/fixtures/corpus/pi-config-classifier.README.md`: source path, remote, captured
+commit, owner, license status, row count, and row shape.
+
+## Command-pattern lessons
+
+These lessons are intentionally phrased as command families and structural caveats, not
+as reusable matching code. Future packs should express them over parsed command-shape
+fields and tested DSL matchers.
+
+### `fast_path` candidates
+
+The POC points to these as useful baseline-pack candidates when their parsed shape is
+clean and no sealed-floor or review-gate condition is present:
+
+- Read-only shell inspection: directory listing, file viewing, file metadata, counts,
+  environment/state inspection, command help/version checks, and simple formatted output.
+- Read-only search and stream inspection: grep-like search, JSON/text filters, strict
+  print-only `sed -n` line ranges, `sort`/`uniq`/`cut`/`tr` when used as readers rather
+  than output writers or shell launchers.
+- Read-only Git and GitHub CLI inspection: status, log, diff, show, branch/tag listing,
+  worktree listing, config reads, PR/issue/run viewing, checks/status, and read-only
+  `gh api` calls that do not request mutating methods or field-submission behavior.
+- Bounded system log inspection: `journalctl` used for reading logs, especially when
+  piped to a bounded display stage such as `tail`; journal maintenance operations are
+  not part of this family.
+- `cd repo && safe` and `cd repo; safe` forms when the directory-change prefix is followed
+  only by independently safe command blocks.
+- Safe `&&`, semicolon, and newline blocks when every top-level segment independently
+  qualifies as safe. Operators embedded inside quotes are data, not shell control flow.
+- Safe pipelines when every stage is independently safe and the pipeline does not end in
+  or hide a shell interpreter.
+- Narrow `|| true` and `|| :` fallbacks, including no-space spellings such as `||true`,
+  only when the left side is already safe and the fallback merely suppresses a non-zero
+  probe exit. Standalone `true` or `:` is not the same lesson.
+- Benign stderr redirects such as dropping stderr to `/dev/null` or merging stderr into
+  stdout for display. Broad stdout redirects and nonstandard redirect targets belong in
+  review.
+
+### `review` candidates
+
+The POC and fork-derived review sets are the richest source of adversarial fixture ideas.
+These families should not fast-path merely because the first visible command looks safe:
+
+- Pipe-to-shell forms such as safe-looking output piped into `sh`, `bash`, `zsh`, or
+  another shell interpreter.
+- Command substitution and process substitution, especially when they hide file reads,
+  destructive commands, or credential access inside an otherwise familiar command.
+- Heredocs and comment-led multi-line snippets. The POC kept these review-gated rather
+  than trying to infer intent from a text block.
+- Secret-bearing input or arguments: credential-file input redirects, `.ssh`/cloud/Pi auth
+  paths, direct `.env` reads/copies, and secret-looking environment expansion such as
+  token, password, private-key, or access-key variables.
+- Broad or ambiguous redirects: stdout file writes, whole-command redirection forms,
+  unexpected file-descriptor redirects, and redirect targets that only look like benign
+  stderr suppression.
+- Mutating GitHub API usage: explicit POST/PUT/PATCH/DELETE methods, equivalent method
+  spellings through shell quoting, and field/input flags that can switch a nominal API
+  call into a mutation.
+- Destructive Git behavior: force pushes and plus-refspecs, hard resets, destructive
+  clean operations, branch deletion, and worktree removal, including when hidden behind
+  global Git options or after a safe prefix.
+- `sed` strict-print evasion: write commands, extra programs, in-place or execute-style
+  behavior, and quoted option tricks that add a second program after a safe-looking print.
+- Reader tools with mutation escapes: output-writing `sort`, multi-output `uniq`,
+  destructive or executing `find`, and `journalctl` maintenance/vacuum operations.
+- Path and basename spoofing: local-tool lookalikes, suffix tricks, arbitrary absolute
+  paths, path traversal, doubled or non-canonical path segments, and approved path
+  prefixes followed by traversal to a different executable.
+- External-directory and trust-boundary cases from the old fork tests: outside-project
+  reads/writes, external `cd` changing the base for a later path, home-expanded SSH paths,
+  and most-restrictive-wins precedence examples.
+- Unsafe composition: safe command followed by unsafe `&&`, semicolon, or newline segment;
+  multiple `||` fallbacks; non-true/colon fallbacks; expansions standing in for fallback
+  commands; backgrounding with `&`; stderr-pipe syntax; subshell groups; and brace groups.
+- Local scripts and shell wrappers when the deterministic policy cannot inspect their
+  behavior from the command shape alone.
+
+### POC `hard_block` rows and sealed-floor nuance
+
+The frozen POC corpus has exactly five `hard_block` rows:
+
+- root recursive delete with an option terminator;
+- block-device overwrite;
+- filesystem formatting through an `mkfs` frontend;
+- root recursive delete hidden inside an otherwise safe-looking `&&` chain; and
+- root recursive delete hidden inside a semicolon-separated block.
+
+Those five rows describe the POC corpus, not this project's complete sealed floor. The
+foundation docs remain authoritative: `SPEC.md`, `RULE_PACKS.md`, and `PRINCIPLES.md`
+define a broader downstream sealed-floor design space that includes catastrophic
+filesystem/disk/system behavior, secret exposure, privilege escalation, remote execution,
+parser-defeating forms, and shutdown/reboot. Capturing only five POC `hard_block` labels
+must not downgrade other foundation-defined floor candidates to ordinary review.
+
+### Risky-behavior catalog
+
+The POC named risky behaviors so the reviewer could see why a command deserved scrutiny.
+For this project, the names are useful catalog terms for review-gate packs and fixtures;
+the POC's detection code is not reusable runtime logic.
+
+- **force-push** — remote history overwrite through force flags or plus-refspecs.
+- **branch-delete** — local branch deletion, especially destructive deletion of work that
+  may lack a remote or durable reflog.
+- **worktree-remove** — removing a linked working tree directory.
+- **hard-reset** — discarding working tree and index changes.
+- **git-clean** — deleting untracked or ignored files/directories.
+- **recursive-delete** — recursive filesystem deletion outside the catastrophic root case.
+- **privilege-escalation** — commands that elevate privileges or request administrator
+  execution.
+- **broad-chmod** — world-readable/world-writable permission broadening such as mode 777.
+- **fork-bomb** — shell forms that exhaust process resources.
+- **disk-destructive** — direct disk overwrite or filesystem formatting operations.
+- **system-shutdown** — shutdown, reboot, halt, poweroff, or equivalent system-stop forms.
+- **remote-shell** — remote content fetched and piped into a shell for immediate execution.
+
+The POC often treated these as `review` behaviors, not automatic `hard_block` outcomes.
+Only its catastrophic subset became `hard_block`. That matches `RULE_PACKS.md`: the sealed
+floor is intentionally narrow and high-confidence, while broader risky behavior belongs in
+review-gate packs unless downstream pack/core design promotes a case into the sealed floor
+with evidence.
+
+## Tune report target shape
+
+The POC tune workflow is valuable because it dry-runs command history and fixtures
+without executing commands, then makes before/after policy changes visible. Downstream
+tune work can rename fields or add provenance/rule-id columns, but should preserve this
+shape and the asymmetry principle from `PRINCIPLES.md` §8: allow expansions such as
+`review->fast_path` transitions must be visually obvious in compare output.
+
+Target JSON report shape:
+
+```text
+{
+  generatedAt,
+  repoRoot,
+  sourcePath,
+  summary: {
+    totalCalls,
+    totalUnique,
+    fastPathCalls,
+    fastPathUnique,
+    reviewCalls,
+    reviewUnique,
+    hardBlockCalls,
+    hardBlockUnique
+  },
+  topReviewedExecutables,
+  topFastPathExecutables,
+  topReviewedCommands,
+  topHardBlockedCommands,
+  perCommand: [
+    { command, count, executable, status, reason, behaviors? }
+  ],
+  compare?: {
+    changedUnique,
+    changedCalls,
+    transitions,
+    beforeSummary,
+    afterSummary
+  }
+}
+```
+
+Additional shape notes:
+
+- `perCommand.status` uses the captured labels: `fast_path`, `review`, or `hard_block`.
+- `transitions` is a sorted before/after status list such as `review->fast_path` with a
+  count. The important lesson is not the exact representation; it is that newly allowed
+  commands stand out during review.
+- Markdown reports should include, in order: title, generated timestamp, `## Summary`
+  with counts and percentages, optional `## Compare` with changed counts and transition
+  lines, `## Top reviewed executables`, `## Top reviewed commands` with reasons, and
+  `## Top hard-blocked commands`.
+- The agent workflow around the report should baseline current behavior, inspect misses by
+  family, make evidence-sized bounded changes, rerun with compare, run fixtures, and then
+  add curated adversarial cases. Adversarial agents or reviewers find clever breaks; they
+  do not decide which ordinary workflows should become policy.
+
+## Package-metadata reference note
+
+The old fork `package.json` is mined for package-shape facts only. The durable product
+target identity is Pi Clearance / `pi-clearance` as a clean pre-1.0 Pi extension; `package-spine` resets the
+fork-shaped `name`, `version`, and `description` instead of preserving them as product
+identity.
+
+Package-shape facts to carry forward:
+
+- Pi extension entry convention: `pi.extensions: ["./src/index.ts"]`.
+- ESM package mode: `"type": "module"`.
+- Pi host API as peer dependency: `@earendil-works/pi-coding-agent` stays a peer, never a
+  bundled runtime dependency.
+- Bash parser grammar source: `tree-sitter-bash`; the active product target routes runtime
+  parsing through the Rust native clearance core rather than a JavaScript/WASM parser
+  dependency shape.
+- Node engine: `node >=22`, matching the Pi host runtime expectation.
+
+Cleanup inputs only:
+
+- The fork-shaped package `name`, `version`, and `description` are not durable identity.
+  `package-spine` owns the reset to clean pre-1.0 metadata for this product.
+- The old fork exports, files list, schemas, config examples, permission-system keywords,
+  and extra permission-manager package surface are not behavior contracts. Future package
+  metadata should be derived from `docs/VISION.md`, `docs/SPEC.md`, and the clean module
+  spine.
+
+## Do-not-port architecture bullets
+
+- Do not port `AUTO_PERMITTED` regexes, `roughTokenize`, `splitTopLevel`, or
+  `isSimpleCommand`/`isFastPathEligible*` as runtime safety mechanisms.
+- Do not treat `peeragent`, `agent-comms`, or `.work/bin/work-view` POC approvals as
+  universal shipped defaults.
+- Do not treat old fork tests or flat `allow|ask|deny` / wildcard matcher maps as the new
+  behavior contract.
+- Do not bring forward `PermissionManager`, `yoloMode`, session approval, subagent
+  forwarding, or wildcard permission architecture.
+- Do not redefine the sealed floor from the POC label distribution. The POC has only five
+  `hard_block` rows, but foundation docs keep secret exposure, privilege escalation,
+  remote execution, parser-defeating forms, and shutdown/reboot in sealed-floor scope
+  unless downstream pack/core design narrows a specific case with evidence.
+- Do not invalidate corpus JSON with comments or embedded provenance.
+
+The intended flow is: translate useful examples into parsed-shape fixtures and pack tests;
+implement policy through this repo's analyzers, DSL matchers, sealed-floor validation,
+review-gate packs, replay reports, and user-approved overlays.
+
+## Category coverage check
+
+Across `test/fixtures/corpus/pi-config-classifier.json` and the curated
+`test/fixtures/corpus/fork-derived.json`, the captured examples represent the reference
+categories the downstream fixture harness must preserve:
+
+- safe read chains and `&&`/`;`/newline blocks of independently safe commands;
+- `cd repo && safe` directory-change chains;
+- narrow `|| true` / `|| :` fallbacks, including the no-space `||true` form;
+- safe read-only pipelines including `| sed -n` strict print and `| tail`;
+- pipe-to-shell forms such as `| sh` and `| bash`;
+- command substitution `$(...)` and process substitution `<(...)`;
+- heredocs;
+- stdout redirects `>` and broad redirects, plus benign stderr redirects such as
+  `2>/dev/null` and `2>&1`;
+- secret path input redirects such as `< ~/.ssh/id_rsa`, `< ~/.aws/credentials`, and
+  `< $HOME/.pi/agent/auth.json`;
+- secret-looking environment expansion such as `$GH_TOKEN` and
+  `${AWS_SECRET_ACCESS_KEY}`;
+- mutating GitHub API forms such as `gh api ... -X POST`, `--method DELETE`, and field
+  flags that switch a request into mutation;
+- destructive Git forms such as plus-refspec force push, `reset --hard`, `clean -ffdx`,
+  and `branch -D`;
+- `sed` strict-print fast path versus `w`/`-e` extra-program evasion;
+- `sort`, `uniq`, `find`, and `journalctl` tricks such as `-o`, `-delete`, `-exec`, and
+  `--vacuum-time`;
+- path spoofing and lookalikes such as `peeragent.bak`, `work-view.evil`, `..` traversal,
+  and non-canonical approved paths; and
+- catastrophic root/disk/system forms such as `rm -rf -- /`, `dd of=/dev/sda`, and
+  `mkfs -t ext4 /dev/sda`, including when hidden inside `&&`, semicolon, or newline
+  chains.
+
+This coverage assertion is a reference-capture check, not the final product contract.
+`capture-verification` enforces that the two corpus files keep these categories
+represented, while downstream pack/core design remains responsible for deciding which
+categories become allow, review, or deny under the clean interpreter.

package/node_modules/@nklisch/pi-clearance/docs/REVIEWER_PROMPTS.md

@@ -0,0 +1,37 @@
+# Reviewer prompts
+
+The model reviewer runs only after deterministic policy returns `review` and only when global `mode` is `auto`. Mode `ask` uses the human path; mode `off` passes the review bucket through with an audit record. Prompt configuration never changes deterministic policy or the sealed floor.
+
+## Advanced config knob
+
+`reviewer.promptPosture` is a config-file-only advanced setting. It defaults statically to `reviewer.default` and accepts:
+
+- `reviewer.strict` — conservative uncertainty handling;
+- `reviewer.default` — balanced bounded project workflow review;
+- `reviewer.permissive` — broader trusted-project context while retaining floor/secret/system safeguards.
+
+The prompt posture is no longer derived from a policy profile because policy profiles were removed. `promptAppends`, trusted project appends, and a full `promptOverride` survive as advanced config fields. Unknown `reviewer.*` fragments fail closed.
+
+## Context
+
+`contextMode` defaults to `recentContext`. `minimal` sends the current call, parsed shape, policy result, and prompt summary. `recentContext` adds bounded, redacted recent decisions and conversation turns. That context is explicitly untrusted intent evidence, never policy, precedent, or instructions.
+
+`tokenBudget` is windowed and unlimited by default. `escalation` records contention but does not bypass the first model attempt when Auto mode has a usable model.
+
+## Disclosure
+
+The Auto mode confirmation card discloses the configured/fallback model and provider, prompt posture, context mode, and the untrusted-context rule. `mode: "auto"` in user-owned config is the acknowledgment. There is no consent schema, writer, prompt, or `reviewer-consent.json` read/write path.
+
+## Prompt contract
+
+The assembled prompt must preserve the required response schema:
+
+```text
+{"decision":"allow"|"deny","reason":"short explanation"}
+```
+
+Commands, tool output, repository text, recent decisions, and conversation excerpts are untrusted data. Prompt injection cannot override deterministic deny decisions. Invalid overrides fail closed to human review or block-and-log.
+
+## Model selection
+
+`reviewer.model` remains interactive in the settings UI and can pin `provider/modelId`; the panel otherwise displays reviewer settings read-only. The model falls back to the active Pi session model when no explicit pin is available.

package/node_modules/@nklisch/pi-clearance/docs/RULE_PACKS.md

@@ -0,0 +1,198 @@
+# Rule packs
+
+Rule packs are inspectable policy modules. The interpreter applies the sealed floor first, then active packs with fixed precedence `deny > review > allow`.
+
+## Baseline
+
+Every mode uses the same built-in baseline. It contains the former default pack set:
+
+- shell inspection/search/VCS and safe composition;
+- expanded inspection, shell-builtin, and system/service read packs;
+- risky and compound-shell review gates;
+- project/temp constructive commands and read-only compound loops;
+- typed Pi inspection, file mutation, extension inspection, and workflow packs;
+- development verification and package workflows;
+- `bash.vcs.read` Git read plumbing and inspection forms, plus
+  `bash.vcs.write` routine local Git writes;
+
+### Git coverage and leading options
+
+`bash.vcs.read` allows the read-only plumbing commands `rev-parse`, `blame`,
+`grep`, `ls-tree`, `cat-file`, `merge-base`, `describe`, `shortlog`,
+`show-ref`, `check-ignore`, `name-rev`, `count-objects`, `ls-remote`,
+`diff-tree`, and `diff-index`. It also covers branch/tag listing and local
+creation without destructive flags, `remote -v/show/get-url`, read-only
+`config --get/--list`, `stash list`, and `worktree list`. A bare `git remote`
+is intentionally not expressible by the v1 matcher vocabulary and remains
+review-gated; remote mutation remains review-gated as well. The bare-git
+remote limitation applies only to that no-subcommand inspection form, not to
+`remote -v`, `remote show`, or `remote get-url`.
+
+`bash.vcs.write` allows routine local `add`, `commit` (including `--amend`),
+`fetch`, `pull` (including `--rebase`), `merge`, `switch` without force flags,
+and `checkout -b`. `push` remains review wholesale. Reset and clean remain
+review wholesale, as do destructive branch/tag/checkout/switch variants and
+all stash, worktree, and remote mutations. Git write families are excluded
+from v1 heterogeneous composition, so a chain such as `git add . && git
+commit -m msg` remains review.
+
+The parser projects supported Git leading options before policy matching:
+`-C <path>`, `--git-dir[=<path>]`, `--work-tree[=<path>]`, `--no-pager`, and
+`--literal-pathspecs`. This makes the real subcommand available at argument
+index zero for direct rules and read-only composition. Refused or unknown
+leading options—including `-c`, `--config-env`, `-P`/`--paginate`,
+`--exec-path`, `--bare`, bundled `-C/path`, and unknown options—leave the
+stage untouched and emit `bash:leading-option-unmodeled`, so they fail closed
+to review. Successful projection emits the informational
+`bash:leading-options-stripped` diagnostic; it does not block an otherwise
+eligible allow.
+
+The baseline also includes the formerly permissive-only network and home surfaces:
+
+- `bash.network.read`;
+- `pi.extension.network-research`;
+- `pi.home.safe`.
+
+Typed Pi `read`, `ls`, `find`, `grep`, `fffind`, and `ffgrep` calls are baseline-allowable when every path fact is proven inside project/temp, non-secret `home`, or `agent-support` scope. `safe-home` remains covered by the home pack, while typed mutations remain `safe-home`-only. The non-secret home read decision is intentionally baseline-wide now that postures are gone: the sealed floor remains non-overridable, and the sensitive-home catalog is the explicit carveout for credential harbors. System and outside paths therefore remain review-gated. Denied, unknown, and sensitive-home paths are governed by the config-derived `config.scope.behavior` rules: configured denied directories deny outright, while unknown and sensitive-home paths are ceilings that review or deny per `projectScope` behavior fields.
+
+Mode is a review-dispatch choice, not a policy-pack selector. Conditional extension packs activate only when their owning tools are registered. Package-contributed packs are available for discovery but never active until user-owned `packEnablement.enabledPackagePacks` explicitly enables them.
+
+### Embedded shell extension boundaries
+
+`background` and `monitor` are analyzed as typed extension tools, but their
+`command` string is projected into a nested `BashCommandShape`. `decide()`
+evaluates that inner shape through the ordinary sealed-floor, review, and allow
+pipeline; it does not redispatch a synthetic bash tool call. Consequently,
+`background({ command: "pnpm test" })` can use the shipped development pack,
+while an inner privilege-escalation or other sealed-floor command is denied
+before wrapper policy is considered.
+
+The projection accepts an optional finite non-negative `timeout` as a resource
+bound. An optional `workingDirectory` (also accepted as `working-directory` or
+`cwd`) must classify inside the configured project or writable-project scope;
+missing, dynamic, system, temporary, or outside-project directories remain
+review-gated. Unknown wrapper fields, missing/non-string commands, invalid
+timeouts, and unparseable shell input fail closed. The
+`pi.extension.review-boundaries` rule is therefore a fallback for an absent or
+uncertain inner projection, not a blanket review of a command that the bash
+policy can already decide.
+
+## Sealed floor
+
+`floor.deny` is always active and cannot be overridden by mode, user packs, repository policy, human approval, or model output. Its catastrophic stage rules use `stageSome` semantics: they inspect every modeled top-level command stage and every command stage in a fully modeled `for`, brace-group, or conditional body. Unsupported or unmodeled bodies retain their blocking diagnostics and fall to review. Commands hidden inside substitutions are likewise review-gated until the parser projects substitution stages.
+
+The shipped floor denies system-root deletion, privilege escalation, shutdown/reboot, `dd` writes whose `of=/dev/...` target is not a pseudo-device (`null`, `zero`, `full`, `random`, `urandom`, standard streams, or `fd/`), and the enumerated device-targeting `mkfs` family. Image-file formatting, `dd` reads, pseudo-device writes, and unlisted disk tools remain review-gated; `wipefs`, `shred`, `sgdisk`, `fdisk`, `parted`, and `zpool` are deliberate follow-up coverage. Every floor `stageSome` inner carries a concrete program anchor so allow/floor overlap can be checked conservatively; an allow-side `stageSome` remains overlap-unknown and is rejected at load time.
+
+## Pack explorer
+
+`/clearance packs` shows baseline, configured, package, and sealed-floor entries. Explorer state uses baseline vocabulary: sealed floor, baseline, enabled config, available, disabled, missing, or ambiguous. It no longer exposes profile membership or posture filters.
+
+## Authoring
+
+A pack is a versioned object with `id`, optional inert metadata, and rules:
+
+```json
+{
+  "version": 1,
+  "id": "user-project.reads",
+  "rules": [
+    {
+      "id": "read-docs",
+      "effect": "allow",
+      "match": { "all": [{ "tool": "bash" }, { "program": "cat" }] },
+      "reason": "read project documentation",
+      "provenance": { "source": "user-project" }
+    }
+  ]
+}
+```
+
+Allow rules must be statically disjoint from the sealed floor. Unknown overlap rejects the pack. Repository packs are tighten-only unless Pi reports the project as trusted. Trusted TypeScript rule modules are cut; only inspectable data packs are loadable.
+
+## Path and compound safety
+
+Constructive allows should use path facts and require complete per-stage coverage. Unknown, home, outside, system, and denied facts never satisfy a project-local allow. Compound-shell allows require modeled form, read-only body effects, safe iterator/body scopes, no substitution, no shell wrapping, and no output redirects.
+
+The development-verification pack also allows routine formatter writes when every
+formatter file operand is proven inside `project`, `writable-project`, or `temp`:
+`cargo fmt`, `biome --write`, `prettier --write`, `ruff check --fix`, and
+`eslint --fix`. A bare `cargo fmt` uses the configured current project root as
+its scope proof; path-bearing forms require path facts. Config, plugin, rules,
+parser, output, manifest, and unstable-option escape flags remain review-gated,
+as do out-of-scope or dynamic operands. `go fmt` remains review-gated. These
+write rules are direct command allows, not read-only composition families.
+
+## Bash environment and wrapper safety
+
+The baseline review pack screens command-stage environment assignments before
+allow rules are selected. Exact names, `LD_`/`DYLD_`/`GIT_CONFIG_` and
+`CARGO_TARGET_` namespaces, and case-insensitive `npm_config_` names route to
+review; benign assignments such as `FOO=1` remain eligible for their normal
+allow rules. This is a review-tier gate, not a sealed-floor deny.
+
+Package-runner coverage includes the pnpm dialect and matching npm/yarn script
+posture. Supported pnpm global options are projected before policy matching, so
+`--filter`, `--dir`, and workspace flags expose the real subcommand; unknown
+options and `-g`/`--global` remain review-gated. The leading `--dir` behavior
+intentionally follows pnpm's project-selection grammar, including its
+cross-project lifecycle-script trust trade-off. Script-shaped pnpm/npm/yarn
+shorthands are equivalent to `run <script>` for project-local workflows, while
+named mutating pnpm subcommands and remote `dlx` execution remain review. The
+`pnpm exec` wrapper projects its target through the complete floor and pack
+pipeline (including environment screening and trusted `node_modules/.bin`
+basename reduction); `dlx` is never projected. Read-only package information
+such as `pnpm list`, `why`, `outdated`, `audit`, `view`, `config list`, and
+`--version` is eligible for the read-only composition family, except audit
+fix forms.
+
+The expanded inspection baseline includes filesystem metadata, checksum,
+process, date, hostname, and shell-state inspection. `bash.shell.builtins`
+handles literal `export`, safe `set` options, tests, `command -v/-V`, and lone
+`cd`; bare `export`/`export -p`, `printenv`, and bare `env` remain review-gated.
+`bash.system.read` handles journalctl and bounded Docker/Podman inspection; systemctl
+inspection/listing, journal mutation, remote systemctl flags, container log follow, and
+streaming stats remain review-gated. Systemctl read forms intentionally cannot be
+allow-loaded while the sealed shutdown floor uses a program-level existential witness.
+
+The parser projects a bounded set of literal wrappers to the inner command so
+the same floor, registry, path facts, and packs classify it: benign `env`
+options (`-u`/`--unset` and `-i`), literal `timeout` durations, `rustup run`
+with a literal toolchain, and trusted system-bin paths including
+`/usr/local/bin`. Unrecognized wrapper options, dynamic durations/programs,
+bare `env`, and `printenv` stay review-gated. Each successful projection emits
+an informational `bash:stage-unwrapped` diagnostic for provenance; the
+information diagnostic itself does not block an otherwise eligible allow.
+
+Registry conditions are also compiled into direct read-only pack guards. This
+keeps execution-capable flags such as ripgrep preprocess/replacement options,
+`find` output actions, sort compressors/output flags, and tail follow modes out
+of the read-only allow surface while their named review rules explain the gate.
+
+## Heterogeneous read-only composition
+
+The baseline `bash.structure.safe` pack has derived composition allows for
+multi-stage commands. Every command stage must independently match a read-only
+or dev-verification family; a single unknown, mutating, or review-gated stage
+vetoes the composition. The ordinary v1 table includes inspection,
+search/filter, Git/GitHub read, development verification, system/service reads,
+shell builtins, `sed -n`, and the `true`/`:` no-ops. Network families remain
+available for ordinary composition, but are deliberately excluded from benign
+output-redirect tolerance: `curl URL > file` is equivalent to network fetch
+plus local write and stays review-gated. Package-manager mutation workflows
+(`bash.packages.common`) and constructive writes are intentionally not family
+members.
+
+Only `and` and `seq` are freely composable. A final `|| true` or `|| :` is
+accepted only when the fallback is the penultimate operator's final block and
+is a bare, resolvable no-op with no arguments, flags, environment assignments,
+substitutions, redirects, pipeline, or background execution. `minStages: 2`
+keeps single-stage commands with their owning pack's provenance. Stage-level
+review and deny rules retain global precedence over the composition allow.
+
+Benign output redirects are a separate narrow allow: literal temp/project
+paths and `/dev/null` are eligible, while `.git` segments, unknown file
+descriptors, dynamic targets, and cwd-relative paths outside the project stay
+review-gated. `$TMPDIR/x` is supported only when the command does not assign
+`TMPDIR`; `go fmt` and node debug-listener flags remain review-gated.
+
+See [PACK_AUTHORING.md](PACK_AUTHORING.md) for matcher and registration details.

package/node_modules/@nklisch/pi-clearance/docs/SPEC.md

@@ -0,0 +1,45 @@
+# SPEC — Pi Clearance
+
+Pi Clearance is a Pi extension that structurally analyzes tool calls, evaluates a sealed deterministic policy, and dispatches only policy uncertainty to a configurable review path.
+
+## Hard constraints
+
+- The sealed deny floor always evaluates first and cannot be loosened.
+- The Rust policy interpreter is pure and total: every call resolves to `allow`, `deny`, or `review`.
+- Parser/analyzer uncertainty, unknown tools, invalid config, and ambiguous conflicts fail closed.
+- Mode is global-only and is the single behavioral dial: `off`, `ask`, or `auto`.
+- Mode changes only dispatch of `review`: Off passes through and audits; Ask prompts a human; Auto uses model-first review with human/block fallback.
+- Off still honors floor, user, shipped, repository, and package deny rules.
+- Model output resolves one call and cannot edit policy or loosen the floor.
+- User-owned global/project config may add policy; repository policy is tighten-only unless Pi reports the project as trusted.
+- Package installation makes packs available, not active. Explicit user-owned enablement is required.
+- Pre-public migrations are clean cutovers. Removed keys fail strict schema validation; there are no translators or aliases. Trusted TypeScript rule modules are deliberately cut and are never loaded.
+- The native engine is distributed as prebuilt Node-API artifacts for Linux x64 glibc and macOS arm64. Installation never runs Cargo; a missing or unsupported artifact fails closed.
+
+## Config
+
+`GlobalConfigSchema` contains `version`, `mode` (default `ask`), `unknownToolPosture`, packs, package/config enablement, reviewer advanced fields, and display preferences. Project overlays contain packs, enablement, project scope, and trusted prompt appends. Repository policy has no mode or posture.
+
+The former policy posture system and reviewer `enabled`/`mode` fields are removed. Reviewer model pinning remains an interactive settings action; other reviewer advanced knobs are config-file-only. The separate reviewer consent schema/file is removed; explicit `mode: "auto"` is the acknowledgment.
+
+## Native boundary
+
+The TypeScript extension resolves config and pack data, then sends JSON-shaped
+commands and an opaque compiled-policy handle to the Rust core. Rust owns bash
+parsing, tool analysis, path-fact enrichment, matcher IR compilation, policy
+composition/evaluation, and replay/adversarial computation. TypeScript retains
+corpus acquisition, proposal heuristics, presentation, and Pi I/O.
+
+## Resolution
+
+1. sealed floor;
+2. built-in baseline;
+3. user-global packs;
+4. user-project packs and scope;
+5. trusted repository/package inputs.
+
+The baseline is the former default pack set plus `bash.network.read`, `pi.extension.network-research`, and `pi.home.safe`. Individual pack ids flow into provenance; no posture pseudo-pack exists.
+
+## Commands
+
+`/clearance setup`, `/clearance mode [off|ask|auto]`, `/clearance settings`, `/clearance status`, `/clearance packs`, `/clearance scope`, `/clearance tune`, `/clearance why`, `/clearance allow <plain language>`, and `/clearance allow`. The allow handler only hands a deterministic brief to the agent; it does not construct policy or call the reviewer. `/clearance profile` and `/clearance auto` are removed.

package/node_modules/@nklisch/pi-clearance/docs/TUNE.md

@@ -0,0 +1,32 @@
+# Tune mode
+
+Tune mode is toggled with `/clearance tune`. It temporarily exposes structured history, replay, proposal-generation, and adversarial-analysis tools to the agent. It does not silently change runtime policy.
+
+## Always-on vs Tune-only tools
+
+Two tools are always active, in and out of Tune mode:
+
+- `clearance_propose` — validates and batches agent-authored proposal drafts (read-only; imports no writers).
+- `clearance_present` — fills approval evidence, renders the batch card, collects explicit user approval, and is the only write path.
+
+Tune mode adds the deep-analysis surface on top: `clearance_status`, `clearance_list_packs`, `clearance_list_history_families`, `clearance_generate_proposals`, `clearance_show_proposal`, `clearance_replay_proposal`, `clearance_validate_pack`, and `clearance_adversarial_cases`. Tune-generated batches flow through the same shared batch cache and the same `clearance_present` card — one format, one approval gate, in or out of Tune.
+
+The batch card is progressive-disclosure: the default view is a dense plain-language summary ("These 12 rules allow: …") plus a one-line evidence status and always-on safety warnings (sealed-floor overlap, path-scope widening). Exact rule diffs, matcher JSON, replay deltas, and adversarial cases render only when the user selects the detail display mode. Approval is approve-all or per-group; when no captured corpus exists, the automated gate fails closed but the card may offer the human an explicit, warned "approve without replay evidence" action — only for genuine no-corpus proposals.
+
+Tune proposals may target user-owned packs, project scope, package enablement, surviving reviewer advanced config, and `mode` suggestions. Proposals must not target removed posture fields, `reviewer.enabled`, or `reviewer.mode`. A mode suggestion uses the same approval-gated card as other config changes.
+
+The safe loop is:
+
+1. inspect complete captured history;
+2. replay current policy without executing commands;
+3. generate an evidence-sized proposal batch;
+4. show exact diffs, warnings, replay deltas, and adversarial cases;
+5. get explicit user approval in Pi UI;
+6. write only user-owned config;
+7. reload, validate, and replay again.
+
+Runtime reviewer decisions are evidence, not permanent policy. Package installation only makes packs available; Tune must still show and approve explicit enablement. Trusted TypeScript rule-module proposals are removed; Tune emits only inspectable data-pack and core-matcher design inputs.
+
+The product interface is Pi-native. Helper executables are plumbing for tests and debugging, not the user's control surface.
+
+`/clearance allow` is the user-initiated entry point: it hands a deterministic authoring brief to the agent (one draft per named family, batches kept focused) and feeds the same `clearance_propose`/`clearance_present` approval pipeline. Tune remains the corpus-evidence batch surface; it sizes proposals from replay history rather than a single user request.