@stravica-ai/digital-operator-pa 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,170 @@
+# @stravica-ai/digital-operator-pa
+
+The public, single-bundled npm surface of the engineering-PA platform.
+
+One install gives operators every CLI bin and bundles the internal platform
+code into a self-contained tarball.
+
+## Install
+
+```sh
+pnpm add @stravica-ai/digital-operator-pa
+```
+
+Requires Node 24+. See [`../../docs/installing.md`](../../docs/installing.md)
+for the GitHub Packages `~/.npmrc` setup (PAT with `read:packages` scope).
+
+## Bins
+
+The wrapper exposes the platform's operator-facing CLIs:
+
+| Bin               | What it does                                                |
+|-------------------|-------------------------------------------------------------|
+| `pa`              | Top-level operator CLI (`pa status`, `pa workspace`, …)     |
+| `desk`            | Task + project queries                                      |
+| `launch`          | Boot a scoped agent instance bound to an identity and task  |
+| `sync`            | Per-host single-writer git sync                             |
+| `secrets`         | SOPS+age secrets vault management                           |
+| `scheduler`       | Scheduling primitives (cron / launchd install + verify)     |
+| `smoke`           | Fresh-clone smoke suite                                     |
+| `distill`         | Librarian distillation sweep                                |
+| `memory-sync`     | PA-memory cache mirror                                      |
+| `migrate-inspect` | Host inspection for migration planning                      |
+| `pa-init`         | Scaffolder for a new operator repo                          |
+| `slice`           | Operator profile slice generator (compact boot context)     |
+| `pa-coordinator-hook` | Claude Code `PreToolUse` hook — three-tier coordinator-mode tool policy |
+
+Each bin runs `--help` and exits 0 to confirm the install is healthy.
+
+`pa-coordinator-hook` is the exception to "operator-facing CLI" above — it's
+a hook binary invoked by Claude Code itself, not run by hand. See
+[`../cli/docs/coordinator-hook.md`](../cli/docs/coordinator-hook.md) for the
+full contract, the settings.json wiring snippet, and the per-PA overlay
+mechanism.
+
+### Starting a PA session
+
+After `pa-init` lays down an operator repo, kick off your PA with:
+
+```sh
+cd <operator-repo>
+pa session
+```
+
+`pa session`:
+
+1. Resolves the operator repo root (`$DAVE_REPO_ROOT` → `$PA_REPO_ROOT`
+   → `.git`-walk → CWD).
+2. Reads `operator/config/preferences.json` and pulls out `paName`.
+3. Chdirs to `agents/<paName>/`.
+4. Execs `claude --dangerously-skip-permissions`, inheriting stdio.
+
+For muscle memory, alias it to your PA's name:
+
+```sh
+alias dave='pa session'    # add to ~/.zshrc / ~/.bashrc
+```
+
+Now `dave` alone boots a session. Errors (missing preferences, missing
+agent directory, `claude` not on `PATH`) exit non-zero with a concrete
+remediation message.
+
+## Programmatic surface
+
+```js
+import { name, version, bins, bundled, describe } from '@stravica-ai/digital-operator-pa';
+
+console.log(describe());
+// → { name: '@stravica-ai/digital-operator-pa', version: '0.1.1', bins: [...], bundled: [...] }
+```
+
+For richer in-process composition (importing internal modules directly),
+consumers can reach into the bundled `dist/` tree — but the bin shims are
+the supported contract.
+
+## Single-bundled-publish model (approach A2)
+
+`@stravica-ai/digital-operator-pa` ships **one tarball** that contains:
+
+```
+package/
+  package.json           # bin map, exports, publishConfig
+  index.mjs              # public ESM surface
+  bin/                   # bin shims — thin wrappers over dist/.../cli.mjs
+  dist/                  # bundled internal packages (built by build.mjs)
+    engineering-pa-core/
+    engineering-pa-runbook/
+    engineering-pa-cli/
+    engineering-pa-migrate-inspect/
+    engineering-pa-workspace/
+    engineering-pa-scaffold/
+    engineering-pa-librarian/
+    engineering-pa-types-engineering/
+    engineering-pa-core-extensions-atlassian/
+    engineering-pa-core-extensions-n8n/
+  README.md
+  LICENSE
+```
+
+`build.mjs` is the pre-pack bundler. It:
+
+1. Copies each internal workspace package's source into `dist/<short-name>/`,
+   skipping `test/`, `node_modules/`, `dist/`, IDE state.
+2. Rewrites every `'@stravica-ai/engineering-pa-*'` string literal inside copied
+   `.mjs` files to a relative path within `dist/`, so cross-package imports
+   resolve without any runtime npm-name lookup.
+
+Hooked via `prepack`, so `pnpm pack` and `pnpm publish` always run it first.
+Also exposed as `pnpm --filter @stravica-ai/digital-operator-pa run build`.
+
+### Bundled docs, knowledge, roles, and schemas
+
+The `dist/` tree carries each internal package's non-code assets too — for
+core that means `docs/`, `knowledge/` (bucket scaffolds), `roles/`, and
+`schema/` all ship inside the tarball.
+
+Platform documentation refers to these assets by **symbolic package path**
+(e.g. `@stravica-ai/engineering-pa-core/docs/pa-operating-model.md`). The
+internal packages are `private: true` and never installed under their own
+names, so that path does not exist in `node_modules` verbatim. In an operator
+install it resolves inside the wrapper's bundle:
+
+```
+@stravica-ai/engineering-pa-<pkg>/<subpath>
+  → node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-<pkg>/<subpath>
+```
+
+For example, `@stravica-ai/engineering-pa-core/knowledge/content-voice/` lives at
+`node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-core/knowledge/content-voice/`
+relative to the operator repo root.
+
+**Why A2 over A1.** A1 publishes each internal package separately and the
+wrapper depends on them via the registry. That requires every internal to be
+public (or at least published with auth-token coverage), multiplies the
+operator-side auth surface, and creates N-tarballs-per-release coordination.
+A2 keeps internals `private: true`, ships one auditable artefact, and matches
+the v0.1 brief explicitly. Split to A1 later only if multi-version internal
+publishing becomes a real need.
+
+## Scripts
+
+```sh
+pnpm --filter @stravica-ai/digital-operator-pa run build         # populate dist/
+pnpm --filter @stravica-ai/digital-operator-pa run test          # wrapper-level tests
+pnpm --filter @stravica-ai/digital-operator-pa run dry-publish   # build + dry-publish
+pnpm --filter @stravica-ai/digital-operator-pa pack              # produce a real tarball
+```
+
+## Publish target
+
+`publishConfig.registry` points at `https://npm.pkg.github.com`. Publishes
+happen via `.github/workflows/publish.yml` on `v*.*.*` tag push or manual
+dispatch. See the root README for the release flow.
+
+## Standards
+
+- JS only — `.mjs`, `type: module`.
+- Zero runtime npm dependencies.
+- `node:test` for tests.
+- camelCase JSON.
+- MIT licensed.

package/bin/desk

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from '../dist/engineering-pa-core/src/desk/cli.mjs';
+run(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    console.error(`desk: ${err.message || err}`);
+    process.exit(2);
+  },
+);

package/bin/distill

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-core/src/distill/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/bin/estate-sync

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-cli/src/sync/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/bin/launch

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-cli/src/launch/cli.mjs').then(async (m) => process.exit(await m.run(process.argv.slice(2))));

package/bin/memory-sync

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-core/src/memory-sync/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/bin/migrate-inspect

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-migrate-inspect/src/cli.mjs').then((m) => m.main(process.argv.slice(2)).then((c) => process.exit(c)));

package/bin/pa

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-cli/src/pa/cli.mjs').then(async (m) => process.exit(await m.main(process.argv.slice(2))));

package/bin/pa-coordinator-hook

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-cli/src/coordinator-hook/cli.mjs').then(async (m) => process.exit(await m.main(process.argv.slice(2))));

package/bin/pa-init

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-scaffold/src/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/bin/research

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-cli/src/research/cli.mjs').then(async (m) => process.exit(await m.main(process.argv.slice(2))));

package/bin/scheduler

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-cli/src/scheduler/cli.mjs').then(async (m) => process.exit(await m.run(process.argv.slice(2))));

package/bin/secrets

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-cli/src/secrets/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/bin/slice

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-core/src/slice/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/bin/smoke

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from '../dist/engineering-pa-cli/src/smoke/cli.mjs';
+run(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    console.error(`smoke: ${err.message || err}`);
+    process.exit(2);
+  },
+);

package/bin/sync

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/engineering-pa-cli/src/sync/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-cli/README.md

@@ -0,0 +1,205 @@
+# @stravica-ai/engineering-pa-cli
+
+Identity: `@stravica-ai/engineering-pa-cli` — operator-facing CLIs.
+
+## Status
+
+**Skeleton — v0.1.0.** Workspace-internal, `"private": true`, not individually published.
+
+Six bin entries are declared and ship as placeholders that print "not yet implemented" and exit 0. Phase 1 Task 4 ports the real implementations from the predecessor `Stravica/dave` `core/tools/` tree.
+
+| Bin | Source | Lands in |
+|---|---|---|
+| `pa` | new (PA-instance control plane) | Task 4 |
+| `desk` | `core/tools/desk/` | Task 4 |
+| `secrets` | `core/tools/secrets/` | Task 4 |
+| `scheduler` | `core/tools/scheduler/` (or equivalent) | Task 4 |
+| `sync` | `core/tools/sync/` | Task 4 |
+| `memory-sync` | `core/tools/memory-sync/` | Task 4 |
+
+`pa-init` is intentionally NOT in this package — it lives under `packages/scaffold/bin/pa-init` per the brief's "scaffold/ = pa-init + onboarding flows" mapping.
+
+## Layout
+
+```
+packages/cli/
+  index.mjs            # shared placeholder entrypoint with runPlaceholder()
+  package.json         # name, version, bin entries (6), scripts
+  README.md            # this file
+  bin/
+    pa
+    desk
+    secrets
+    scheduler
+    sync
+    memory-sync
+  test/
+    index.test.mjs
+```
+
+Each bin shim is a one-line Node script that calls `runPlaceholder(toolName, argv)` from `index.mjs`. When Task 4 lands real CLIs, the shims become standard tooling-spec shims pointing at `src/<tool>/cli.mjs` modules and the chokepoint pattern (`src/<tool>/runner.mjs`) per the tooling standard §7.
+
+## Commands
+
+In v0.1.0, every bin behaves identically:
+
+```bash
+<tool> --help    # prints usage, exits 0
+<tool>           # prints "not yet implemented", exits 0
+<tool> anything  # prints "unknown verb" to stderr, exits 1
+```
+
+### `pa project` — project state writes
+
+Write-side complement to `desk projects`. Source of truth is
+`projects/<id>/project.json`; the CLI rewrites manifests in place,
+preserving the operator-repo 2-space indent and trailing newline.
+
+```bash
+pa project create <id> --name "..." --category <c>           # scaffold projects/<id>/{project.json, README.md}
+                       [--priority 0|1|2|3] [--owner ...] [--assignee ...] [--summary "..."]
+
+pa project status <id> <draft|planned|in-progress|blocked|done|archived>
+                                                              # set status; stamps `shipped` on done
+
+pa project doc add  <id> --label "..." --path "..." [--group "..."]
+                                                              # append a doc to a group (default: "Documents")
+pa project doc rm   <id> --path "..."                         # remove the entry whose path matches
+
+pa project list [--status ...] [--category ...] [--all] [--json]
+```
+
+`docs` is a **grouped object** keyed by group name → array of `{label, path}`:
+
+```json
+{
+  "docs": {
+    "Documents": [ { "label": "README", "path": "projects/foo/README.md" } ],
+    "Plans":     [ { "label": "Brief",  "path": "projects/foo/brief.md"  } ]
+  }
+}
+```
+
+Legacy flat-array manifests are accepted on read and migrated to the
+grouped shape transparently on the first `pa project doc add` write.
+The workspace project-detail page renders both shapes.
+
+### `pa work` — work-item state writes
+
+Write-side complement to `desk work`. Items live at
+`work/w-YYYY-MM-DD-NNN.json`; the CLI auto-numbers `NNN` against today's
+existing items.
+
+```bash
+pa work create [--project <id>] --title "..." --category <c>
+               [--priority 0|1|2|3] [--summary "..."] [--owner ...] [--assignee ...]
+
+pa work status <id> <draft|planned|in-progress|blocked|done|archived>
+                                                              # set status; stamps `completedAt` on done
+
+pa work list [--project <id>] [--status ...] [--category ...]
+             [--mine] [--theirs] [--all] [--json]
+```
+
+`--mine` resolves the PA name from `operator/config/preferences.json`
+(`paName` / `agentName`), defaulting to `"pa"`.
+
+### `pa knowledge` — query the operator's knowledge graph
+
+Reads `<repo-root>/operator/knowledge/.graph.json` and exposes five verbs
+for querying the operator's knowledge system. Feeds the third leg of the
+PA operating model — knowledge retrieval discipline — so agents can
+extract the right snippet at the right size instead of reading whole
+files.
+
+```bash
+pa knowledge related <slug> [--in|--out]     # 1-hop neighbourhood
+pa knowledge search  <term> [--full]         # find docs matching a term
+pa knowledge domain  <name>                  # all docs in a domain + internal edges
+pa knowledge orphans [--exclude-stubs]       # docs with no inbound edges
+pa knowledge path    <a> <b>                 # shortest path between two docs
+```
+
+Global flag: `--format <table|json|mermaid>` (default: `table`). The
+`json` shape is stable-by-convention — `{ "verb": "<name>", ... }` —
+so downstream roles (e.g. `dispatch-briefer`) can pipe query output
+into their own tooling.
+
+Slug resolution accepts exact ids, path-suffix filenames
+(`voice-guide.md` matches `operator/knowledge/writing/voice-guide.md`),
+or title-substring matches. Ambiguous matches exit `2` with the
+candidate list.
+
+`search` defaults to a title-only scan for speed. `--full` walks the
+doc body under `<repo-root>/operator/knowledge/`, but returns the same
+ranking (title exact > title substring > body match, tie-break on
+edge count). Zero-result queries exit `0` — empty is a valid answer.
+
+**Exit codes**: `0` ok, `1` usage, `2` unknown/ambiguous slug or
+unknown domain, `3` IO (graph missing / unreadable).
+
+### `pa staging-alias` — canonical staging.<site> alias for CF Workers sites
+
+Wires a `staging.<hostname>` subdomain to a chosen branch's preview
+deployment on the operator's CF-hosted Workers sites. Built around a
+small router-worker that proxies to the chosen workers.dev preview URL,
+because CF Custom Domains can only target prod deployments and CF
+Preview URLs can only run on `*.workers.dev` (per CF docs 2026-05-21).
+
+```bash
+pa staging-alias set --site <hostname> --branch <branch> [--version <id>]
+pa staging-alias unset --site <hostname> [--keep-worker]
+pa staging-alias status --site <hostname>
+pa staging-alias list
+```
+
+Registered sites are data-driven (`src/staging-alias/sites.mjs`): one
+entry per site, naming the source worker, the router worker, the vault
+key suffix, and the expected CF account-name. Adding a fourth site is
+one entry + a vault-key pair.
+
+Every write runs the 6-step CF multi-account drill: load the
+site-specific vault keys, `GET /accounts/{id}`, assert
+`result.name == expectedAccountName`, ABORT on mismatch. The drill
+output is echoed on stdout so the operator sees which account a write
+landed on. Full design + trade-offs: [`docs/staging-alias.md`](./docs/staging-alias.md).
+
+### `pa lint linkedin` — voice-rule linter
+
+Lints operator-authored text against a JSON voice-rule corpus and reports
+violations in **alter-format** (`swap → X`, `cut`, `rename`) with rationale and
+source pointer. Deterministic rules (em-dash, banned vocab, reused reaction
+phrases, repeated openers) move out of the writer's prompt and into a validator.
+
+```bash
+pa lint linkedin <input-file> [--rules <path>] [--format <text|json>] \
+                              [--severity <error|warning|info>] [--surface <name>]
+```
+
+Default corpus resolves to `operator/knowledge/writing/linkedin-rules.json`
+under the repo root. Three detector types (`literal-phrase`, `regex`, `count`)
+and three alter kinds (`swap`, `cut`, `rename`). Full schema + examples:
+[`docs/lint-linkedin.md`](./docs/lint-linkedin.md).
+
+This verb uses **lint-semantic exit codes** (ESLint-style) that intentionally
+deviate from §6 below — `0` clean, `1` errors found, `2` warnings only, `3`
+usage/IO/config error. Rationale and full table in the doc.
+
+## Exit codes (tooling standard §6)
+
+| Code | Meaning |
+|---|---|
+| 0 | OK (placeholder ran; no work done) |
+| 1 | Usage error (bad flag, unknown verb) |
+| 2 | Logical / operational failure (unused in skeleton) |
+| 3 | Transport / IO failure (unused in skeleton) |
+
+## Tests
+
+```bash
+pnpm --filter @stravica-ai/engineering-pa-cli test
+```
+
+## Standards
+
+Follows the [tooling standard](../../CONTRIBUTING.md#standards): JS only, zero npm deps, `node:test`, `node:util.parseArgs` with `strict: true`, camelCase JSON.

package/dist/engineering-pa-cli/bin/estate-sync

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/sync/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-cli/bin/launch

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/launch/cli.mjs').then(async (m) => process.exit(await m.run(process.argv.slice(2))));

package/dist/engineering-pa-cli/bin/pa

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/pa/cli.mjs').then(async (m) => process.exit(await m.main(process.argv.slice(2))));

package/dist/engineering-pa-cli/bin/pa-coordinator-hook

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// main() itself fails closed (exit 2) on any config-load or decision-logic
+// error — see cli.mjs. This top-level .catch() is one more layer below
+// that: it only fires on something even main() can't catch (e.g. the
+// dynamic import() itself failing on a corrupted/partial install). Same
+// posture either way — a security-relevant gate fails closed, not open.
+import('../src/coordinator-hook/cli.mjs')
+  .then(async (m) => process.exit(await m.main(process.argv.slice(2))))
+  .catch((err) => {
+    process.stderr.write(`pa-coordinator-hook: fatal error loading hook (${err && err.message}) — failing closed (block)\n`);
+    process.exit(2);
+  });

package/dist/engineering-pa-cli/bin/research

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/research/cli.mjs').then(async (m) => process.exit(await m.main(process.argv.slice(2))));

package/dist/engineering-pa-cli/bin/scheduler

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/scheduler/cli.mjs').then(async (m) => process.exit(await m.run(process.argv.slice(2))));

package/dist/engineering-pa-cli/bin/secrets

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/secrets/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-cli/bin/smoke

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from '../src/smoke/cli.mjs';
+run(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    console.error(`smoke: ${err.message || err}`);
+    process.exit(2);
+  },
+);

package/dist/engineering-pa-cli/bin/sync

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/sync/cli.mjs').then((m) => m.main(process.argv.slice(2)));

package/dist/engineering-pa-cli/config/coordinator-allowlist.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://stravica.dev/schemas/coordinator-allowlist.v1.json",
+  "version": 1,
+  "_comment": "Core three-tier allowlist for pa-coordinator-hook. Tier 1 tools never invoke the hook (see the settings.json matcher in packages/cli/docs/coordinator-hook.md) so they are not enumerated here for enforcement purposes — the tier1 array below is documentation only. Per-PA extensions belong in an overlay file (~/.claude/coordinator-overlay.json or <workspace>/.claude/coordinator-overlay.json), NOT in this file — this file ships inside the published package and is overwritten on every install/upgrade.",
+
+  "tier1": [
+    "Agent", "TaskStop", "SendMessage", "Workflow", "TaskCreate", "TaskList",
+    "TaskGet", "TaskOutput", "TaskUpdate", "Monitor", "ScheduleWakeup",
+    "AskUserQuestion", "Skill", "ToolSearch", "EnterPlanMode", "ExitPlanMode"
+  ],
+
+  "tier2": {
+    "Bash": {
+      "allowPatterns": [
+        "^pa\\s",
+        "^pnpm exec pa\\s",
+        "^desk\\s",
+        "^claude-relay\\s",
+        "^node\\s+\\S*claude-relay\\S*\\s+",
+        "^git status(\\s|$)",
+        "^git log(\\s|$)",
+        "^git diff --stat(\\s|$)",
+        "^git branch --show-current(\\s|$)",
+        "^git branch(\\s|$)",
+        "^git remote -v(\\s|$)",
+        "^gh pr view(\\s|$)",
+        "^gh pr list(\\s|$)",
+        "^gh pr merge(\\s|$)",
+        "^gh pr close(\\s|$)",
+        "^gh api\\s+(?!.*(-X|--method)[=\\s]*(POST|PUT|PATCH|DELETE|HEAD|post|put|patch|delete|head)\\b)",
+        "^ls(\\s|$)",
+        "^pwd(\\s|$)",
+        "^hostname(\\s|$)",
+        "^date(\\s|$)",
+        "^whoami(\\s|$)",
+        "^which\\s",
+        "^echo\\s"
+      ]
+    },
+    "Read": {
+      "_comment": "`<self>` is substituted at runtime: the resolved paName when known (PA_SELF_AGENT env var, else operator/config/preferences.json#paName), else `[^/]+` — the spec's documented fallback ('if unknown, allow any agents/*/ path').",
+      "allowPathPatterns": [
+        "^\\.session/",
+        "^agents/<self>/",
+        "^work/",
+        "^projects/[^/]+/project\\.json$",
+        "^projects/[^/]+/progress\\.md$",
+        "(^|/)spawn-log\\.json$",
+        "^\\.cache/"
+      ],
+      "allowAbsolutePathPatterns": [
+        "^/private/tmp/",
+        "^/tmp/"
+      ],
+      "blockPathPatterns": [
+        "^operator/knowledge/"
+      ]
+    },
+    "Write": {
+      "allowPathPatterns": [
+        "^agents/<self>/staging/",
+        "^agents/<self>/spawn-log\\.json$",
+        "^\\.session/",
+        "^\\.cache/"
+      ],
+      "allowAbsolutePathPatterns": [
+        "^/private/tmp/",
+        "^/tmp/"
+      ]
+    }
+  },
+
+  "tier3": ["Edit", "NotebookEdit", "Grep", "Glob", "WebFetch", "WebSearch"],
+
+  "hardDeny": {
+    "_comment": "Checked before any allow pattern (core or overlay), for both Bash commands and Read/Write paths. Overlays cannot add, remove, or shadow entries here — see policy.mjs. Not a security sandbox (a determined caller can still smuggle a second command past a naive prefix regex — see bashChainGuard below for the mitigation), just a mechanical backstop against the most obviously destructive one-liners, the specific 'obviously-destructive gh verbs' the spec calls out, and reads/writes of credential material even if some overlay pattern would otherwise match it.",
+    "bashPatterns": [
+      "rm\\s+-rf\\b",
+      "curl[^\\n]*\\|\\s*(sh|bash|zsh)\\b",
+      "wget[^\\n]*\\|\\s*(sh|bash|zsh)\\b",
+      "^git\\s+push\\b[^\\n]*--force",
+      "^git\\s+reset\\s+--hard\\b",
+      "^git\\s+clean\\s+-f",
+      "^git\\s+branch\\s+-D\\b",
+      "--no-verify\\b",
+      "--no-gpg-sign\\b",
+      "^gh\\s+repo\\s+delete\\b",
+      "^gh\\s+(release|workflow|secret|auth)\\s+(delete|remove|logout)\\b",
+      "^sudo\\b",
+      "^dd\\s+if=",
+      "\\bmkfs\\b",
+      ">\\s*/dev/(sd|nvme|disk|rdisk)"
+    ],
+    "bashChainGuardPattern": "[;&|`<>\\n]|\\$\\(",
+    "bashChainGuardNote": "Tier2 Bash commands containing a shell-chaining metacharacter (;, &&, ||, |, backtick, $(...), <, >) or an embedded newline are blocked outright even if the leading command (or leading line) matches an allow pattern — a prefix match on 'pa knowledge search foo && rm -rf ~' must not slip through, nor must 'pa knowledge search foo\\nsudo apt-get purge -y openssh-server' or a redirect like 'echo foo > ~/.ssh/authorized_keys'. False positives (e.g. a quoted '&&' inside a search string) are an accepted cost; the hook always suggests a dispatch alternative.",
+    "pathPatterns": [
+      "\\.vault/",
+      "secrets\\.enc\\.json$",
+      "\\.ssh/",
+      "\\.aws/",
+      "(^|/)\\.env$"
+    ]
+  },
+
+  "messages": {
+    "Bash": "Bash command not on the coordinator allowlist.",
+    "Read": "Read path not on the coordinator allowlist.",
+    "Write": "Write path not on the coordinator allowlist — any durable file change goes through a dispatch.",
+    "Edit": "Dispatch tool-developer or writer for any durable file change — main thread is coordinator-mode.",
+    "NotebookEdit": "Dispatch tool-developer or writer for any durable file change — main thread is coordinator-mode.",
+    "Grep": "Dispatch Explore for search — main thread is coordinator-mode.",
+    "Glob": "Dispatch Explore for file discovery — main thread is coordinator-mode.",
+    "WebFetch": "Dispatch `/research` (or a worker) for web work — main thread is coordinator-mode.",
+    "WebSearch": "Dispatch `/research` (or a worker) for web work — main thread is coordinator-mode.",
+    "operator/knowledge/**": "Use `pa knowledge` (related/search/domain/orphans/path) retrieval verbs — a direct Read bypasses the knowledge graph.",
+    "hardDeny": "This command/path matches a hard-deny pattern that no allowlist or overlay can override."
+  }
+}