docks-kit 0.15.5 → 0.16.1

package/AGENTS.md

@@ -4,17 +4,20 @@ Canonical instructions for coding agents working on this project. Compatible wit
 
 ## Repository purpose
 
-Portable configuration kit for AI coding agents. Per-tool Single Source of Truth
-(SoT) directories deploy to each tool's user-config location through
-`./docks-kit sync`. Clone once to get a consistent AI-assisted environment on
-supported Linux, macOS, and Windows hosts. The kit focuses on **token efficiency
-without sacrificing quality**. Every setting and hook minimizes token use while
+Portable configuration kit for AI coding agents. The kit manages three coding
+harnesses: Claude Code, Codex, and Oh My Pi (`omp`). Per-tool Single Source of
+Truth (SoT) directories deploy to each harness's user-config location through
+`./docks-kit sync`. The kit also deploys shared [agentskills.io](https://agentskills.io)
+skills. Clone once to get a consistent AI-assisted environment on supported
+Linux, macOS, and Windows hosts. The kit focuses on **token efficiency without
+sacrificing quality**. Every setting and hook minimizes token use while
 preserving rigorous output. When you add or edit anything, ask: *does this
 change reduce tokens without weakening correctness?*
 
 Tool-specific instructions live alongside this file:
 - **`CLAUDE.md`** — Claude Code SoT (`SoT/.claude/`), env vars, hooks, plugins, status line, session management, permission mode, open concerns.
 - Codex uses this `AGENTS.md` file plus the Codex SoT under `SoT/.codex/`; no separate root `CODEX.md` is needed.
+- omp uses this `AGENTS.md` file plus the omp SoT under `SoT/.omp/`.
 
 
 docks-kit runtime and standalone binary support covers Linux x64/arm64, macOS
@@ -27,17 +30,19 @@ launcher can fall back to Bun source.
 |------|---------|
 | `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers. On supported hosts, each runs the matching binary in `cli/dist/` only when its `--version` matches `package.json`. Otherwise it runs Bun-from-source and auto-installs Bun plus `node_modules`. Hosts outside the support matrix fail before source fallback. The standalone platform release binary provides no-Bun recovery. |
 | `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
+| `cli/src/engine-native/ompSync.ts` | omp file deployment, marketplace registration, and plugin synchronization |
 | `cli/` | Effect 4 RC CLI + bundled docs topics |
 | `SoT/models.json` | Kit-verified Claude and Codex model catalog |
 | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative) |
 | `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
+| `SoT/.omp/` | Kit-owned omp SoT: `AGENTS.md`, `config.yml`, `mcp.json`, and `intercom.json` |
 | `install.sh` / `install.ps1` | POSIX and Windows global installers |
 | `.github/workflows/release-cli.yml` | `cli-v*` release: six binaries for Linux, macOS, and Windows on x64 and arm64, plus `SHA256SUMS` and npm publish |
 | `README.md` | Front door |
 | `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
 | `SoT/.agents/skills.txt` | Universal-skill manifest, intentionally empty by default. Adding an [agentskills.io](https://agentskills.io/specification) slug opts it into EngineNative's shared `~/.agents/skills/` bootstrap and Claude symlink. |
 | `notification.mp3` | Audio asset for Notification hooks (consumed by Claude Code today; tool-agnostic file) |
-| `docs/plans/` | Multi-commit work-item plans (`active/` with status in frontmatter, plus `finished/` archive). Convention: `docs/plans/AGENTS.md` |
+| `docs/PLAN.md` | Plan record standard. The plan record is a GitHub issue; no plan markdown is tracked. `docs/AGENTS.md` routes to it and `docs/CLAUDE.md` contains only `@AGENTS.md`. |
 | `CLAUDE.md` | Claude-specific instructions; imports this `AGENTS.md` |
 | `AGENTS.md` | This file — tool-agnostic instructions |
 
@@ -46,12 +51,24 @@ Codex SoT notes:
 - `SoT/.codex/config.toml` pins Codex to `model = "gpt-5.6-sol"`, sets normal and plan reasoning to `high` with concise summaries, and sets `model_verbosity = "low"`, `personality`, live top-level `web_search`, workspace-write sandboxing with sandboxed command network access, cross-session `memories` (+ dedicated note tools), `[agents]` subagent limits (`max_threads = 12`, `max_depth = 2` — intentionally above Codex defaults for broad parallel kit work; deeper recursion increases cost and predictability risk), a 128 KiB `project_doc_max_bytes` budget for the repo-side AGENTS.md chain (the global `~/.codex/AGENTS.md` is uncapped and not counted), and enables the two Docks plugins `docks@docks` and `plan-lifecycle@docks` (the shared plan lifecycle).
 - `SoT/.codex/rules/*.rules` deploys to `~/.codex/rules/` as kit-managed Codex command policy. This is Codex's equivalent of permission allow/prompt/block rules; user-learned approvals in `~/.codex/rules/default.rules` are preserved.
 - `SoT/.codex/plugins/marketplace.json` deploys to Codex's personal marketplace path at `~/.agents/plugins/marketplace.json`; when the `codex` CLI is available, sync reruns `codex plugin add <plugin@marketplace>` for enabled SoT plugins so stale cached installs are refreshed.
+- Codex `/import` can copy Claude hooks into `~/.codex/hooks.json`. `codexSync.ts removeRetiredImportedHooks, legacy SessionStart cleanup` removes only recognized hooks from retired docks-kit Claude settings, backs up a changed file, and preserves user-authored hooks. The current Claude SessionStart program emits the structured JSON shape shared by both tools.
+- Codex limits the initial skill list to 2% of the model context and shortens descriptions first; it still reads a selected skill's full `SKILL.md`. Additive sync preserves user-added plugins, so their skill count and malformed cached `SKILL.md` files remain plugin-owned. Sync never patches a plugin cache in place.
 - The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
 - The `codex` CLI binary is upstream-owned, not kit-owned. The official standalone installer keeps package metadata under `$CODEX_HOME/packages/standalone` and places the `codex` symlink in `~/.local/bin` by default; sync only warns with a download-then-run installer command when the CLI is missing. Existing installs can self-update with `codex update`; npm and Homebrew remain upstream alternatives.
+
 - Claude runtime settings are an authoring template with sentinels. `claudeRuntime.ts` materializes absolute Bun/script paths only after the shared `bun.ts` bootstrap is ready; `claudeSync.ts` writes all runtime assets before atomically committing settings, then prunes the legacy shell scripts and Stop hook. Native `rate_limits` is the sole quota source, so jq/curl/OAuth caches are not runtime dependencies. A missing Bun defers only this cutover and preserves legacy pointers/files.
 - Claude's deployed SoT defaults are `model: opus` and `effortLevel: high`; `advisorModel` is deliberately absent/off. `--claude-advisor=on` is the per-machine opt-in and writes `advisorModel: fable` after the settings merge. `opus` is the alias, not a pinned id: the `minimumVersion` floor of 2.1.219 ensures Claude Code can resolve it to the newest Opus its provider offers — Opus 5 on the Anthropic API or Opus 4.6 on Microsoft Foundry — instead of silently capping Anthropic API users at Opus 4.8 under the former 2.1.170 floor. Keeping the alias provides provider portability and tracks future Opus releases; the literal `claude-opus-5` is unavailable on Foundry. The floor also subsumes Fable 5's older 2.1.170 requirement.
+- Claude permission rules are pruned, not host-scoped. The kit deploys its `PowerShell(...)` deny and ask rules on every host, because Claude Code leaves the PowerShell tool opt-in off Windows rather than unavailable, and a host that enables it must already carry the guards. `claudeRetired.ts RETIRED_PERMISSION_RULES, exact retired-rule inventory` lists the rules the kit no longer ships. `claudeSync.ts syncRemovals, retired-permission pass` force-prunes those exact strings from the kit-managed `~/.claude/settings.json` on every sync, because `settings.ts mergeSettings, permission-array union` would otherwise keep a dropped rule forever. A different user-authored rule survives. To restore an exact retired rule for one checkout, put it in that checkout's `.claude/settings.local.json`. Claude Code resolves that file against the working directory and merges it over user settings. Sync never reads or writes the checkout-local file. Claude Code has no user-scope local settings file. For a machine-wide restoration, add the rule to `SoT/.claude/settings.json`. At the same time, remove the exact string from `claudeRetired.ts RETIRED_PERMISSION_RULES, exact retired-rule inventory`. `permissions.allow` holds four read-only entries (`Read`, `Glob`, `Grep`, and `WebSearch`) plus the working-directory edit rule `Edit(./)`. Broad shell allow rules are not restored, because an allow rule resolves before Claude Code's read-only command analyzer and the auto-mode classifier. `autoMemoryEnabled` and `autoDreamEnabled` are both `false`.
+
+omp SoT notes:
+- `SoT/.omp/AGENTS.md`, `config.yml`, and `mcp.json` deploy to `~/.omp/agent/`.
+- `SoT/.omp/intercom.json` deploys to `$PI_CODING_AGENT_DIR/intercom/config.json`. The default root is `~/.pi/agent`.
+- `ompSync.ts syncConfig` deep-merges `config.yml` through `mergeOmpConfig`.
+- Sync registers the `docks` marketplace. It installs or upgrades `docks@docks` and `plan-lifecycle@docks` at user scope.
+- Sync installs `pi-intercom` at the verified version from `SoT/toolchain.json`.
+- The omp CLI is upstream-owned and self-updating through `omp update`. Sync never installs or upgrades the CLI.
 
-For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT directory.
+For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the matching SoT directory.
 
 ## Engineering rules
 
@@ -59,19 +76,20 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 - **Removed bash engine.** The bash engine was removed after the `bash-engine-final` tag. `DOCKS_KIT_ENGINE=bash` must fail with the removed-engine message; engine bugs are fixed forward in EngineNative.
 - **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-rc.109` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-rc.109` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.109`, and `vitest@4.1.10` (required by the `@effect/vitest` peer range). `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
 - **Effect skill routing.** Effect work in this checkout must verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/unstable/cli/`, never from memory or a mutable dist-tag. The `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` skills target Effect 3.x and do not apply.
-- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, and `agents`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync codex` for Codex-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches; used by `docks-kit update`), `--reconcile`, `--prune`, and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
+- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, `agents`, and `omp`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync omp` for omp-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches; used by `docks-kit update`), `--reconcile`, `--prune`, and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
+- **Per-machine harness selection.** `~/.docks-kit/state.json` drives a flag-less sync. A missing file selects `claude`, `codex`, and `agents`; it never selects `omp` implicitly. `sync` never prompts and never writes the selection file. `docks-kit harnesses` is the only command that writes the selection.
 - **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates — neither flag-less reset can clean it up. The one exception is the Claude `removed` manifest (`claude::_removed_manifest`), a curated list of unambiguous kit-owned artifacts that `claude::sync_removals` force-prunes on every sync, including the home-relative `~/.local/bin/session-relay` artifact installed outside `~/.claude`; see `CLAUDE.md` § Pruning stale artifacts.
 - **`--reconcile` / `--prune` are the kit-owned reconcile flags.** Orthogonal — `--reconcile` reconciles the settings layer (SoT-declared keys/tables/arrays win; user-only keys and nested objects are preserved; permissions arrays are replaced wholesale by SoT). `--prune` uninstalls kit-managed installations not in the SoT (plugins, marketplaces, and `~/.agents/skills/*` entries tracked in `~/.agents/.kit-managed-skills`). Combine for a full reset to SoT's kit-managed scope. User-only additions outside the kit's scope (custom env vars, mcpServers, manually-installed skills, third-party plugins not declared in SoT) are always preserved. Each tool's per-tool file documents the specific paths and diff recipes.
-- **SOLID-aligned modules.** `cli/src/engine-native/parseArgs.ts` owns flag parsing/validation. `toolchain.ts` owns verified-version floor reporting over `SoT/toolchain.json`; `bun.ts` owns the shared, memoized Bun bootstrap; `claudeRuntime.ts` owns Claude settings materialization. `claudeSync.ts`, `codexSync.ts`, and `skillsSync.ts` own tool-specific sync logic. `index.ts` is the thin orchestrator. The public CLI seam is `cli/src/engine.ts`.
+- **SOLID-aligned modules.** `cli/src/engine-native/parseArgs.ts` owns flag parsing and validation. `toolchain.ts` owns verified-version floor reporting over `SoT/toolchain.json`; `bun.ts` owns the shared, memoized Bun bootstrap; `claudeRuntime.ts` owns Claude settings materialization. `claudeSync.ts`, `codexSync.ts`, and `skillsSync.ts` own their tool-specific sync logic. `ompSync.ts` owns omp file and plugin sync. `ompYaml.ts` owns the omp YAML merge. `harnesses.ts` owns per-machine harness selection. `index.ts` is the thin orchestrator. The public CLI seam is `cli/src/engine.ts`.
 - **Small, reviewable changes.** Bundled multi-concern PRs are harder to review and revert. Split an engine/CLI change and a per-tool config change unless the change requires atomicity.
 - **Dry-run before destructive flags.** Always preview with `./docks-kit sync --dry-run` (or the relevant `diff <(jq -S …)` recipe in the per-tool file) before invoking `--reconcile` or `--prune`. User-added permissions / env vars / plugins absent from SoT will be discarded.
-- **SoT prompt files are rules, not explanation.** `SoT/.claude/CLAUDE.md` and `SoT/.codex/AGENTS.md` are loaded into every agent session's prompt context — every line costs prompt tokens on every turn for every user. Restrict their content to rules, heuristics, and `<constraint>` blocks the agent must *act on* during a turn. Do NOT add inline source citations (`Source: …`, attributed quotes), "why this rule exists" preface text, version-watermarking trivia (e.g. "Distilled from X v2.0, captured 2025-11-07"), per-bug workarounds, or installation instructions. Provenance, motivation, and historical context belong in `CLAUDE.md` / `AGENTS.md` at the repo root (humans read once) or in commit messages — never in the SoT. For every line, apply the official test: would removing it cause the agent to make mistakes? If not, cut it — over-instruction degrades adherence on current frontier models.
+- **SoT prompt files are rules, not explanation.** `SoT/.claude/CLAUDE.md`, `SoT/.codex/AGENTS.md`, and `SoT/.omp/AGENTS.md` are loaded into agent sessions' prompt context — every line costs prompt tokens on every turn for every user. Restrict their content to rules, heuristics, and `<constraint>` blocks the agent must *act on* during a turn. Do NOT add inline source citations (`Source: …`, attributed quotes), "why this rule exists" preface text, version-watermarking trivia (e.g. "Distilled from X v2.0, captured 2025-11-07"), per-bug workarounds, or installation instructions. Provenance, motivation, and historical context belong in `CLAUDE.md` / `AGENTS.md` at the repo root (humans read once) or in commit messages — never in the SoT. For every line, apply the official test: …
 - **Cache-invariance for kit-authored prompt surfaces.** Never put timestamps, counters, or mutable state into SoT prompt files, hook outputs that land in the cached prefix, or tool definitions — cache breaks force cold-start writes. Dynamic context belongs in runtime-injected messages (e.g. SessionStart hook output), which is exactly how the kit's date/config injection works.
 
 ## Code style
 
 - Bash: for launchers/installers/hook assets, use `set -euo pipefail`, quoted variables, `[[ ]]` over `[ ]`, and function-scoped `local`.
-- JSON config: edit the SoT (`SoT/<tool>/`) and run `./docks-kit sync`. Never edit deployed config (`~/.claude/`, `~/.codex/`) directly.
+- JSON and YAML config: edit the SoT (`SoT/<tool>/`) and run `./docks-kit sync`. Never edit deployed config under `~/.claude/`, `~/.codex/`, or `~/.omp/agent/` directly.
 
 ## Security
 
@@ -87,7 +105,23 @@ Use direct acceptance and focused regressions while iterating, then run the full
 
 ## Skills
 
-This project ships **kit-mechanic skills** under `.claude/skills/` — narrowly-scoped references for how EngineNative works (settings merge, plugin bootstrap, universal-skill install, Codex TOML merge, sync orchestration). They cost prompt tokens only inside this repo's sessions and document regression-prone TypeScript sync logic in `cli/src/engine-native/`. **Pipeline content** (multi-agent slash commands, refactor/security/docs workflows, parallel-scanner agents) belongs in the separate [DocksDocks/docks](https://github.com/DocksDocks/docks) plugin — not here. Project-level agents under `.claude/agents/` follow the same rule: kit-mechanic agents that wrap kit-mechanic skills are permitted; pipeline agents live in the docks plugin.
+**Project-skill scope.** Keep project skills within two classes: kit-mechanic skills and the `unslop` repo-prose skill.
+Canonical project skills live in `.agents/skills/<name>/SKILL.md`.
+Each `.claude/skills/<name>` entry is a relative symlink to its canonical directory.
+Codex reads `.agents/skills/` natively, so one copy serves both tools.
+Kit-mechanic skills document regression-prone TypeScript sync logic in `cli/src/engine-native/`.
+Kit-mechanic skills: `codex-config-merge-context`, `engine-native-context`, `plugin-bootstrap-context`, `settings-merge-context`, `sync-orchestration-context`, `toolchain-context`, `universal-skills-context`, and `omp-sync-context`.
+**Pipeline content** (multi-agent slash commands, refactor/security/docs workflows, parallel-scanner agents) belongs in the separate [DocksDocks/docks](https://github.com/DocksDocks/docks) plugin — not here. Project-level agents under `.claude/agents/` follow the same rule: kit-mechanic agents that wrap kit-mechanic skills are permitted; pipeline agents live in the docks plugin.
+
+**Windows checkouts.** These nine entries are the only symlinks this repository tracks. Git for Windows defaults to `core.symlinks=false`, which checks a symlink out as a plain file holding the target path, so Claude Code finds no `SKILL.md` and silently loads no project skill. Codex is unaffected, because it reads the real directories under `.agents/skills/`. To restore Claude Code on Windows, enable Developer Mode or run as administrator, then `git config core.symlinks true` and re-checkout the paths: `git checkout -- .claude/skills`. Never repair this by replacing an entry with a copy; two copies drift, which is the failure the canonical layout removes. This limitation is confined to project skills in this checkout. It does not affect the deployed user-level skills, where `skillsSync.ts linkOrCopyWithWarnings` already falls back from symlink to junction to marked copy.
+
+`npx skills add cursor/plugins -s unslop -y -a claude-code codex` installs `unslop`, and root `skills-lock.json` pins it.
+The repository vendors upstream `unslop` text and pins it by the lockfile hash, so never edit it locally.
+Upstream licenses `pstack/` under MIT (Copyright (c) 2026 Lauren Tan), so redistribution is permitted.
+MIT requires the notice to travel with the copy, so `.agents/skills/unslop/LICENSE` vendors it verbatim and must stay beside `SKILL.md`.
+The `unslop` "adding soul" guidance conflicts with the global Simplified Technical English Output Standard.
+The Output Standard wins.
+Use `unslop` only for its pattern-detection lists.
 
 <constraint>
 When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agents/*.md` + its `.codex/agents/*.toml` twin) cites EngineNative internals, name the **module + exported/local function + semantic anchor** (e.g. `claudeSync.ts syncPlugins, pass 5 uninstall guard`) — never a raw `file:NNN` line number, which goes stale on every refactor. Keep exactly one coarse `metadata.source_files[].lines` range per skill file as the sole intentional line-number touchpoint.
@@ -98,42 +132,78 @@ When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agent
 ## Plans
 
 Use direct implementation for one clear, reversible, low-risk local diff with one
-bounded acceptance path; it creates no tracked plan, reviewer, or automatic
+bounded acceptance path; it creates no plan issue, reviewer, or automatic
 commit. Use a canonical plan for explicit planning, multi-commit or
 cross-repository work, cold handoff, an unresolved decision, a cross-subsystem or
 public-contract change, security-sensitive or destructive work, or any
 non-`local` effect.
 
 <constraint>
-Canonical plans live in `docs/plans/active/`; status is frontmatter and
-`docs/plans/finished/` is terminal. Exactly three skills own the workflow:
-`plan-workspace` maintains the workspace; main-context `plan-manager` runs six
-phases — decide, draft, research, one plan review, implement, code review — and
-archives; internal `plan-reviewer` returns a readable pre-implementation verdict.
-Two read-only reviewer wrappers ship, `plan-reviewer` and `code-reviewer`, and
-nothing else in the lifecycle has a wrapper.
+The plan record is a GitHub issue. Its body starts with
+`<!-- plan-contract: v3 -->`, then a blank line and the exact eight `##`
+sections; it has no frontmatter. GitHub owns title, open-work phase, owner,
+timestamps, and completion, and no plan markdown is tracked in the repository.
+Exactly three skills own the workflow: `plan-workspace` maintains the workspace;
+main-context `plan-manager` runs six phases - decide, draft, research, plan
+review, implement, code review - with bounded repair and fresh re-review in both
+review phases, then archives; internal `plan-reviewer` returns one readable
+pre-implementation verdict block per round. Two read-only reviewer wrappers
+ship, `plan-reviewer` and `code-reviewer`, and nothing else in the lifecycle has
+a wrapper.
 </constraint>
 
-The record is markdown only: `plan_contract: v2` frontmatter plus eight `##`
-sections — `## Goal`, `## Research`, `## Steps`, `## Acceptance`,
-`## Do not touch`, `## Open questions`, `## Review`, `## Verification Results`.
-There are no hashes, permits, run identities, locks, bundles, or `v2`/`vN` plan
-files, and the `plan.mjs` shipped inside the installed `plan-lifecycle` plugin
-is the only lifecycle tool. This lifecycle creates zero commits and never
-pushes; commit when the user asks, under `docks:commit-discipline`.
+After the marker and blank line, the record carries exactly `## Goal`,
+`## Research`, `## Steps`, `## Acceptance`, `## Do not touch`,
+`## Open questions`, `## Review`, and `## Verification Results`, in that order
+and once each. `## Goal` carries exactly one mode line. Open-work phase is one
+of `drafting`, `planned`, `ongoing`, or `blocked` in a `plan:<phase>` label; a
+blocked plan starts `## Open questions` with `Blocked: <one-line reason>`.
+Closed completion derives from GitHub `state` and `stateReason`. `## Review`
+contains exactly `_Review records are stored in issue comments._`. Each reviewer
+returns one markdown block, and the manager posts that whole block as one issue
+comment. The latest trusted well-formed record per review kind wins; its author
+must equal the plan's sole assignee. A legacy body verdict is consulted only
+when no trusted comment record exists for that kind. Both review phases use
+fresh inputs and run at most five rounds, stopping on pass, no progress, a
+finding surviving its fix, or `repair` or `fixes-required` in round five. A
+plan-review `blocked` verdict always routes its user-only decision through
+`## Open questions` and `ask`.
+
+The record carries no hash, permit, run identity, lock, or bundle, and the
+`plan.mjs` shipped inside the installed `plan-lifecycle` plugin is the only
+lifecycle tool. An `export` writes the sha256 of the body it copied beside the
+copy so a stale copy cannot revert the record; that digest detects staleness and
+authorizes nothing. Routine plan issue publication, implement-start linked
+branch creation, commits, normal pushes, and the closing pull request carry the
+settled mode's authorization and need no repeated prompt. Before any branch
+checkout, including `gh issue develop --checkout`, require
+`git status --porcelain` to be empty. If it is dirty, never stash, move, or
+commit ambient work; set the plan `blocked` and name the dirty paths, or use an
+authorized clean worktree.
+Immediately after setting the plan `ongoing`, every `gh issue develop` call uses
+`--repo`; the manager reuses a linked branch or creates one with
+`--base <default> --checkout`, then re-lists and recovers after failure.
+Implementation stops when no linked branch can be verified; there is no local
+fallback. After the checks policy passes, the manager asks immediately before
+merge. Without a fresh `Merge now` answer, it leaves the pull request and issue
+open. `plan.mjs archive` verifies the latest trusted code-review result and
+merged closing pull request after landing.
 
 Every Steps row carries an `Effect` of exactly
 `local|probe|production_access|publish|push|release|deploy`. A step whose
 `Effect` is not `local` requires an in-session `ask` confirmation immediately
-before it runs; when `ask` is unavailable the step is set `blocked` with
-`blocked_reason` naming the unconfirmed effect. Persisted effects record intent
-only.
-
-A plan carrying a `Plan-run:` line is a v1 plan: render it, never parse or
-migrate it, and finish it by hand by moving the file byte-unchanged to
-`docs/plans/finished/<YYYY-MM-DD>-<slug>.md` with a `## Retirement` section
-appended. The complete contract lives in `docs/plans/AGENTS.md`;
-`docs/plans/CLAUDE.md` contains only `@AGENTS.md`.
+before it runs; when `ask` is unavailable the step is set `blocked` and the plan
+reason becomes the first `## Open questions` line, `Blocked: <reason>`.
+Persisted effects record intent only. Routine issue publication and landing
+actions are outside the Steps table.
+
+Render a plan body verbatim only when the user names that plan and asks to see it. After a write, report the one-line header strip and the changed lines only; a write never re-renders the body.
+
+No plan markdown is tracked. The pre-GitHub records under
+`docs/plans/finished/` were deleted; `git log -- docs/plans/finished/` recovers
+them as history, and no lifecycle command restores them. The complete contract
+lives in `docs/PLAN.md`; `docs/AGENTS.md` routes to it and `docs/CLAUDE.md`
+contains only `@AGENTS.md`.
 
 Distinct from per-tool **Open Concerns** sections (wait-on-upstream
 blockers tied to a vendor shipping a fix — these live inside the per-tool

package/README.md

@@ -5,15 +5,17 @@ Truth (SoT)** directories deploy to each tool's user-config location. Clone
 once to get a consistent AI-assisted environment on supported Linux, macOS,
 and Windows machines. Tuned for **token efficiency without sacrificing quality**.
 
-Supported tools: **Claude Code**, **Codex**, and any agent consuming
-[agentskills.io](https://agentskills.io) universal skills.
+Supported harnesses: **Claude Code**, **Codex**, and **Oh My Pi (`omp`)**.
+The kit also deploys [agentskills.io](https://agentskills.io) universal skills.
 
 ## Quick start
 
 ```bash
 git clone https://github.com/DocksDocks/public.git ~/projects/public
 cd ~/projects/public
-./docks-kit sync            # deploy everything (Claude Code + Codex + skills)
+./docks-kit harnesses       # choose this machine's flag-less sync harnesses
+./docks-kit sync            # deploy this machine's harness selection
+./docks-kit sync omp        # deploy omp explicitly
 ./docks-kit status          # doctor view: drift, toolchain, plugins, skills
 ```
 
@@ -41,15 +43,16 @@ PowerShell.
 ## CLI
 
 ```text
-docks-kit sync [claude] [codex] [agents]   deploy the SoT (default: all three)
-docks-kit update [--no-sync]               self-update the kit (autodetects checkout vs global install), then sync
-docks-kit model <claude|codex> [value]     get/set the DEPLOYED model (TTY picker)
-docks-kit models [claude|codex]            model catalogs (`--json`)
-docks-kit toolchain [check|ensure <tool>]  verified-version floors for external tools
-docks-kit status [--json]                  deployed-vs-SoT drift + toolchain + counts
-docks-kit plugins list [--json]            enabledPlugins tri-state vs installed
-docks-kit skills list [--json]             universal skills vs manifest
-docks-kit docs [topic]                     self-documentation (9 topics)
+docks-kit sync [claude] [codex] [agents] [omp]  deploy explicit targets or the machine selection
+docks-kit harnesses                             view or change this machine's selection
+docks-kit update [--no-sync]                    self-update the kit (autodetects checkout vs global install), then sync
+docks-kit model <claude|codex> [value]          get/set the DEPLOYED model (TTY picker)
+docks-kit models [claude|codex]                 model catalogs (`--json`)
+docks-kit toolchain [check|ensure <tool>]       verified-version floors for external tools
+docks-kit status [--json]                       deployed-vs-SoT drift + toolchain + counts
+docks-kit plugins list [--json]                 enabledPlugins tri-state vs installed
+docks-kit skills list [--json]                  universal skills vs manifest
+docks-kit docs [topic]                          self-documentation (9 topics)
 --help --version --wizard --completions    built-in
 ```
 
@@ -87,6 +90,9 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 - **Additive by default** — user-only settings keys, plugins, and skills
   survive a plain sync. Reconciliation toward the SoT is explicit
   (`--reconcile` / `--prune`).
+- **Per-machine selection** — `~/.docks-kit/state.json` drives a flag-less sync.
+  A missing file selects Claude Code, Codex, and universal skills. It does not
+  select omp. Use `docks-kit harnesses` to view or change the selection.
 - **Idempotent** — every step is safe to re-run; no-change syncs are no-ops.
 - **Toolchain floors** — `SoT/toolchain.json` records the kit-verified version
   floors for external tools (bun, bwrap, …). `docks-kit toolchain check` prints
@@ -106,6 +112,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 |------|---------|
 | `SoT/.claude/` | Claude Code SoT (settings template, Bun runtime programs, CLAUDE.md) |
 | `SoT/.codex/` | Codex SoT (config.toml, rules, AGENTS.md, marketplace) |
+| `SoT/.omp/` | omp SoT (AGENTS.md, config.yml, mcp.json, intercom.json) |
 | `SoT/.agents/` | Universal-skill manifest |
 | `SoT/models.json` | Kit-verified Claude and Codex model catalog |
 | `SoT/toolchain.json` | Verified-version floors |
@@ -114,7 +121,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 | `cli/` | docks-kit CLI (Effect 4 RC on Bun) + bundled docs topics |
 | `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (binary → Bun-from-source) |
 | `install.sh` / `install.ps1` | POSIX and Windows global installers |
-| `docs/plans/` | Multi-commit work-item plans |
+| `docs/PLAN.md` | Plan record standard; plans are GitHub issues |
 | `AGENTS.md` / `CLAUDE.md` | Agent-facing engineering rules / Claude Code specifics |
 
 ## Platform support
@@ -136,7 +143,7 @@ Tagging `cli-v*` builds six standalone binaries for Linux, macOS, and Windows
 on x64 and arm64. The workflow attaches them plus `SHA256SUMS` to the GitHub
 release. npm publishes the exact package tarball through trusted publishing
 with OIDC provenance.
-Package `docks-kit` 0.15.5 bundles the CLI + generated payload, so npm releases
+Package `docks-kit` 0.16.1 bundles the CLI + generated payload, so npm releases
 are versioned config snapshots without shipping the authoring `SoT/` tree.
 
 ## Deeper docs

package/cli/docs/sync-layers.md

@@ -1,7 +1,9 @@
 # Sync layers
 
-`docks-kit sync [claude] [codex] [agents]` — targets are positional words;
-no target means all three.
+`docks-kit sync [claude] [codex] [agents] [omp]` — targets are positional
+words; no target means this machine's harness selection in
+`~/.docks-kit/state.json`. The default is `claude codex agents`, and
+`docks-kit harnesses` changes it.
 
 ## claude (→ ~/.claude, ~/.claude.json, shell rc)
 
@@ -46,6 +48,34 @@ and `codex plugin add` refresh.
 `npx skills add` per missing manifest slug, Claude symlink healing, and the
 kit-managed snapshot that `--prune` reconciles against.
 
+## omp (→ resolved agent dir, intercom root)
+
+AGENTS.md, mcp.json, and intercom config.json are whole-file deploys;
+config.yml is deep-merged (SoT keys win, mapping nodes merge, deployed-only
+keys survive, stale slash-bearing `retry.fallbackChains` wildcards pruned).
+Directories are mode 0700 and files mode 0600. Then the `docks` marketplace is
+registered, `docks@docks` and `plan-lifecycle@docks` are installed or upgraded
+through `omp plugin`, and `pi-intercom` is installed at its
+`SoT/toolchain.json` pin. Inventory comes from `omp plugin list --json`, where a
+marketplace row counts as installed only when its `scope` is `user`, so a repeat
+run is a no-op and a project-only row still installs. When just the legacy
+config-root registry lists `docks`, omp copies it forward itself: the sync runs
+`marketplace update`, or the read-only `marketplace list` under
+`--skip-plugin-refresh`, which keeps installs but fetches nothing. A dry run
+invokes no omp subcommand.
+
+Paths mirror upstream `dirs.ts` `DirResolver`, resolved from the environment
+plus directory probes, so a dry run still runs no omp subcommand. The agent
+directory is `<config root>/agent`, where the config root is
+`~/<PI_CONFIG_DIR or .omp>` plus `profiles/<name>` under an active profile
+(`OMP_PROFILE`, else legacy `PI_PROFILE`). For the default profile only,
+`PI_CODING_AGENT_DIR` replaces the agent directory outright. The agent
+directory never moves under XDG. Only the data root that holds
+`marketplaces.json` does: on Linux and macOS, with no agent-dir override
+active, an existing `$XDG_DATA_HOME/omp` (or `$XDG_DATA_HOME/omp/profiles/<name>`
+for a named profile) is adopted. The intercom file keeps pi-intercom's own
+root: `$PI_CODING_AGENT_DIR/intercom`, else `~/.pi/agent/intercom`.
+
 ## Reconcile flags
 
 - `--reconcile` — settings layer: SoT-declared keys win; user-only preserved.

package/cli/src/commands/harnesses.ts

@@ -0,0 +1,64 @@
+import { Command, Prompt } from "effect/unstable/cli"
+import { Console, Effect } from "effect"
+import { bail } from "../engine"
+import {
+  engineHome,
+  HARNESSES,
+  harnessStateFile,
+  LEGACY_SELECTION,
+  readHarnessSelection,
+  writeHarnessSelection,
+  type Harness
+} from "../engine-native/harnesses"
+
+const DESCRIPTIONS: Record<Harness, string> = {
+  claude: "Claude Code user configuration",
+  codex: "Codex user configuration",
+  agents: "universal agent skills",
+  omp: "Oh My Pi user configuration"
+}
+
+export const harnessesCommand = Command.make(
+  "harnesses",
+  {},
+  () =>
+    Effect.gen(function* () {
+      const home = engineHome(process.env)
+      const stored = yield* Effect.sync(() => readHarnessSelection(home))
+      const selection = stored ?? LEGACY_SELECTION
+      const names = selection.join(", ")
+
+      if (stored === undefined) {
+        yield* Console.log(
+          `Harness selection: ${names} (no selection is stored yet; the legacy default applies)`
+        )
+      } else {
+        yield* Console.log(`Harness selection: ${names}`)
+      }
+
+      if (!process.stdout.isTTY) return
+
+      const answer = yield* Prompt.multiSelect({
+        message: "Choose the harnesses for a flag-less docks-kit sync",
+        choices: HARNESSES.map((harness) => ({
+          title: harness,
+          value: harness,
+          description: DESCRIPTIONS[harness],
+          selected: selection.includes(harness)
+        }))
+      })
+
+      if (answer.length === 0) {
+        return yield* bail("Select at least one harness. The stored selection was not changed.")
+      }
+
+      yield* Effect.sync(() => writeHarnessSelection(home, answer))
+      yield* Console.log(
+        `Saved harness selection: ${answer.join(", ")} (${harnessStateFile(home)})`
+      )
+    })
+).pipe(
+  Command.withDescription(
+    "Choose the harness selection that drives a flag-less docks-kit sync."
+  )
+)

package/cli/src/commands/sync.ts

@@ -29,11 +29,11 @@ const updateNudge = (logger: Logger): void => {
   }
 }
 
-const VALID_TARGETS = ["claude", "codex", "agents"]
+const VALID_TARGETS = ["claude", "codex", "agents", "omp"]
 
 const targets = Argument.variadic(
   Argument.string("target").pipe(
-    Argument.withDescription("Sync targets: claude, codex, agents (default: all three)")
+    Argument.withDescription("Sync targets: claude, codex, agents, omp (default: selected harnesses)")
   )
 )
 

package/cli/src/engine-native/claudeRetired.ts

@@ -0,0 +1,165 @@
+/** Kit-owned permission rules the SoT no longer ships.
+ *
+ * `mergeSettings` unions the deployed arrays with the SoT arrays, so dropping a
+ * rule from `SoT/.claude/settings.json` never removes it from a file an earlier
+ * sync already wrote. `claudeSync.ts syncRemovals` force-prunes this exact-string
+ * inventory on every host so the retirement reaches existing installations
+ * without `--reconcile`.
+ *
+ * `allow` holds the shell pre-approvals retired in favour of Claude Code's own
+ * read-only command analysis and the auto-mode classifier, plus `WebFetch`.
+ * `deny` holds the malformed single-backslash spellings superseded by their
+ * escaped `\\)` forms; Claude Code refuses to parse the old text.
+ *
+ * Exact strings only. A user-authored rule outside this list survives the prune.
+ */
+export const RETIRED_PERMISSION_RULES = {
+  allow: [
+    "Bash(git *)",
+    "Bash(git add *)",
+    "Bash(git commit *)",
+    "Bash(git status *)",
+    "Bash(git diff *)",
+    "Bash(git log *)",
+    "Bash(git branch *)",
+    "Bash(git checkout *)",
+    "Bash(git switch *)",
+    "Bash(git stash *)",
+    "Bash(git fetch *)",
+    "Bash(git pull *)",
+    "Bash(git tag *)",
+    "Bash(git show *)",
+    "Bash(git blame *)",
+    "Bash(git worktree *)",
+    "Bash(gh *)",
+    "Bash(pnpm *)",
+    "Bash(npm *)",
+    "Bash(npx *)",
+    "Bash(node *)",
+    "Bash(docker *)",
+    "Bash(docker-compose *)",
+    "Bash(ls *)",
+    "Bash(cat *)",
+    "Bash(find *)",
+    "Bash(grep *)",
+    "Bash(head *)",
+    "Bash(tail *)",
+    "Bash(wc *)",
+    "Bash(sort *)",
+    "Bash(uniq *)",
+    "Bash(diff *)",
+    "Bash(which *)",
+    "Bash(pwd *)",
+    "Bash(date *)",
+    "Bash(mkdir *)",
+    "Bash(basename *)",
+    "Bash(dirname *)",
+    "Bash(realpath *)",
+    "Bash(jq *)",
+    "Bash(curl *)",
+    "Bash(tree *)",
+    "Bash(sed *)",
+    "Bash(awk *)",
+    "Bash(cut *)",
+    "Bash(tr *)",
+    "Bash(tee *)",
+    "Bash(echo *)",
+    "Bash(printf *)",
+    "Bash(env *)",
+    "Bash(printenv *)",
+    "Bash(uname *)",
+    "Bash(file *)",
+    "Bash(stat *)",
+    "Bash(du *)",
+    "Bash(id *)",
+    "Bash(whoami *)",
+    "Bash(php *)",
+    "Bash(composer *)",
+    "Bash(python3 *)",
+    "Bash(python *)",
+    "Bash(pip *)",
+    "Bash(pip3 *)",
+    "PowerShell(git *)",
+    "PowerShell(git add *)",
+    "PowerShell(git commit *)",
+    "PowerShell(git status *)",
+    "PowerShell(git diff *)",
+    "PowerShell(git log *)",
+    "PowerShell(git branch *)",
+    "PowerShell(git checkout *)",
+    "PowerShell(git switch *)",
+    "PowerShell(git stash *)",
+    "PowerShell(git fetch *)",
+    "PowerShell(git pull *)",
+    "PowerShell(git tag *)",
+    "PowerShell(git show *)",
+    "PowerShell(git blame *)",
+    "PowerShell(git worktree *)",
+    "PowerShell(gh *)",
+    "PowerShell(pnpm *)",
+    "PowerShell(npm *)",
+    "PowerShell(npx *)",
+    "PowerShell(node *)",
+    "PowerShell(docker *)",
+    "PowerShell(docker-compose *)",
+    "PowerShell(ls *)",
+    "PowerShell(cat *)",
+    "PowerShell(find *)",
+    "PowerShell(grep *)",
+    "PowerShell(head *)",
+    "PowerShell(tail *)",
+    "PowerShell(wc *)",
+    "PowerShell(sort *)",
+    "PowerShell(uniq *)",
+    "PowerShell(diff *)",
+    "PowerShell(which *)",
+    "PowerShell(pwd *)",
+    "PowerShell(date *)",
+    "PowerShell(mkdir *)",
+    "PowerShell(basename *)",
+    "PowerShell(dirname *)",
+    "PowerShell(realpath *)",
+    "PowerShell(jq *)",
+    "PowerShell(curl *)",
+    "PowerShell(tree *)",
+    "PowerShell(sed *)",
+    "PowerShell(awk *)",
+    "PowerShell(cut *)",
+    "PowerShell(tr *)",
+    "PowerShell(tee *)",
+    "PowerShell(echo *)",
+    "PowerShell(printf *)",
+    "PowerShell(env *)",
+    "PowerShell(printenv *)",
+    "PowerShell(uname *)",
+    "PowerShell(file *)",
+    "PowerShell(stat *)",
+    "PowerShell(du *)",
+    "PowerShell(id *)",
+    "PowerShell(whoami *)",
+    "PowerShell(php *)",
+    "PowerShell(composer *)",
+    "PowerShell(python3 *)",
+    "PowerShell(python *)",
+    "PowerShell(pip *)",
+    "PowerShell(pip3 *)",
+    "WebFetch"
+  ],
+  deny: [
+    "PowerShell(Remove-Item *-Recurse* \\)",
+    "PowerShell(Remove-Item *-Recurse* *:\\)",
+    "PowerShell(del *-Recurse* \\)",
+    "PowerShell(del *-Recurse* *:\\)",
+    "PowerShell(erase *-Recurse* \\)",
+    "PowerShell(erase *-Recurse* *:\\)",
+    "PowerShell(rd *-Recurse* \\)",
+    "PowerShell(rd *-Recurse* *:\\)",
+    "PowerShell(ri *-Recurse* \\)",
+    "PowerShell(ri *-Recurse* *:\\)",
+    "PowerShell(rm *-Recurse* \\)",
+    "PowerShell(rm *-Recurse* *:\\)",
+    "PowerShell(rmdir *-Recurse* \\)",
+    "PowerShell(rmdir *-Recurse* *:\\)"
+  ],
+  ask: []
+} as const satisfies Readonly<Record<"allow" | "deny" | "ask", ReadonlyArray<string>>>