@nklisch/pi-enhanced 0.4.3 → 0.5.0

package/node_modules/@nklisch/pi-astral-pocket/src/tools.ts

@@ -2,140 +2,246 @@ import { Type } from "typebox";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { join } from "node:path";
-
 import type { ActivationState } from "./activation.js";
 import { resolveProjectIdentity } from "./scope.js";
 import { searchAstraSessions } from "./sessions.js";
-import { readSummaryCapped, searchPocket, writeNote } from "./store.js";
+import {
+  MAX_BODY_CHARS,
+  MAX_EVIDENCE_CHARS,
+  MAX_TITLE_CHARS,
+  retireNote,
+  searchPocket,
+  writeNote,
+} from "./store.js";
 
 const INACTIVE_MESSAGE =
   "Pocket tools are only active in gpt-6-astra sessions with the pocket enabled (/pocket on).";
-const DEFAULT_RECALL_LIMIT = 10;
 export const MAX_RECALL_LIMIT_PER_SOURCE = 20;
-
 function normalizeRecallLimit(value: unknown): number {
-  if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_RECALL_LIMIT;
+  if (typeof value !== "number" || !Number.isFinite(value)) return 10;
   return Math.min(MAX_RECALL_LIMIT_PER_SOURCE, Math.max(1, Math.trunc(value)));
 }
-
 export interface ToolDeps {
   state: ActivationState;
-  /** Pocket root directory (~/.pi/agent/astral-pocket). */
   root: string;
-  /** Sessions directory (~/.pi/agent/sessions). */
   sessionsDir: string;
   maxSessionAgeDays: () => number;
 }
-
 function textResult(text: string) {
   return { content: [{ type: "text" as const, text }], details: {} };
 }
-
 export function registerPocketTools(pi: ExtensionAPI, deps: ToolDeps): void {
   pi.registerTool({
     name: "pocket_note",
     label: "Pocket Note",
     description:
-      "Write a durable note to your persistent pocket. Notes default to the current repository. Use global scope only for explicitly portable preferences or observations — never for secrets or ephemeral task state.",
-    promptSnippet: "Save a durable cross-session note to the astral pocket",
+      "Save, replace or retire a current-repository navigation clue or hard-to-rediscover technical pitfall. Never save preferences, user policy, delivery history or facts already covered by current docs. New notes are project-only.",
+    promptSnippet:
+      "Save or retire a repository navigation clue or technical pitfall",
     promptGuidelines: [
-      "Use pocket_note when you learn something durable (a decision and why, a project convention, a pitfall, a user preference) — not for ephemeral task state.",
-      "Never put secrets, credentials, tokens, or personal data in pocket notes.",
-      "Keep pocket_note project-scoped by default; use global scope only for a clearly general preference or conditional portable observation.",
+      "Use pocket_note only for actionable repository navigation or verified technical pitfalls worth avoiding rediscovery; never preferences, policy, architecture/status summaries, ordinary docs facts or personal data.",
+      "Retire obsolete notes; replace updates agent-authored notes in place, supersedes retires source notes when saving a new learning.",
     ],
     parameters: Type.Object({
-      title: Type.String({ description: "Short note title" }),
-      body: Type.String({ description: "Note content — a few sentences is enough" }),
-      keywords: Type.Optional(Type.Array(Type.String(), { description: "2-5 recall keywords" })),
-      scope: Type.Optional(Type.Union([Type.Literal("project"), Type.Literal("global")], {
-        description: "Project by default. Use global only for explicitly portable preferences or observations.",
-      })),
+      action: Type.Optional(
+        Type.Union([Type.Literal("save"), Type.Literal("retire")], {
+          description: "Default save. Retire needs noteFile only.",
+        }),
+      ),
+      noteFile: Type.Optional(
+        Type.String({
+          description: "Canonical filename to retire (not a path)",
+        }),
+      ),
+      kind: Type.Optional(
+        Type.Union([Type.Literal("navigation"), Type.Literal("pitfall")], {
+          description: "Required for save",
+        }),
+      ),
+      title: Type.Optional(
+        Type.String({
+          minLength: 1,
+          maxLength: MAX_TITLE_CHARS,
+          description: "Required for save: descriptive technical title",
+        }),
+      ),
+      body: Type.Optional(
+        Type.String({
+          minLength: 1,
+          maxLength: MAX_BODY_CHARS,
+          description:
+            "Required for save: one complete actionable learning, not a status summary",
+        }),
+      ),
+      evidence: Type.Optional(
+        Type.String({
+          maxLength: MAX_EVIDENCE_CHARS,
+          description:
+            "Optional source path, symbol, command or other evidence pointer",
+        }),
+      ),
+      keywords: Type.Optional(
+        Type.Array(Type.String({ maxLength: 64 }), { maxItems: 5 }),
+      ),
+      replace: Type.Optional(
+        Type.String({
+          description: "Existing agent-authored note filename to update",
+        }),
+      ),
+      supersedes: Type.Optional(
+        Type.Array(Type.String(), {
+          maxItems: 10,
+          description:
+            "Current-repository note filenames to retire when saving this learning",
+        }),
+      ),
     }),
-    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+    async execute(_id, params, signal, _onUpdate, ctx) {
       if (!deps.state.active) throw new Error(INACTIVE_MESSAGE);
-      if (signal?.aborted) throw new Error("Pocket note cancelled");
-      const project = ctx.cwd;
-      const scope = params.scope ?? "project";
-      const projectId = resolveProjectIdentity(project);
-      const fileName = await withFileMutationQueue(join(deps.root, "POCKET.md"), async () => {
-        if (signal?.aborted || !deps.state.active) throw new Error("Pocket note cancelled");
-        return writeNote(deps.root, {
-          title: params.title,
-          body: params.body,
-          keywords: params.keywords,
-          project,
-          projectId: scope === "project" ? projectId : undefined,
-          scope,
-          source: "agent",
-        });
+      const projectId = resolveProjectIdentity(ctx.cwd);
+      return withFileMutationQueue(join(deps.root, "POCKET.md"), async () => {
+        if (signal?.aborted || !deps.state.active)
+          throw new Error("Pocket note cancelled");
+        if (params.action === "retire") {
+          if (!params.noteFile) throw new Error("Retire requires noteFile");
+          retireNote(deps.root, params.noteFile, projectId);
+          return textResult(
+            `Retired notes/${params.noteFile}; excluded from startup and default recall. Retiring generated learning also prevents further automatic extraction of its source session.`,
+          );
+        }
+        if (params.action !== undefined && params.action !== "save")
+          throw new Error("Unknown note action");
+        if (!params.kind || !params.title || !params.body)
+          throw new Error("Save requires kind, title and body");
+        if (params.noteFile)
+          throw new Error(
+            "Use replace to update a note, or action: retire with noteFile",
+          );
+        const fileName = writeNote(
+          deps.root,
+          {
+            kind: params.kind,
+            title: params.title,
+            body: params.body,
+            evidence: params.evidence,
+            keywords: params.keywords,
+            project: ctx.cwd,
+            projectId,
+          },
+          new Date(),
+          { replace: params.replace, supersedes: params.supersedes },
+        );
+        return textResult(`Learning saved: notes/${fileName}`);
       });
-      return textResult(`Note saved to the pocket: notes/${fileName}`);
     },
   });
-
   pi.registerTool({
     name: "pocket_recall",
     label: "Pocket Recall",
     description:
-      "Search current-repository and explicit global pocket notes plus current-repository Astra sessions. Summarized by default; pass full: true for larger excerpts or scope: all for intentional cross-repository precedent.",
-    promptSnippet: "Search pocket notes and past astra sessions",
+      "Search active current-repository learning notes by default. source: sessions or both explicitly includes historical transcripts. includeHistory: true includes legacy/retired notes; scope: all searches other repositories but does not enable history. full: true returns larger excerpts, not full files.",
+    promptSnippet:
+      "Search repository learning or explicitly requested historical excerpts",
     promptGuidelines: [
-      "Use pocket_recall for the quick pocket pass: search with keywords from the pocket summary before deep repo exploration.",
-      "Keep recall cheap: at most 4-6 lookup steps, summarized results first, full: true only when you need exact commands or error text.",
+      "Start with one focused recall when a concrete navigation or rediscovery problem makes it useful; expand only if results help. Recall is not mandatory for every repository task.",
     ],
     parameters: Type.Object({
-      query: Type.String({ description: "Keywords to search for (all must match)" }),
+      query: Type.String({
+        description: "Keywords to search for (all must match)",
+      }),
       source: Type.Optional(
-        Type.Union([Type.Literal("pocket"), Type.Literal("sessions"), Type.Literal("both")], {
-          description: "Where to search (default: both)",
+        Type.Union(
+          [
+            Type.Literal("pocket"),
+            Type.Literal("sessions"),
+            Type.Literal("both"),
+          ],
+          {
+            description:
+              "Default pocket. Sessions are historical precedent, not active learning.",
+          },
+        ),
+      ),
+      includeHistory: Type.Optional(
+        Type.Boolean({
+          description:
+            "Include labeled legacy, unclassified, retired and global notes (default false)",
+        }),
+      ),
+      full: Type.Optional(
+        Type.Boolean({
+          description: "Larger excerpts, not complete files (default false)",
+        }),
+      ),
+      limit: Type.Optional(
+        Type.Integer({
+          minimum: 1,
+          maximum: MAX_RECALL_LIMIT_PER_SOURCE,
+          description: "Max hits per source; default 10",
+        }),
+      ),
+      scope: Type.Optional(
+        Type.Union([Type.Literal("current"), Type.Literal("all")], {
+          description:
+            "Current repository by default; all adds foreign precedent, independently of includeHistory.",
         }),
       ),
-      full: Type.Optional(Type.Boolean({ description: "Return larger excerpts (default: false)" })),
-      limit: Type.Optional(Type.Integer({
-        minimum: 1,
-        maximum: MAX_RECALL_LIMIT_PER_SOURCE,
-        description: "Max hits from each source (default: 10, maximum: 20)",
-      })),
-      scope: Type.Optional(Type.Union([Type.Literal("current"), Type.Literal("all")], {
-        description: "Current repository plus global notes by default; all includes foreign repositories as precedent.",
-      })),
     }),
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+    async execute(_id, params, signal, _onUpdate, ctx) {
       if (!deps.state.active) throw new Error(INACTIVE_MESSAGE);
-      const source = params.source ?? "both";
+      if (signal?.aborted) throw new Error("Pocket recall cancelled");
+      const source = params.source ?? "pocket";
       const limit = normalizeRecallLimit(params.limit);
-      const recallScope = params.scope ?? "current";
+      const scope = params.scope ?? "current";
       const projectId = resolveProjectIdentity(ctx.cwd);
+      const excludeSession = {
+        id: ctx.sessionManager.getSessionId(),
+        path: ctx.sessionManager.getSessionFile(),
+      };
       const sections: string[] = [];
-
       if (source === "pocket" || source === "both") {
-        const hits = searchPocket(deps.root, params.query, projectId, limit, params.full, recallScope);
+        const hits = searchPocket(
+          deps.root,
+          params.query,
+          projectId,
+          limit,
+          params.full,
+          scope,
+          params.includeHistory,
+          excludeSession,
+        );
         sections.push(
           hits.length === 0
             ? "Pocket notes: no matches."
             : `Pocket notes (${hits.length}):\n${hits
-                .map((h) => `- ${h.title} [notes/${h.noteFile}]${h.project ? ` (${h.project})` : ""} · scope: ${h.scope}${recallScope === "all" && h.scope === "project" && resolveProjectIdentity(h.project) !== projectId ? " · cross-repository precedent" : ""}${h.source ? ` · ${h.source}` : ""}${h.date ? ` · ${h.date}` : ""}\n  ${h.excerpt}`)
+                .map(
+                  (hit) =>
+                    `- ${hit.title} [notes/${hit.noteFile}] (${hit.project || "unknown"}) · ${hit.scope} · ${hit.date}${hit.historical ? " · historical precedent (not current authority)" : ""}${hit.retired ? " · retired" : ""}\n  ${hit.excerpt}`,
+                )
                 .join("\n")}`,
         );
       }
-
       if (source === "sessions" || source === "both") {
         const hits = await searchAstraSessions(deps.sessionsDir, params.query, {
           full: params.full,
           limit,
           maxAgeDays: deps.maxSessionAgeDays(),
           projectId,
-          recallScope,
+          recallScope: scope,
+          excludeSession,
         });
+        if (signal?.aborted) throw new Error("Pocket recall cancelled");
         sections.push(
           hits.length === 0
             ? "Past astra sessions: no matches."
-            : `Past astra sessions (${hits.length}):\n${hits
-                .map((h) => `- [${h.kind}] ${h.timestamp} (${h.project})${recallScope === "all" && resolveProjectIdentity(h.project) !== projectId ? " · cross-repository precedent" : ""}\n  ${h.excerpt}`)
+            : `Past astra sessions (${hits.length}) — historical precedent, not current authority:\n${hits
+                .map(
+                  (hit) =>
+                    `- [${hit.kind}] ${hit.timestamp} (${hit.project}) · session ${hit.sessionId}\n  ${hit.excerpt}`,
+                )
                 .join("\n")}`,
         );
       }
-
       return textResult(sections.join("\n\n"));
     },
   });

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

@@ -34,7 +34,7 @@ display, pack, and posture fields are supplied by runtime normalization.
 | `ask` | human prompt; unattended calls block-and-log | deny |
 | `auto` | model first, then human/block fallback | deny |
 
-`gatedTools` is a global exact-name list and defaults to empty. Non-Bash tools absent from the list bypass Clearance analysis and policy entirely, execute, and receive an audit entry marked as an allow/bypass. There are no wildcards or future-tool opt-ins, and `bash` cannot be listed. Bash remains fully gated. This intentionally makes typed edit/read protections opt-in and is a published behavioral break for the next minor release.
+`gatedTools` is a global exact-name list and defaults to empty. Non-Bash tools absent from the list bypass Clearance analysis and policy entirely, execute, and receive an audit entry marked as an allow/bypass. There are no wildcards or future-tool opt-ins, and `bash` cannot be listed. Bash remains fully gated. Typed edit/read protections are opt-in.
 
 `unknownToolPosture` remains a config-file-only knob and applies only to an opted-in non-Bash tool that has no registered analyzer. It defaults to `"allow"`; it does not re-gate tools absent from `gatedTools`. Setting it to `"review"` or `"deny"` tightens opted-in unknown tools. The sealed floor and all active user/shipped deny rules run in every mode.
 
@@ -71,7 +71,7 @@ The reviewer settings selector exposes `promptPosture` and `model` interactively
 
 ## Packs
 
-The baseline is always the old default pack set plus `bash.network.read`, `pi.extension.network-research`, and `pi.home.safe`. Mode never changes baseline activation. Package packs remain available until explicitly enabled through `packEnablement.enabledPackagePacks`; user-owned config packs can be disabled with `disabledConfigPacks`.
+The built-in baseline is described in [RULE_PACKS.md](RULE_PACKS.md#baseline), including `bash.network.read`, `pi.extension.network-research`, and `pi.home.safe`. Mode never changes baseline activation. Package packs remain available until explicitly enabled through `packEnablement.enabledPackagePacks`; user-owned config packs can be disabled with `disabledConfigPacks`.
 
 ## Commands
 
@@ -81,4 +81,4 @@ The baseline is always the old default pack set plus `bash.network.read`, `pi.ex
 - `/clearance status`, `/clearance packs`, `/clearance scope`, `/clearance tune`, `/clearance why` — unchanged surfaces with mode/baseline vocabulary. Scope management also supports `scope agent-support add|remove <path>` and `scope agent-support-defaults <on|off>`.
 - `/clearance allow <plain language>` or `/clearance allow` — hand an agent-authored structural allow request to the shared proposal card. Accepted rules land in the user-global pack; this command adds no separate config surface.
 
-`/clearance profile` and `/clearance auto` are removed with no aliases. The next minor release must call out the non-Bash default bypass and the typed-tool protection break.
+`/clearance profile` and `/clearance auto` are unsupported and have no aliases.

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

@@ -2,7 +2,7 @@
 
 This guide is for people changing Pi Clearance itself.
 
-> The pre-public command surface is `/clearance`; removed commands and aliases are not preserved.
+> The command surface is `/clearance`; unsupported commands have no compatibility aliases.
 
 For product behavior, start with [README.md](../README.md) and [USER_GUIDE.md](USER_GUIDE.md). For design intent, read the foundation docs linked at the end of this file.
 
@@ -127,7 +127,7 @@ package README snippets.
 | `src/skill/clearance-tune/` | internal tune helper harness plus display-only structured proposal presentation seam |
 | `src/skill/clearance-*/` | thin agent guidance that points to canonical docs |
 | `test/` | unit, fixture, replay, runtime, and skill tests |
-| `.work/` | Workbench state (active items, backlog, conventions) |
+| [Repository `.work/`](../../../.work/) | Workbench state (active items, backlog, conventions) |
 
 ## Settings command surface and dispatcher seam
 
@@ -262,23 +262,22 @@ Public docs should stay practical and low-hype:
 
 The root README and these reference docs are user/developer docs. The foundation docs remain the design source of truth.
 
-## Agile-workflow substrate
+## Contributor workflow
 
-Work is tracked in `.work/` as plain markdown items: `active/` for in-flight
-epics/features/stories, `backlog/` for parked ideas, and `CONVENTIONS.md` for
-project behavior (tags, verification commands, body discipline). Read item
-files directly; there is no separate query binary.
-
-Before design, implementation, or review work, read `.work/CONVENTIONS.md` and
-the relevant `docs/` foundation docs.
+Follow the repository's [AGENTS.md](../../../AGENTS.md) and
+[Workbench conventions](../../../.work/CONVENTIONS.md) for work tracking,
+verification, and review.
 
 ## Foundation docs
 
-- [VISION.md](VISION.md) — product direction and open questions.
+- [VISION.md](VISION.md) — product direction.
 - [SPEC.md](SPEC.md) — behavior contract.
 - [ARCHITECTURE.md](ARCHITECTURE.md) — module boundaries.
 - [PRINCIPLES.md](PRINCIPLES.md) — safety and execution rules.
+
+## Focused references
+
 - [RULE_PACKS.md](RULE_PACKS.md) — shipped pack intent.
 - [PACK_AUTHORING.md](PACK_AUTHORING.md) — data-pack, TypeScript-pack, and package distribution guidance.
 - [REVIEWER_PROMPTS.md](REVIEWER_PROMPTS.md) — prompt and reviewer contract.
-- [REFERENCE_PATTERNS.md](REFERENCE_PATTERNS.md) — reference patterns from earlier captures.
+- [REFERENCE_PATTERNS.md](REFERENCE_PATTERNS.md) — policy-corpus vocabulary, command-family lessons, and capture provenance; not an implementation-pattern catalog or foundation.

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

@@ -305,11 +305,11 @@ is not covered makes a project-local allow return `false`. For `none-in` without
 `deny > review > allow` — so a `review` rule for `mkdir -m` and a sealed-floor `deny` for
 `sudo` still win over a matching path-scoped allow.
 
-The runtime enrichment seam supplies cwd and project scope only; `homeDirectory` plumbing is
-tracked separately. As a result a runtime `~/...` operand stays `scope: "unknown"` and fails
-closed rather than resolving to `home` — this is safe current behavior, not a historical aside,
-and it causes extra review, never an unsafe allow. Supplying `homeDirectory` at the runtime
-seam is the follow-up that lets `~/...` classify as `home`.
+Runtime enrichment receives cwd, project scope, and the resolved `homeDirectory` when
+available. Supported unquoted `~/...` operands resolve lexically against that home before
+scope classification; the winning scope still follows configured precedence, so it is not
+necessarily `home`. Without a usable home directory, these operands remain `unknown` and
+cannot satisfy a constructive allow.
 
 ## Compound shell matchers
 

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

@@ -56,8 +56,7 @@ the host approval boundary. Global `gatedTools` is an exact-name opt-in list wit
 wildcards or future-tool consent; Bash is always fully gated and cannot be listed. An
 opted-in tool without a registered analyzer uses `unknownToolPosture`, which defaults to
 `"allow"` and may be tightened to `"review"` or `"deny"`. The posture does not apply to
-absent names, and the next minor release must communicate this intentional typed-tool
-protection break.
+absent names.
 
 **Implication:** the interpreter must be pure and total for gated calls: every analyzed
 or opted-in unknown input returns `allow`, `deny`, or `review` with a reason; bypasses are

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

@@ -2,11 +2,11 @@
 
 ## Purpose statement
 
-This document is the durable bridge from two reference sources into the clean
-pi-clearance product:
+This policy-corpus reference preserves vocabulary, command-family lessons, and
+provenance from two sources:
 
 - the local `pi-config` clearance proof of concept; and
-- the old fork-shaped permission-system scaffold currently being retired.
+- a fork-shaped permission-system scaffold.
 
 These sources are **command-pattern, fixture-vocabulary, package-shape, and
 tune-report inspiration only**. They are not runtime architecture for
@@ -252,10 +252,9 @@ Additional shape notes:
 
 ## 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.
+The old fork `package.json` supplies package-shape reference facts only. Its name,
+version, and description do not define Pi Clearance's product identity; the current
+package manifest owns that metadata.
 
 Package-shape facts to carry forward:
 
@@ -268,14 +267,10 @@ Package-shape facts to carry forward:
   dependency shape.
 - Node engine: `node >=22.18`, matching the Pi host runtime expectation. Pi loads the package's TypeScript extension entrypoint directly.
 
-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.
+The old fork exports, files list, schemas, config examples, permission-system keywords,
+and extra permission-manager package surface are not behavior contracts. Package metadata
+must follow the current product boundaries in [VISION.md](VISION.md),
+[SPEC.md](SPEC.md), and [ARCHITECTURE.md](ARCHITECTURE.md), not the reference scaffold.
 
 ## Do-not-port architecture bullets
 
@@ -329,7 +324,6 @@ categories the downstream fixture harness must preserve:
   `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.
+These categories describe reference-corpus coverage, not the product's policy outcomes.
+Corpus maintenance should preserve their representation; the current packs and core
+interpreter determine which cases become allow, review, or deny.

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

@@ -14,14 +14,14 @@ Pi Clearance is a Pi extension that structurally analyzes tool calls, evaluates
 - 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. Clearance defines no npm install lifecycle hooks and package installation never reads or writes user config.
 - Global and project config written through Clearance is sparse: `version` plus recursively retained non-default user choices. Defaults remain runtime-only. Invalid or obsolete files fail strict validation and runtime falls back to floor-only policy; package installation does not migrate them.
-- 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.
+- Unsupported config keys fail strict schema validation; there are no translators or aliases for removed keys. Executable TypeScript rule modules are never loaded.
 - The native engine is distributed as prebuilt Node-API artifacts for Linux x64 glibc, Linux arm64 glibc, macOS x64, macOS arm64, and Windows x64 MSVC. Windows ARM is not a release target. Installation never runs Cargo; a missing or unsupported artifact fails closed.
 
 ## Config
 
 `GlobalConfigSchema` contains `version`, `mode` (default `ask`), exact `gatedTools` (default empty; Bash and wildcards rejected), `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 complete schemas normalize runtime views; `src/config/persistence.ts` owns the sparse persisted representation.
 
-The former policy posture system and reviewer `enabled`/`mode` fields are removed. Reviewer model pinning and the compact selector/toggle settings controls remain confirm-backed. The separate reviewer consent schema/file is removed; explicit `mode: "auto"` is the acknowledgment. The next minor release must communicate the intentional typed-tool bypass behavior break.
+Reviewer model pinning and the compact selector/toggle settings controls are confirm-backed. Explicit `mode: "auto"` is the acknowledgment for model review; no separate reviewer consent file is read or written. [CONFIGURATION.md](CONFIGURATION.md) lists unsupported legacy keys and their strict-validation behavior.
 
 ## Native boundary
 
@@ -39,8 +39,8 @@ corpus acquisition, proposal heuristics, presentation, and Pi I/O.
 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.
+The baseline comprises the built-in packs described in [RULE_PACKS.md](RULE_PACKS.md#baseline), including `bash.network.read`, `pi.extension.network-research`, and `pi.home.safe`. Individual pack ids flow into provenance; no posture pseudo-pack exists.
 
 ## Commands
 
-`/clearance`, `/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.
+`/clearance`, `/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 unsupported and have no aliases.

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

@@ -34,7 +34,7 @@ Global and project config written through Clearance is persisted sparsely. Packa
 /clearance allow
 ```
 
-Bare `/clearance` opens guided setup. `/clearance mode` without an argument still opens settings. `/clearance profile` and `/clearance auto` were removed before release. There are no aliases. Settings mutations require interactive confirmation and write only user-owned config.
+Bare `/clearance` opens guided setup. `/clearance mode` without an argument still opens settings. `/clearance profile` and `/clearance auto` are unsupported and have no aliases. Settings mutations require interactive confirmation and write only user-owned config.
 
 ## Allow a command family
 
@@ -59,14 +59,13 @@ Review surfaces speak plain language. The human approval card shows what the com
 
 The settings control center uses compact selector/toggle rows. It exposes mode, reviewer model and evidence posture, scope preset and unknown-path behavior, a pack explorer, exact gated non-Bash tools, and Stream briefing preferences (note mode, model label, accent). Every mutation uses confirmation, the config planner, atomic write, reload, and policy invalidation. Advanced context, budget, escalation, prompt appends, and overrides remain config-file settings; status names their customization categories without dumping values.
 
-The baseline is broad by default: it includes the former default pack set plus expanded inspection, shell-builtin and system/service reads, bounded development verification, network reads, typed network research, non-secret home and agent-support typed Pi reads, and safe-home typed Pi mutations. Literal project/temp output redirects and `/dev/null` are eligible, while dynamic, `.git`, unknown-fd, and network output redirects remain review-gated. Installed package packs are merely available until explicitly enabled by user-owned config.
+The baseline is broad by default: the [built-in packs](RULE_PACKS.md#baseline) cover inspection, shell-builtin and system/service reads, bounded development verification, network reads, typed network research, non-secret home and agent-support typed Pi reads, and safe-home typed Pi mutations. Literal project/temp output redirects and `/dev/null` are eligible, while dynamic, `.git`, unknown-fd, and network output redirects remain review-gated. Installed package packs are merely available until explicitly enabled by user-owned config.
 
 ## Safety model
 
 - Parsed structure, not raw shell text, drives policy.
 - Non-Bash tools bypass Clearance unless their exact name appears in global `gatedTools` (default `[]`); Bash is always gated and cannot be listed.
 - Opted-in unknown tools follow `unknownToolPosture` (default `allow`). Wildcards and future-tool opt-in are not supported.
-- This default typed-tool bypass is an intentional published behavior break and must be called out in the next minor release.
 - Parser uncertainty and unsupported forms fail closed to review.
 - Model decisions resolve one call and never create permanent policy.
 - Tune mode proposes user-approved inspectable data-pack changes after replay and adversarial evidence; executable TypeScript rule modules are not supported.

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

@@ -20,4 +20,4 @@ The sealed floor always wins. Invalid config fails closed to floor-only policy.
 
 ## Trust and growth
 
-User-owned global/project config may widen policy. Repository policy and installed packs cannot silently widen it. Persisted settings written through Clearance contain only non-default choices, while runtime normalization supplies the rest. Package installation neither changes config nor enables packs. Tune replay, adversarial checks, explicit confirmation, and post-write validation make policy growth auditable. The default non-Bash bypass is an intentional published behavioral break requiring next-minor release communication.
+User-owned global/project config may widen policy. Repository policy and installed packs cannot silently widen it. Persisted settings written through Clearance contain only non-default choices, while runtime normalization supplies the rest. Package installation neither changes config nor enables packs. Tune replay, adversarial checks, explicit confirmation, and post-write validation make policy growth auditable.

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/README.md

@@ -33,7 +33,7 @@ Run them in joined or detached mode, steer them while active, resume retained se
 ## Install
 
 This branch is locally qualified but unpublished, so it cannot be installed from npm yet.
-After an explicitly authorized publication, the package name will be `@nklisch/pi-subagents` and its immutable registry receipt will be recorded in [Fork maintenance](./docs/FORK-MAINTENANCE.md).
+The published package is `@nklisch/pi-subagents`. [Fork maintenance](./docs/FORK-MAINTENANCE.md) records its provenance, release policy, and compatibility commitments.
 
 Load it directly for development:
 
@@ -458,7 +458,7 @@ It never throws — all error conditions produce a `console.warn` and return `{}
 
 This extension is a minimal, composable core: it owns agent spawning, execution, and result retrieval, and exposes a typed `SubagentsService` plus lifecycle events that other extensions build on.
 
-See [`docs/architecture/architecture.md`](./docs/architecture/architecture.md) for the full architecture document — design principles, domain decomposition, module dependency flow, Mermaid diagrams, and the improvement roadmap.
+See [`docs/architecture/architecture.md`](./docs/architecture/architecture.md) for design principles, domain ownership, lifecycle and service contracts, and module dependency diagrams.
 
 ## Relationship to upstream
 

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/VISION.md

@@ -28,9 +28,8 @@ model, exact effective thinking level, active or final runtime, run id, delivery
 mode, and terminal reason when one exists. Parent-only lifecycle tools are
 centrally registered and removed from child tool definitions, preventing
 recursive orchestration while preserving ordinary inherited extension tools.
-The package excludes the retired experimental editors, wizards, and bespoke
-conversation viewer from the import branch (see ADR 0004 for the UI direction
-history).
+The package excludes agent-definition editors, wizards, and a bespoke
+conversation viewer; ADR 0004 defines the narrow operator UI contract.
 
 ## Fork posture