@unbrained/pm-cli 2026.6.5 → 2026.6.7

package/docs/ONBOARDING.md

@@ -0,0 +1,165 @@
+# Onboarding
+
+Use this guide to become productive in your first two hours without breaking release flow or tracker integrity.
+
+## Agent Quick Context
+
+- Bootstrap with `npm install -g .`, verify toolchain versions, then run `pnpm build`.
+- Use `pm context` + `pm search` before creating any new item.
+- Claim before substantial edits and link files/docs/tests as you go.
+- Run sandbox-safe tests before closing items.
+- Never hand-edit tracker records or generated changelog output.
+
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon), [pm-oh5h](../.agents/pm/tasks/pm-oh5h.toon), [pm-10ml](../.agents/pm/stories/pm-10ml.toon).
+
+## Prerequisites
+
+- Node.js 20 or newer
+- pnpm 10 or newer
+- Git + GitHub CLI (`gh`) authenticated for this repository
+
+## First-Time Bootstrap (Real Repository Work)
+
+Run from the repository root:
+
+```bash
+npm install -g .
+pm --version
+node -v
+pnpm -v
+pnpm build
+export PM_AUTHOR="<stable-agent-id>"
+```
+
+For real repository tracking, do not set `PM_PATH`.
+
+## First Read Path
+
+Use progressive disclosure:
+
+```bash
+pm context --limit 10
+pm search "<request keywords>" --limit 10
+pm list-open --limit 20
+pm list-in-progress --limit 20
+pm install guide-shell --project
+pm guide workflows
+```
+
+Then use:
+
+- [Agent Guide](AGENT_GUIDE.md)
+- [Command Reference](COMMANDS.md)
+- [Testing](TESTING.md)
+- [Releasing](RELEASING.md)
+
+## Safe Local Verification
+
+Use sandbox-safe wrappers for test execution:
+
+```bash
+node scripts/run-tests.mjs test
+node scripts/run-tests.mjs coverage
+```
+
+Standard local gate set:
+
+```bash
+pnpm build
+pnpm typecheck
+node scripts/run-tests.mjs coverage
+pnpm quality:docs-skills
+pm validate --check-resolution --check-history-drift
+```
+
+## Real Tracker Workflow (Canonical Loop)
+
+1) Orient and dedupe
+
+```bash
+pm context --limit 10
+pm search "<keywords>" --limit 10
+pm list-open --limit 20
+pm list-in-progress --limit 20
+```
+
+2) Claim and start
+
+```bash
+pm claim <id>
+pm update <id> --status in_progress --message "Start implementation"
+```
+
+3) Link execution context while editing
+
+```bash
+pm files <id> --add path=src/...,scope=project,note="implementation scope"
+pm docs <id> --add path=docs/...,scope=project,note="user-facing behavior"
+pm test <id> --add command="node scripts/run-tests.mjs test -- tests/unit/...",scope=project,timeout_seconds=240
+```
+
+4) Record progress
+
+```bash
+pm comments <id> "Progress update and rationale."
+pm notes <id> --add "Design tradeoff."
+pm learnings <id> --add "Durable lesson."
+```
+
+5) Verify, close, and release
+
+```bash
+pm test <id> --run --progress
+pm comments <id> "Evidence: linked tests and gates passed."
+pm close <id> "Acceptance criteria met; verification passed." --validate-close warn
+pm release <id>
+```
+
+## Release Overview
+
+- Daily release prep runs via `.github/workflows/auto-release.yml`.
+- Tag-triggered publish runs via `.github/workflows/release.yml`.
+- `CHANGELOG.md` is generated by `pm-changelog` and must stay package-generated.
+
+Local parity:
+
+```bash
+pnpm release:pipeline:dry-run
+pnpm release:pipeline
+```
+
+## Hard Never-Do List
+
+- Do not hand-edit `CHANGELOG.md` (use `pnpm changelog:pm` only).
+- Do not run manual `npm publish` for this project.
+- Do not set `PM_PATH` for real repository mutations.
+- Do not edit `.agents/pm/**` files directly; mutate through `pm` commands.
+- Do not bypass governance with destructive git commands unless explicitly approved.
+
+## Diagnostics and Recovery
+
+```bash
+pm health --check-only
+pm validate --check-resolution --check-history-drift
+pm normalize --dry-run --json
+pm package doctor --project --detail summary
+pm contracts --command <command> --flags-only --json
+```
+
+If history drift is reported:
+
+```bash
+pm history-repair <id> --dry-run
+pm history-repair <id>
+```
+
+If sensitive content is found in history:
+
+```bash
+pm history-redact <id> --literal "<secret>" --replacement "[redacted]" --dry-run
+pm history-redact <id> --literal "<secret>" --replacement "[redacted]"
+```
+
+## Private Operations Boundary
+
+Keep credentials, host-specific runbooks, internal topology, and raw private reliability logs out of tracked docs and package output. Keep those details in local, ignored operations notes.

package/docs/QUICKSTART.md

@@ -11,7 +11,7 @@ Use this page to get from a clean repository to a tracked, verified item.
 - Close only after evidence is recorded.
 - Use `pm install guide-shell --project` before `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Install
 
@@ -31,7 +31,7 @@ pm upgrade --cli-only
 For one-off use:
 
 ```bash
-npx @unbrained/pm-cli --help
+npx --yes @unbrained/pm-cli@latest --help
 ```
 
 Optional first-party packages are installable during init or on demand:

package/docs/README.md

@@ -20,15 +20,18 @@ pm guide release --json
 | Reader | First page | Then read |
 |--------|------------|-----------|
 | New user | [Quickstart](QUICKSTART.md) | [Command Reference](COMMANDS.md) |
+| New maintainer | [Onboarding](ONBOARDING.md) | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md), [Releasing](RELEASING.md) |
 | Coding agent | [Agent Guide](AGENT_GUIDE.md) | [Configuration](CONFIGURATION.md), then command help |
 | Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md) |
 | Package author | [Packages and Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
 | Codex user | [Codex Plugin](CODEX_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
+| Claude Code user | [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
 | Machine client | `pm contracts --json` | [Command Reference](COMMANDS.md#machine-contracts), optionally `pm install guide-shell --project && pm guide commands` |
 
 ## Documentation Map
 
 - [Quickstart](QUICKSTART.md) - install, initialize, create, claim, link, test, close.
+- [Onboarding](ONBOARDING.md) - first-two-hours maintainer and contributor setup.
 - [Agent Guide](AGENT_GUIDE.md) - canonical agent loop, tracker linking, and token-minimal command choices.
 - [Command Reference](COMMANDS.md) - command families with examples and when to use each family.
 - [Configuration](CONFIGURATION.md) - settings, storage formats, output, search, validation, and environment variables.
@@ -37,6 +40,7 @@ pm guide release --json
 - [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
 - [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
+- [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) - native Claude Code plugin architecture and install flow.
 - [Releasing](RELEASING.md) - maintainer release checklist and failure handling.
 - [starter extension](examples/starter-extension/README.md) - compact extension scaffold reference.
 
@@ -71,11 +75,15 @@ Community files:
 
 ## Tracker References
 
-This documentation structure is tracked through:
+Current documentation structure work is tracked through:
 
-- [pm-3042](../.agents/pm/epics/pm-3042.toon)
-- [pm-r9gu](../.agents/pm/features/pm-r9gu.toon)
-- [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon)
+- [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon)
+
+Legacy documentation baseline references (closed):
+
+- [pm-3042](../.agents/pm/epics/pm-3042.toon) (closed)
+- [pm-r9gu](../.agents/pm/features/pm-r9gu.toon) (closed)
+- [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon) (closed)
 
 When changing docs, link files back to the active item:
 

package/docs/RELEASING.md

@@ -12,7 +12,7 @@ For local progressive-disclosure routing, install `guide-shell` with `pm install
 - Run local parity gates before pushing release tags.
 - Use `pm guide release --json` for machine-readable release docs routing after `guide-shell` is installed.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Version Policy
 
@@ -74,6 +74,41 @@ The pipeline performs:
 
 The generated changelog includes clickable pm item links to the tracked `.toon` files. Missing release evidence should be fixed in pm item history, not by hand-editing `CHANGELOG.md`.
 
+## Changelog Classification (Contributor-Facing)
+
+`pnpm changelog:pm` routes closed pm items into keep-a-changelog sections using `pm-changelog` classification logic. Use explicit type/tag metadata when you want deterministic section routing.
+
+Signal tiers:
+
+- **Strong signals**: item `type` + `tags`
+- **Weak signal**: item `title` (after stripping CLI-flag-like tokens such as `--add`)
+
+Category precedence (first matching bucket wins):
+
+| Priority | Category | Trigger terms (from strong + weak signals unless noted) |
+|---|---|---|
+| 1 | `Security` | `security`, `cve`, `vulnerability` |
+| 2 | `Deprecated` | `deprecated`, `deprecation` |
+| 3 | `Removed` | `removed`, `remove`, `deleted`, `delete` |
+| 4 | `Fixed` | `fix`, `fixed`, `bug`, `bugfix`, `hotfix`, `regression` |
+| 5 | `Added` | `feature`, `feat`, `added`, `add`, `new` |
+| 6 | `Changed` | strong-signal `change`, `changed`, `refactor`, `update`, `updated`, `improve`; for non-bug-like types only, title fallback is also used |
+| 7 | `Other` | no classifier match |
+
+Bug-like default:
+
+- Items with type `Issue`, `Bug`, `Bugfix`, or `Defect` default to `Fixed` unless a higher-priority category already matched.
+- This bug-like default runs before title-only `Changed` fallback to avoid misrouting command-name issue titles (for example "`pm update ...`" issue reports).
+
+Practical examples:
+
+- `Issue` + title `pm update --add-tags fails` -> `Fixed`
+- `Task` + tag `refactor` -> `Changed`
+- `Feature` + tag `security` -> `Security`
+- `Issue` + tag `feature` -> `Added` (explicit stronger signal beats default)
+
+If a changelog routing rule appears incorrect, fix classifier behavior in the `pm-changelog` package/repo and then consume the updated package here. Do not patch generator internals in this repository.
+
 ## Local Release Parity Checklist
 
 1. Confirm or compute the version.

package/docs/SDK.md

@@ -66,11 +66,13 @@ Command/action contract exports:
 Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 
 - `activateExtensionForTest`
+- `assertPackageManifest`
 - `assertRegisteredCommandContract`
 - `assertRegisteredHook`
 - `assertRegisteredSearchProvider`
 - `assertRegisteredImporter`
 - `assertRegisteredExporter`
+- `assertRegisteredVectorStoreAdapter`
 
 Commander option contract exports:
 
@@ -152,6 +154,28 @@ When a package-owned command is missing at runtime, CLI usage guidance now inclu
 
 Package installs currently activate only extension resources. Additional package resource kinds (`docs`, `examples`) are metadata-first and available through package manifest/catalog inspection.
 
+Package tests can assert the normalized manifest through the SDK without
+reimplementing resource sorting, alias normalization, or package.json parsing:
+
+```ts
+import {
+  assertPackageManifest,
+  readPmPackageManifest,
+} from "@unbrained/pm-cli/sdk";
+
+const manifest = await readPmPackageManifest(packageRoot);
+
+assertPackageManifest(manifest, {
+  packageName: "@acme/pm-incident-workflow",
+  aliases: ["incident-workflow"],
+  resources: {
+    extensions: ["extensions/incident-workflow"],
+    docs: ["README.md"],
+    examples: ["examples/basic.md"],
+  },
+});
+```
+
 For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat and avoids advanced schema constructs such as root `oneOf`.
 
 ## Capability Requirements
@@ -332,6 +356,7 @@ import {
   assertRegisteredExporter,
   assertRegisteredImporter,
   assertRegisteredSearchProvider,
+  assertRegisteredVectorStoreAdapter,
 } from "@unbrained/pm-cli/sdk/testing";
 
 assertRegisteredImporter(activation.registrations, { importer: "jsonl" });
@@ -340,6 +365,33 @@ assertRegisteredExporter(activation.registrations, {
   extensionName: "my-ext",
 });
 assertRegisteredSearchProvider(activation.registrations, { provider: "semantic-local" });
+assertRegisteredVectorStoreAdapter(activation.registrations, { adapter: "pinecone" });
+```
+
+Use `assertRegisteredVectorStoreAdapter` for packages that call
+`registerVectorStoreAdapter`. It proves the semantic-storage integration is
+present without importing private registry internals or configuring a live
+vector store in unit tests.
+
+Assert package-owned schema registrations the same way. This lets packages prove
+their custom project-management primitives without importing private registry
+types or reading generated schema files:
+
+```ts
+import {
+  assertRegisteredItemField,
+  assertRegisteredItemType,
+} from "@unbrained/pm-cli/sdk/testing";
+
+assertRegisteredItemField(activation.registrations, {
+  field: "severity",
+  extensionName: "incident-ext",
+  type: "string",
+});
+assertRegisteredItemType(activation.registrations, {
+  itemType: "Incident",
+  folder: "incidents",
+});
 ```
 
 Hooks are surfaced via `activation.hooks` (an `ExtensionHookRegistry`), not the command
@@ -361,6 +413,12 @@ declares only the `hooks` capability and registers a default-inert `afterCommand
 hook, so package authors can copy a lifecycle pattern that does not write files,
 produce output, or alter command behavior.
 
+The bundled `pm-governance-audit` package is the governance hook exemplar. It
+combines package-owned commands with `onRead` and `onWrite` hooks, declares the
+`hooks` capability, and only writes a compact JSONL sidecar when
+`PM_GOVERNANCE_AUDIT_HOOK_LOG` is set. Use that pattern for audit/cache/telemetry
+packages that need file-level context without storing item bodies by default.
+
 `afterCommand` receives the command outcome plus an optional `affected` array for
 item mutations. Each affected entry is a compact command context:
 `id`, `op`, `item_type`, `previous_status`, `status`, `changed_fields`, and
@@ -500,6 +558,14 @@ embedding-backed providers (for example Ollama or a hosted model) implement
 `embed`/`embedBatch` on the same `SearchProviderDefinition` shape, and may also
 `registerVectorStoreAdapter` for a custom vector store.
 
+Optional advanced relevance hooks:
+
+- `queryExpansion` (or `query_expansion`) for `search.query_expansion.provider`
+- `rerank` for hybrid rerank candidates when `search.rerank.enabled=true`
+
+Both hooks are best-effort. If a hook throws or returns an invalid shape, core
+search degrades gracefully and emits warning codes instead of hard-failing.
+
 ## Robust Automation Pattern
 
 1. Read `PM_TOOL_ACTIONS` or `PM_TOOL_PARAMETERS_SCHEMA` for baseline static validation.

package/docs/TESTING.md

@@ -9,7 +9,7 @@ This page describes safe local tests, linked tests, coverage, and release-readin
 - Linked tests added through `pm test` should use sandbox-safe commands.
 - Run linked tests before closing the item that owns the work.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Standard Local Checks
 
@@ -132,6 +132,20 @@ pm validate --check-resolution --check-history-drift
 pm health --check-only
 ```
 
+When release readiness requires external GitHub security telemetry in addition to
+local checks, run:
+
+```bash
+gh issue list --state open --limit 100 --json number,title,updatedAt,url
+gh pr list --state open --limit 50 --json number,title,headRefName,reviewDecision,url
+gh api "repos/unbraind/pm-cli/dependabot/alerts?state=open&per_page=100"
+gh api "repos/unbraind/pm-cli/secret-scanning/alerts?state=open&per_page=100"
+gh api "repos/unbraind/pm-cli/code-scanning/alerts?state=open&per_page=100"
+```
+
+`code-scanning/alerts` can return `404 no analysis found` until at least one
+CodeQL run has completed.
+
 For documentation-only changes, at minimum run:
 
 ```bash
@@ -140,3 +154,21 @@ rg -n "forbidden-private-token-or-path" README.md docs
 ```
 
 Replace the placeholder pattern with the actual sensitive term being guarded in the current task.
+
+## Contract Snapshot Gate
+
+Tracked by [pm-d6kq](../.agents/pm/tasks/pm-d6kq.toon).
+
+`pm contracts --full --json` is a public machine-readable SDK and agent surface.
+Keep its committed golden snapshot current when command contracts, schemas,
+aliases, or extension-provided command contracts intentionally change:
+
+```bash
+pnpm build
+pnpm contracts:update
+pnpm contracts:check
+```
+
+CI runs `pnpm contracts:check` in the static gate. Snapshot diffs should be
+reviewed like an API change and paired with the package-owned changelog flow
+when the contract surface changes intentionally.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.6.5",
+  "version": "2026.6.7",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -13,6 +13,7 @@
     "url": "https://github.com/unbraind/pm-cli/issues"
   },
   "bin": {
+    "pm-cli": "dist/cli.js",
     "pm": "dist/cli.js",
     "pm-mcp": "dist/mcp/server.js"
   },
@@ -74,6 +75,9 @@
     "test:coverage": "node scripts/run-tests.mjs coverage",
     "quality:static": "node scripts/release/static-quality-gate.mjs",
     "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
+    "quality:docs-links": "node scripts/release/docs-skills-gate.mjs --links-only",
+    "contracts:update": "node scripts/contracts-snapshot.mjs --update",
+    "contracts:check": "node scripts/contracts-snapshot.mjs --check",
     "dogfood:package-first": "node scripts/dogfood-package-first.mjs",
     "smoke:external-packages": "node scripts/smoke-external-packages.mjs",
     "smoke:codex-plugin": "node scripts/smoke-codex-plugin-mcp.mjs",
@@ -129,7 +133,7 @@
   },
   "devDependencies": {
     "@sentry/cli": "^3.5.0",
-    "@types/node": "^25.9.1",
+    "@types/node": "^25.9.2",
     "@vitest/coverage-v8": "^4.1.8",
     "esbuild": "0.28.0",
     "tsx": "^4.22.4",

package/packages/pm-governance-audit/README.md

@@ -2,6 +2,20 @@
 
 First-party package that restores optional governance audit surfaces in bare-core `pm`.
 
+## Hooks
+
+The package also registers default-inert `onRead` and `onWrite` hooks as the
+first-party governance hook exemplar. Set `PM_GOVERNANCE_AUDIT_HOOK_LOG` to a
+JSONL sidecar path to capture compact read/write records:
+
+```bash
+PM_GOVERNANCE_AUDIT_HOOK_LOG=.pm-local/governance-hooks.jsonl pm update pm-demo --status closed
+```
+
+Records include `kind`, `path`, `scope`, and write metadata such as `op`,
+`item_id`, `item_type`, and `changed_fields`. They intentionally omit item
+bodies and full before/after snapshots.
+
 ## Commands
 
 - `pm dedupe-audit`

package/packages/pm-governance-audit/extensions/governance-audit/index.js

@@ -1,3 +1,5 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
 import {
   runCommentsAuditPackage,
   runDedupeAuditPackage,
@@ -9,9 +11,12 @@ export const manifest = {
   version: "0.1.0",
   entry: "./index.js",
   priority: 0,
-  capabilities: ["commands", "schema"],
+  capabilities: ["commands", "schema", "hooks"],
 };
 
+const HOOK_LOG_ENV = "PM_GOVERNANCE_AUDIT_HOOK_LOG";
+const createdHookLogDirs = new Set();
+
 const dedupeAuditFlags = [
   { long: "--mode", value_name: "value", value_type: "string", description: "Audit mode: title_exact|title_fuzzy|parent_scope." },
   { long: "--status", value_name: "value", value_type: "string", description: "Filter by status." },
@@ -105,10 +110,43 @@ function normalizeCommand() {
   };
 }
 
+function appendHookAuditRecord(kind, context) {
+  const logPath = process.env[HOOK_LOG_ENV]?.trim();
+  if (!logPath) {
+    return;
+  }
+  try {
+    const absoluteLogPath = path.resolve(logPath);
+    const logDir = path.dirname(absoluteLogPath);
+    if (!createdHookLogDirs.has(logDir)) {
+      mkdirSync(logDir, { recursive: true });
+      createdHookLogDirs.add(logDir);
+    }
+    const writeContext = kind === "on_write" ? context : undefined;
+    appendFileSync(
+      absoluteLogPath,
+      `${JSON.stringify({
+        kind,
+        path: context.path,
+        scope: context.scope,
+        op: writeContext?.op,
+        item_id: writeContext?.item_id,
+        item_type: writeContext?.item_type,
+        changed_fields: writeContext?.changed_fields,
+      })}\n`,
+      "utf8",
+    );
+  } catch {
+    // Best-effort sidecar logging must not interrupt core read/write flows.
+  }
+}
+
 export function activate(api) {
   api.registerCommand(dedupeAuditCommand());
   api.registerCommand(commentsAuditCommand());
   api.registerCommand(normalizeCommand());
+  api.hooks.onRead((context) => appendHookAuditRecord("on_read", context));
+  api.hooks.onWrite((context) => appendHookAuditRecord("on_write", context));
 }
 
 export default {

package/packages/pm-governance-audit/extensions/governance-audit/index.ts

@@ -1,4 +1,6 @@
-import type { CommandDefinition, ExtensionApi } from "../../../../src/sdk/index.js";
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import type { CommandDefinition, ExtensionApi, OnReadHookContext, OnWriteHookContext } from "../../../../src/sdk/index.js";
 import {
   runCommentsAuditPackage,
   runDedupeAuditPackage,
@@ -10,9 +12,12 @@ export const manifest = {
   version: "0.1.0",
   entry: "./index.js",
   priority: 0,
-  capabilities: ["commands", "schema"],
+  capabilities: ["commands", "schema", "hooks"],
 };
 
+const HOOK_LOG_ENV = "PM_GOVERNANCE_AUDIT_HOOK_LOG";
+const createdHookLogDirs = new Set<string>();
+
 const dedupeAuditFlags = [
   { long: "--mode", value_name: "value", value_type: "string", description: "Audit mode: title_exact|title_fuzzy|parent_scope." },
   { long: "--status", value_name: "value", value_type: "string", description: "Filter by status." },
@@ -106,10 +111,43 @@ function normalizeCommand(): CommandDefinition {
   };
 }
 
+function appendHookAuditRecord(kind: "on_read" | "on_write", context: OnReadHookContext | OnWriteHookContext): void {
+  const logPath = process.env[HOOK_LOG_ENV]?.trim();
+  if (!logPath) {
+    return;
+  }
+  try {
+    const absoluteLogPath = path.resolve(logPath);
+    const logDir = path.dirname(absoluteLogPath);
+    if (!createdHookLogDirs.has(logDir)) {
+      mkdirSync(logDir, { recursive: true });
+      createdHookLogDirs.add(logDir);
+    }
+    const writeContext = kind === "on_write" ? (context as OnWriteHookContext) : undefined;
+    appendFileSync(
+      absoluteLogPath,
+      `${JSON.stringify({
+        kind,
+        path: context.path,
+        scope: context.scope,
+        op: writeContext?.op,
+        item_id: writeContext?.item_id,
+        item_type: writeContext?.item_type,
+        changed_fields: writeContext?.changed_fields,
+      })}\n`,
+      "utf8",
+    );
+  } catch {
+    // Best-effort sidecar logging must not interrupt core read/write flows.
+  }
+}
+
 export function activate(api: ExtensionApi): void {
   api.registerCommand(dedupeAuditCommand());
   api.registerCommand(commentsAuditCommand());
   api.registerCommand(normalizeCommand());
+  api.hooks.onRead((context) => appendHookAuditRecord("on_read", context));
+  api.hooks.onWrite((context) => appendHookAuditRecord("on_write", context));
 }
 
 export default {

package/packages/pm-governance-audit/extensions/governance-audit/manifest.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
-  "capabilities": ["commands", "schema"],
+  "capabilities": ["commands", "schema", "hooks"],
   "manifest_version": 1,
   "pm_min_version": "2026.5.0",
   "activation": {

package/packages/pm-governance-audit/package.json

@@ -18,7 +18,8 @@
     "project-management",
     "governance",
     "audit",
-    "normalize"
+    "normalize",
+    "hooks"
   ],
   "pm": {
     "aliases": [
@@ -34,7 +35,8 @@
       "tags": [
         "governance",
         "audit",
-        "normalize"
+        "normalize",
+        "hooks"
       ],
       "links": {
         "docs": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-governance-audit#readme",