@tenphi/harnesspm 0.0.0-snapshot.7984e7b

package/docs/spec/02-package-format.md

@@ -0,0 +1,238 @@
+# 2. Package format
+
+**In short**
+
+- A harness is a `harness/` folder at the package root. It is an [Agent Plugins 1.0](https://agent-plugins.org/) plugin: `plugin.json`, `skills/`, `mcp.json`.
+- Everything harnesspm adds lives in the standard's extension namespace: the `dev.harnesspm` field in `plugin.json` and the folder of the same name.
+- Every unit has an ID, `<plugin name>:<kind>/<name>`, used to exclude, replace or patch it.
+
+The smallest harness is two files:
+
+```text
+harness/
+├── plugin.json                          {"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "mylib"}
+└── dev.harnesspm/rules/usage.md  one rule, always on
+```
+
+The portable parts (skills and MCP servers) work in any Agent Plugins client, even without harnesspm.
+
+## 2.1 Location
+
+1. A package MUST put its harness in a folder named `harness/` at the package root.
+2. If `package.json` has a `files` field, it MUST include `harness`.
+3. harnesspm MUST NOT run any code from a package to discover its harness. Discovery reads files only.
+> pnpm 12.11 and later link package-root `skills/` folders from direct dependencies by themselves. harnesspm reads only `harness/skills/`, so the two never link the same skills twice.
+
+## 2.2 Layout
+
+A package that uses every unit kind:
+
+```text
+harness/
+├── plugin.json                       ← Agent Plugins manifest (required)
+├── skills/                           ← Agent Skills, one folder each
+│   └── uikit-review/
+│       └── SKILL.md
+├── mcp.json                          ← Agent Plugins MCP configuration
+└── dev.harnesspm/            ← harnesspm extension folder
+    ├── rules/
+    │   ├── forms.md
+    │   └── state-maps.md
+    ├── agents/
+    │   └── uikit-reviewer.md
+    ├── scripts/
+    │   ├── probe.mjs
+    │   └── check-styles.mjs
+    ├── hooks.json
+    └── permissions.json
+```
+
+Every file is optional except `plugin.json`. A package that has only one rule is valid.
+
+The extension folder name is the harnesspm namespace, `dev.harnesspm`, based on the domain `harnesspm.dev`. See [13-open-questions.md](13-open-questions.md#133-extension-namespace).
+
+## 2.3 Manifest
+
+`plugin.json` follows Agent Plugins 1.0. Its schema is closed, so all harnesspm fields go under `extensions["dev.harnesspm"]`.
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "uikit",
+  "description": "Rules, docs and tools for building UIs with @cube-dev/ui-kit",
+  "extensions": {
+    "dev.harnesspm": {
+      "extends": ["@tenphi/tasty", "@tenphi/glaze"],
+      "docs": "../docs/components",
+      "scripts": {
+        "probe": {
+          "file": "./dev.harnesspm/scripts/probe.mjs",
+          "description": "Capture a story's DOM and computed CSS",
+          "allow": true
+        },
+        "check-styles": { "file": "./dev.harnesspm/scripts/check-styles.mjs" }
+      },
+      "exclude": ["tasty:rules/legacy-tokens"],
+      "replace": { "tasty:rules/lint-comments": "./dev.harnesspm/rules/lint-comments.md" }
+    }
+  }
+}
+```
+
+### Core fields (Agent Plugins)
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `$schema` | yes | The Agent Plugins schema identifier. |
+| `name` | yes | The **plugin name**. Lowercase letters, digits, `-` and `.`. harnesspm uses it as the prefix in unit IDs and script names. |
+| `version` | no | If missing, harnesspm uses `version` from `package.json`. |
+| `description`, `author`, `homepage`, `repository`, `license`, `keywords` | no | Metadata, as defined by Agent Plugins. |
+
+### harnesspm extension fields
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `extends` | string[] | Packages whose harness this harness passes on. Resolved from this package's own folder. See [03-resolution.md](03-resolution.md#33-extends). |
+| `exclude` | string[] | Units or whole packages to drop from what this harness passes on. |
+| `replace` | object | Unit ID → path of a file that takes that unit's place. |
+| `patch` | object | Rule ID → path of a patch that changes some of its sections. See [2.5](#25-rules). |
+| `docs` | string | The folder with the package's docs. See [2.7](#27-docs). |
+| `scripts` | object | Script name → script definition. See [05-executables.md](05-executables.md#51-scripts). |
+| `projects` | object | Git remote → folder with units for that repository. Read only in added harnesses. See [07-added.md](07-added.md#72-example). |
+
+Unknown fields inside the extension MUST make `harnesspm check` fail, so typos do not ship.
+
+## 2.4 Unit kinds
+
+| Kind | Location | Format | Activation |
+| --- | --- | --- | --- |
+| Rule | `<ns>/rules/*.md` | Markdown with optional frontmatter | Always on, file-scoped, or on demand. See [2.5](#25-rules). |
+| Skill | `skills/<name>/SKILL.md` | [Agent Skills](https://agentskills.io/specification) | The agent loads it when relevant or when asked. |
+| Sub-agent | `<ns>/agents/*.md` | Markdown: `name` and `description` frontmatter, instructions in the body. See [2.6](#26-sub-agents). | The agent starts it. |
+| Doc | The folder named in `docs` | Markdown | Listed in an index. The agent reads a page when needed. |
+| Script | Named in `scripts` | Any executable file | Run through `harnesspm run`. |
+| Hook | `<ns>/hooks.json` | See [05-executables.md](05-executables.md#52-hooks) | The agent runs it on an event. |
+| MCP server | `mcp.json` | Agent Plugins MCP configuration | The agent starts it. |
+| Permission | `<ns>/permissions.json`, and `allow` on scripts | See [05-executables.md](05-executables.md#54-permissions) | The agent applies it. |
+
+`<ns>` is the extension folder, `dev.harnesspm`. A file that `replace` or `patch` names is not a unit of its own, even inside `rules/`.
+
+An agent picks a skill by its `description`. Say what the skill does, then, after "Use when", the situations and the words people use when they need it. Being picked is likely, not certain. When a skill must run in a situation, also add an always-on rule that names it: "To trace UI text, use the `uikit-text-origin` skill."
+
+## 2.5 Rules
+
+A rule is one Markdown file about one topic. Small files make overrides simple: a consumer replaces or drops a whole file, or patches a few of its sections.
+
+```markdown
+---
+description: How to write state maps in Tasty styles
+paths: ["**/*.tsx", "**/*.ts"]
+---
+
+# State maps
+
+- Put every state of one property in one map.
+- …
+```
+
+| Frontmatter | Activation |
+| --- | --- |
+| none | **Always on.** The text goes into the agent's main instructions. |
+| `paths`, with or without `description` | **File-scoped.** Active when the agent works on matching files. The description, if any, is the text of the pointer line. |
+| `description` only | **On demand.** Listed with its description. The agent reads it when relevant. |
+
+Always-on rules cost context in every session. A package SHOULD keep them short and move details into on-demand rules, docs or skills. `harnesspm check` reports the size of a package's always-on text.
+
+A package SHOULD split a rule into small sections with `##` headings, so that others can change one section with a patch.
+
+### Patches
+
+A patch changes some sections of a rule and keeps the rest. It is a Markdown file:
+
+```markdown
+---
+remove: ["Legacy tokens"]
+---
+
+## Disable comments
+
+Use `oxlint-disable-next-line`. `eslint-disable` comments are ignored in this project.
+```
+
+1. A **section** is a heading and everything up to the next heading of the same or a higher level.
+2. Each section in the patch **replaces** the section with the same heading text and level in the rule.
+3. A section whose heading the rule does not have is **added** at the end.
+4. Text before the first heading of the patch is **added** at the end of the rule.
+5. `remove` in the frontmatter lists headings whose sections are **removed**.
+
+A patch keeps the rule's ID. `harnesspm why` lists the patches applied to a unit. Patches work on rules only. Where patches come from and in which order they apply is defined in [03-resolution.md](03-resolution.md#34-priority).
+
+## 2.6 Sub-agents
+
+```markdown
+---
+name: uikit-reviewer
+description: Reviews UI changes against UI Kit rules. Use for UI pull requests.
+claude: { tools: "Read, Grep, Glob", model: "sonnet" }
+codex: { model_reasoning_effort: "medium" }
+---
+
+Review the change like an owner. Do not edit files.
+```
+
+| Part | Claude Code | Codex |
+| --- | --- | --- |
+| `name`, `description` | frontmatter | `name`, `description` |
+| Body | the prompt | `developer_instructions` |
+| `claude:` | copied into the frontmatter | ignored |
+| `codex:` | ignored | copied into the TOML file |
+
+Only `name`, `description` and the body are portable. Agent-specific settings, such as models and tool limits, go under the agent's own key. Keys that widen what the agent may do (`permissionMode` for Claude Code, `sandbox_mode` and `approval_policy` for Codex) are written only for the project, added harnesses and trusted packages.
+
+## 2.7 Docs
+
+```json
+"docs": "../docs"
+```
+
+1. The path is relative to `harness/`. It MAY point outside `harness/` but MUST stay inside the package.
+2. If `<dir>/llms.txt` exists, harnesspm uses it as the index. Its format is the [llms.txt](https://llmstxt.org/) convention: a Markdown list of links with short descriptions.
+3. Otherwise harnesspm builds the index from every `.md` and `.mdx` page. A page's title is its frontmatter `title`, else its first heading, else its file name. Its frontmatter `description` follows the link. To leave pages out, write an `llms.txt`.
+4. The index points at the files of the **installed** version. See [04-outputs.md](04-outputs.md#42-stable-package-paths).
+
+## 2.8 Unit IDs
+
+Every unit has an ID: `<plugin name>:<kind>/<name>`.
+
+| Unit | ID |
+| --- | --- |
+| `harness/dev.harnesspm/rules/state-maps.md` in plugin `tasty` | `tasty:rules/state-maps` |
+| `harness/skills/uikit-review/` in plugin `uikit` | `uikit:skills/uikit-review` |
+| script `probe` in plugin `uikit` | `uikit:scripts/probe` |
+| server `docs` in `mcp.json` of plugin `uikit` | `uikit:mcp/docs` |
+| hook entry with `"id": "check-styles"` | `uikit:hooks/check-styles` |
+| `harness/dev.harnesspm/agents/uikit-reviewer.md` | `uikit:agents/uikit-reviewer` |
+| the docs of plugin `uikit` | `uikit:docs` |
+| `permissions.json` of plugin `uikit` | `uikit:permissions` |
+
+`exclude` also accepts a package name, such as `@tenphi/glaze`, to drop a whole package.
+
+Commands name scripts and MCP servers in a short form, `<plugin name>:<name>`: `harnesspm run uikit:probe`, `harnesspm mcp uikit:docs`. Agents see an MCP server as `<plugin name>-<server>`, such as `uikit-docs`.
+
+## 2.9 Naming rules
+
+1. Plugin names MUST be unique within one resolved graph. On a clash, harnesspm stops and names both packages. The consumer can then exclude one of them.
+2. **harnesspm never renames a skill.** The Agent Skills format requires a skill's `name` to match its folder name, and agents look skills up by that name.
+3. Skill names SHOULD start with the plugin name, such as `uikit-review`, so names from different packages do not collide. `harnesspm check` warns when they do not.
+4. When two layers ship a skill with the same name, the higher layer wins and harnesspm prints a warning.
+5. Script names MUST be unique within a plugin. Agents call them as `<plugin name>:<script>`, such as `uikit:probe`.
+
+## 2.10 Validation
+
+`harnesspm check` runs at `prepack` and fails when:
+
+- `plugin.json` or `mcp.json` breaks the Agent Plugins schema;
+- a skill breaks the Agent Skills format;
+- a harnesspm extension field is unknown or has the wrong type;
+- a path points outside the package, or at a file the npm tarball would not include;
+- a link in a rule, skill or doc points at a file that will not be published.

package/docs/spec/03-resolution.md

@@ -0,0 +1,104 @@
+# 3. Resolution
+
+**In short**
+
+- Three layers, lowest to highest: **dependencies**, **project**, **added** harnesses.
+- A dependency passes on the harness of other packages only through `extends`.
+- A higher layer changes units below it only through `exclude`, `replace` and `patch`. Unit IDs never clash between packages, because plugin names are unique.
+
+## 3.1 Layers
+
+| Layer | Source | Committed outputs? |
+| --- | --- | --- |
+| 📦 **Dependencies** | Harness packages in the project's dependencies, and what they `extends` | yes |
+| 🏢 **Project** | `harnesspm.json` and the project's own `harness/` | yes |
+| ➕ **Added** | Harnesses a person adds on top (see [07-added.md](07-added.md)). User scope first, then local scope, each in the order added | no |
+
+Committed outputs MUST be computed from the dependency and project layers only. Two teammates with different added harnesses produce identical committed files.
+
+## 3.2 Discovery
+
+For each workspace, harnesspm starts from its `dependencies`, `devDependencies` and `optionalDependencies`:
+
+1. Resolve each one from the workspace folder, the way Node.js does.
+2. Keep it if it has a `harness/` folder.
+3. Follow `extends` of every kept package (see [3.3](#33-extends)).
+
+harnesspm reads files only. It never runs code from a dependency during discovery. Every dependency with a harness is included unless the project excludes it.
+
+## 3.3 Extends
+
+`extends` lets a package pass on the harness of packages it builds on.
+
+```json
+"extends": ["@tenphi/tasty", "@tenphi/glaze"]
+```
+
+1. Each name MUST be resolved **from the folder of the package that declares it**, so the version is the one that package uses. When copies with different versions remain, [3.5](#35-one-package-several-versions) picks one.
+2. harnesspm follows `extends` recursively and stops with an error on a cycle.
+3. Only `extends` passes harness on. A library's other dependencies, including its development tools, never reach its users.
+4. A package's `exclude`, `replace` and `patch` change what it passes on. A middle package can fix an upstream rule for all its users.
+
+Example: an app depends only on `@cube-dev/ui-kit`, which extends Tasty and Glaze. The app gets all three, in the versions UI Kit installed.
+
+## 3.4 Priority
+
+Packages in the dependency layer are ordered **upstream first**: a package comes after the packages it extends. Unrelated packages are ordered by name.
+
+| Situation | Result |
+| --- | --- |
+| A project entry repeats a unit ID of its own harness | The entry's unit wins. |
+| `exclude` names a unit or a package | It is dropped, with everything only it extends. |
+| `replace` names a unit | The new file takes the unit's ID and place. |
+| `patch` names a rule | Its sections change as defined in [02-package-format.md](02-package-format.md#25-rules). |
+| Two skills have the same name | The later one wins, with a warning. |
+| An override names a unit that does not exist | Warning. It usually means an upstream unit was renamed. |
+
+For one rule, harnesspm takes the original or the highest `replace`, then applies every patch from the layers above it, lowest layer first. A patch from a layer below the winning `replace` is dropped with a warning.
+
+When an upgrade changes a section that a patch replaces or removes, `harnesspm sync` warns and names the section, because the patch may now be out of date. The lock stores a hash of each such section to detect this.
+
+## 3.5 One package, several versions
+
+Outputs point at one stable path per package ([04-outputs.md](04-outputs.md#42-stable-package-paths)), so harnesspm uses one version of each package in a repository:
+
+1. A direct dependency of a workspace wins.
+2. Otherwise the copy closest to a workspace in the `extends` chain wins.
+3. Among equals, the highest version wins.
+
+harnesspm warns and names the versions.
+
+## 3.6 Monorepos
+
+Workspaces come from the `workspaces` field of the root `package.json` or from `pnpm-workspace.yaml`.
+
+1. Each workspace is resolved on its own dependencies, from its own folder. Backend workspaces do not get frontend rules.
+2. Units that the root reaches, or that every workspace shares, are written once, at the root.
+3. A workspace's own `harness/` belongs to that workspace. A workspace that another workspace depends on is still the project's own code, so it is in the project layer and trusted.
+4. Executable units are written at the root, where both agents read them.
+5. One version per package applies to the whole repository ([3.5](#35-one-package-several-versions)).
+
+## 3.7 Project configuration
+
+`harnesspm.json` is committed. Every field is optional.
+
+```json
+{
+  "$schema": "https://unpkg.com/@tenphi/harnesspm/schema/harnesspm.schema.json",
+  "exclude": ["@tenphi/glaze"],
+  "patch": { "tasty:rules/lint-comments": "./harnesspm/patches/tasty-lint-comments.patch.md" },
+  "trust": { "@cube-dev/ui-kit": true }
+}
+```
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `$schema` | — | The JSON schema, for editors. |
+| `exclude` | `[]` | Packages or unit IDs to drop. |
+| `replace` | `{}` | Unit ID → path of a project file that takes its place. |
+| `patch` | `{}` | Rule ID → path of a project patch that changes some of its sections. |
+| `trust` | `{}` | Which packages may run executable units. See [06-trust.md](06-trust.md). |
+
+The project's own `harness/`, if it has one, resolves like any harness package: its `extends` bring packages into the dependency layer, and its `exclude`, `replace` and `patch` apply here as they do for its users. `harnesspm.json` applies after it, for this repository only. So contributors see what users see, plus the repository's own changes.
+
+harnesspm writes outputs for both Claude Code and Codex. Outputs for an agent a person does not use cost nothing: they are per machine and excluded from git.

package/docs/spec/04-outputs.md

@@ -0,0 +1,109 @@
+# 4. Outputs
+
+**In short**
+
+- harnesspm writes each agent's **native** files, where the agent already looks.
+- Of the outputs, only the managed blocks in `AGENTS.md`, the `@AGENTS.md` lines in `CLAUDE.md` and `harnesspm.lock.json` are committed. Everything else is written on each machine and kept out of git.
+- People never edit outputs. Every output names its source.
+
+Package authors do not need this chapter. It defines what implementations write.
+
+## 4.1 Principles
+
+1. **Native files only.** No agent has to understand a harnesspm format.
+2. **Commit only what reviewers need.** The managed block in `AGENTS.md` shows rule changes in pull requests. The lock shows every other unit change. All other outputs are per machine.
+3. **Per-machine outputs are excluded through `.git/info/exclude`.** That file belongs to the clone, is never committed, and is shared by worktrees. harnesspm never edits `.gitignore`.
+4. **Units of added harnesses never enter a tracked file.** harnesspm MUST refuse to write one there.
+5. **Outputs are marked.** Each generated file or block says it is generated and names the sources to edit.
+6. **harnesspm edits only its own entries** in files that people or agents also write, and keeps the rest unchanged.
+
+## 4.2 Stable package paths
+
+Package managers place packages at paths that differ between machines. harnesspm creates one stable link per harness package and uses only these paths in outputs:
+
+```
+node_modules/.harnesspm/pkgs/@tenphi/tasty  →  <real location of the package>
+```
+
+A job that does not install dependencies, such as a review bot, runs `npx -y @tenphi/harnesspm fetch`. It downloads only the harness packages in the lock with `npm pack`, checks each tarball against the lock's integrity, and fills these paths and the generated files, so pointers in the committed block work there too. It reuses installed copies, never runs package code and writes no agent settings.
+
+## 4.3 Project outputs
+
+These hold the dependency and project layers, plus added harnesses with local scope and the project entries of all added harnesses.
+
+| Unit | Claude Code | Codex |
+| --- | --- | --- |
+| Always-on rules, docs index, script list (team) | Managed block in `AGENTS.md` (committed), reached through `@AGENTS.md` in `CLAUDE.md` | Managed block in `AGENTS.md` (committed) |
+| Always-on rules (added harnesses) | Managed block in `CLAUDE.local.md` | `developer_instructions` in `.codex/config.toml` |
+| File-scoped rules | Link in `.claude/rules/harnesspm/<plugin>/` with `paths`, plus a pointer line in the block | Pointer line in the block |
+| On-demand rules | Pointer line with its description | Pointer line with its description |
+| Skills | Link in `.claude/skills/<name>`, plus `Skill(<name>)` in `permissions.allow` of `.claude/settings.local.json` for skills from the project, an added harness or a trusted package | Link in `.agents/skills/<name>` |
+| Sub-agents | Generated `.claude/agents/<name>.md` | Generated `.codex/agents/<name>.toml` |
+| Hooks, permissions | Entries in `.claude/settings.local.json` | `.codex/hooks.json`, `.codex/rules/harnesspm.rules` |
+| MCP servers | Local scope: `projects.<project>.mcpServers` in `~/.claude.json`, where `claude mcp add-json --scope local` writes them | `[mcp_servers.<id>]` in `.codex/config.toml` |
+
+Notes:
+
+1. `CLAUDE.local.md` counts as a `CLAUDE.md` for Claude Code. In a repository with only `AGENTS.md`, harnesspm MUST start `CLAUDE.local.md` with `@AGENTS.md`, or Claude would stop reading `AGENTS.md`.
+2. harnesspm owns `.codex/` and writes it on each machine. If a team already commits `.codex/config.toml`, harnesspm does not touch it and `harnesspm status` lists the units Codex is missing. The team moves those settings into `harness/`, which feeds both agents.
+3. A file-scoped rule has two outputs for Claude Code on purpose: the link activates it natively on matching files, and the pointer line in the shared block serves Codex.
+4. File-scoped and on-demand rules of added harnesses are pointer lines with absolute paths, in `CLAUDE.local.md` and the user-level blocks. They get no `.claude/rules/` link, because Claude Code treats a link to a file outside the working folder as an external import that needs approval. Patched rules and docs indexes of added harnesses are generated into `~/.harnesspm/generated/`, because a repository may have no `node_modules`.
+5. An added harness's `exclude` or `patch` of a team always-on rule cannot change committed text. harnesspm writes the change into the local block instead ("ignore rule X", or "in rule X, section Y now says: …"), which both agents read after the team block.
+
+## 4.4 Outputs of added harnesses, user scope
+
+These go to the agents' user-level folders, so they work in every repository, including ones without harnesspm.
+
+| Unit | Claude Code | Codex |
+| --- | --- | --- |
+| Rules | Managed block in `~/.claude/CLAUDE.md` | Managed block in `~/.codex/AGENTS.md` |
+| Skills | Link in `~/.claude/skills/`, plus `Skill(<name>)` in `permissions.allow` of `~/.claude/settings.json` | Link in `~/.agents/skills/` |
+| Sub-agents | Generated in `~/.claude/agents/` | Generated in `~/.codex/agents/` |
+| Hooks, permissions | Entries in `~/.claude/settings.json` | `~/.codex/hooks.json`, `~/.codex/rules/harnesspm.rules` |
+| MCP servers | User scope: `mcpServers` in `~/.claude.json` | `[mcp_servers.<id>]` in a managed block at the end of `~/.codex/config.toml` |
+| Write access to the working copies of added harnesses | `permissions.additionalDirectories` | `sandbox_workspace_write.writable_roots` |
+| The hook that applies added harnesses in each repository ([07-added.md](07-added.md#75-applying-in-every-repository)) | `SessionStart` entry in `~/.claude/settings.json` | `SessionStart` entry in `~/.codex/hooks.json` |
+
+## 4.5 Monorepos
+
+1. A workspace with its own units gets a managed block in `<workspace>/AGENTS.md`. Codex joins `AGENTS.md` files from the root down to the current folder. Paths in a workspace's block are relative to its folder. A block that becomes empty is removed, and so is a file that held only the block.
+2. Claude Code does not read a nested `AGENTS.md` when the root has a `CLAUDE.md`. harnesspm writes `<workspace>/CLAUDE.md` with `@AGENTS.md` when it is missing. Both files are committed.
+3. Skills and executable units are written at the root.
+
+## 4.6 Managed blocks
+
+A managed block is the only part of a Markdown file harnesspm owns. Text outside it never changes. Without markers, harnesspm appends a block at the end.
+
+```markdown
+<!-- BEGIN:harnesspm — generated by `harnesspm sync`. Do not edit. To change a rule, run `npx harnesspm why <ID>`. -->
+## @tenphi/tasty 3.17.1 (via @cube-dev/ui-kit)
+
+- Never put dynamic values into styles. Use tokens. (tasty:rules/style-values)
+- When editing `**/*.tsx`, read node_modules/.harnesspm/pkgs/@tenphi/tasty/harness/dev.harnesspm/rules/state-maps.md (tasty:rules/state-maps)
+- Docs: node_modules/.harnesspm/pkgs/@tenphi/tasty/docs/llms.txt
+
+## @cube-dev/ui-kit 0.206.1
+
+- …
+- Scripts: `npx harnesspm run uikit:probe <story>` — capture a story's DOM and computed CSS
+<!-- END:harnesspm -->
+```
+
+Every line carries its unit ID, so an agent can find the source with `harnesspm why`.
+
+## 4.7 Files shared with people
+
+`CLAUDE.md` files, `~/.codex/AGENTS.md`, `.claude/settings.local.json` and `~/.claude/settings.json` are also written by people, or by the agent itself (Claude Code saves "don't ask again" approvals into `.claude/settings.local.json`). In these files, and in `~/.claude.json`, `.codex/hooks.json` and `~/.codex/config.toml`, harnesspm changes only its managed block or the entries it created. It records its entries in a per-machine state file, `harnesspm/state.json` in the clone's git folder or `~/.harnesspm/state.json`, so it can remove them later. A settings file that held only harnesspm's entries is deleted with them.
+
+## 4.8 Why native files and not plugins
+
+Both agents have plugin systems. harnesspm does not generate plugins in v1, because Claude Code cloud sessions do not install plugins that a repository declares, and plugins hide changes from pull request review. See [13-open-questions.md](13-open-questions.md#135-plugin-output-mode).
+
+## 4.9 Size limits
+
+| Agent | Limit |
+| --- | --- |
+| Codex | `AGENTS.md` files are joined up to `project_doc_max_bytes`, 32 KiB by default. The rest is cut off. |
+| Claude Code | No hard limit. The vendor advises under about 200 lines per `CLAUDE.md`. |
+
+`harnesspm status` reports the always-on size per agent and per package, and warns near a limit.

package/docs/spec/05-executables.md

@@ -0,0 +1,158 @@
+# 5. Executables
+
+**In short**
+
+- A package declares **scripts**. Agents and hooks run them through one command: `npx harnesspm run <plugin>:<script>`. MCP servers start through `npx harnesspm mcp <plugin>:<server>`.
+- Hooks and MCP servers are written once and translated for each agent.
+- A package can allow only its own scripts. It can always restrict (deny, ask).
+- Nothing executable runs unless the project trusts the package ([06-trust.md](06-trust.md)).
+
+## 5.1 Scripts
+
+A script is a file a package ships for agents, hooks or MCP servers to run.
+
+```json
+"scripts": {
+  "probe": {
+    "file": "./dev.harnesspm/scripts/probe.mjs",
+    "description": "Capture a story's DOM and computed CSS",
+    "allow": true
+  }
+}
+```
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `file` | yes | Path inside `harness/`, starting with `./`. |
+| `description` | no | Shown to the agent in the script list. Without it, the script is hidden from the agent and only hooks and MCP servers use it. |
+| `allow` | no | The producer suggests that agents may run it without asking. Takes effect only when the consumer trusts the package. See [5.4](#54-permissions). |
+
+### The runner
+
+Every script runs through one command:
+
+```bash
+npx harnesspm run uikit:probe -- --story Button
+```
+
+The runner:
+
+1. finds the package through the stable path in `node_modules/.harnesspm/pkgs/`, so the installed version always runs;
+2. refuses the script when its package is not trusted, when the installed version differs from the lock (run `harnesspm sync`), or when a `"pin"` package has a version nobody approved;
+3. picks the interpreter from the file: `node` for `.js`, `.mjs` and `.cjs`, `sh` for `.sh`, otherwise the file itself;
+4. sets these environment variables:
+
+| Variable | Value |
+| --- | --- |
+| `PLUGIN_ROOT` | The package's `harness/` folder (same meaning as in Agent Plugins) |
+| `PLUGIN_DATA` | `~/.harnesspm/data/<plugin name>/`, kept across updates (same meaning as in Agent Plugins) |
+| `HARNESSPM_PROJECT_DIR` | The project root |
+| `HARNESSPM_AGENT` | `claude`, `codex`, or empty when a person runs it. harnesspm puts it into the hook and MCP commands it writes, and reads the agent's marker for a script an agent runs ([06-trust.md](06-trust.md#62-trusting-a-package), rule 4). |
+
+The runner must start fast, because hooks call it on every matching tool call.
+
+Why a runner instead of file paths:
+
+- one command works with every package manager and folder layout;
+- permission rules match one stable prefix in both agents;
+- hooks, MCP servers and skills use the same command, so a `SKILL.md` works on every machine.
+
+## 5.2 Hooks
+
+Claude Code and Codex use nearly the same hook model: event → matcher → command, JSON on stdin, exit code `0` to continue and `2` to block with the reason on stderr. harnesspm's format keeps that shape.
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "id": "check-styles",
+        "matcher": { "claude": "Edit|Write" },
+        "run": "check-styles",
+        "timeout": 30
+      }
+    ]
+  }
+}
+```
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `id` | yes | Unit name. The ID becomes `<plugin>:hooks/<id>`. |
+| `run` | yes | A script name from `scripts`. harnesspm writes the full command for each agent. |
+| `matcher` | no | A string for both agents, or an object with a `claude` key, a `codex` key or both. With an object, the hook is written only for the agents it names. Tool names differ between agents (for example, file edits), so an object is common. Without a matcher, the hook matches every tool in both agents. |
+| `timeout` | no | Seconds. |
+
+### Events
+
+Portable events, supported by both agents: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SubagentStart`, `SubagentStop`, `Stop`.
+
+harnesspm writes a hook only for the agents that support its event.
+
+### Contract for hook scripts
+
+1. The script reads the agent's own JSON on stdin. `HARNESSPM_AGENT` says which agent sent it.
+2. Exit `0` continues. Exit `2` blocks, for events that support blocking, with the reason on stderr.
+3. JSON on stdout, such as `hookSpecificOutput.permissionDecision`, follows the agent's own format.
+
+Agent Plugins has an open proposal for portable hooks ([PR #89](https://github.com/agentplugins/agent-plugins-spec/pull/89)). If it becomes part of the standard, harnesspm reads the standard file as well and keeps its own format working during a migration period.
+
+## 5.3 MCP servers
+
+MCP servers use the Agent Plugins `mcp.json` format.
+
+```json
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "docs": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${PLUGIN_ROOT}/dev.harnesspm/scripts/docs-mcp.mjs"]
+    },
+    "figma": { "type": "streamable-http", "url": "https://example.com/mcp" }
+  }
+}
+```
+
+harnesspm writes each server under the name `<plugin name>-<server>`, such as `uikit-docs`. For a server from the project, an added harness or a trusted package, it also writes an allow rule for its tools in Claude Code (`mcp__uikit-docs`), because MCP tool calls ask for approval even in cloud sessions. A trusted server already runs the package's code, so its tools need no opt-in of their own. Codex gets no rule.
+
+- **stdio servers** are written as `npx harnesspm mcp uikit:docs`. The runner expands `${PLUGIN_ROOT}` and `${PLUGIN_DATA}`, sets the environment from [5.1](#51-scripts) and starts the server. Both agents get the same command.
+- **Remote servers** are written as they are. Secrets never go into `mcp.json`. Authentication stays with the agent.
+
+## 5.4 Permissions
+
+A dependency MUST NOT be able to grant itself broad rights. harnesspm writes allow rules only for units from the project, an added harness or a trusted package, and only for three things: skills, scripts with `"allow": true`, and MCP servers ([5.3](#53-mcp-servers)). Deny and ask rules pass through freely.
+
+**Skills get an allow rule to run unattended.** Outside cloud sessions, Claude Code asks before it invokes a skill, and a headless run denies the call. For each skill from the project's own harness, an added harness or a trusted package, harnesspm writes `Skill(<name>)` into `permissions.allow`. The `allowed-tools` field inside a `SKILL.md` does not replace this: it only pre-approves tools while the skill runs. In cloud sessions the rule changes nothing ([5.5](#55-what-the-agents-still-decide)).
+
+**Scripts get an allow rule when they ask for one.** When a script has `"allow": true` and the consumer trusts the package, harnesspm writes:
+
+| Agent | Rule |
+| --- | --- |
+| Claude Code | `Bash(npx harnesspm run uikit:probe *)` in `permissions.allow` |
+| Codex | `prefix_rule(pattern=["npx", "harnesspm", "run", "uikit:probe"], decision="allow")` |
+
+**Deny and ask rules** only restrict. They are written as command prefixes:
+
+```json
+{
+  "deny": [["git", "push", "--force"]],
+  "ask": [["npm", "publish"]]
+}
+```
+
+| Neutral | Claude Code | Codex |
+| --- | --- | --- |
+| `deny` | `Bash(git push --force *)` in `permissions.deny` | `prefix_rule(…, decision="forbidden")` |
+| `ask` | `Bash(npm publish *)` in `permissions.ask` | `prefix_rule(…, decision="prompt")` |
+
+## 5.5 What the agents still decide
+
+harnesspm adds a gate. It does not remove the agents' own gates:
+
+| Agent | Own gate |
+| --- | --- |
+| Claude Code | Allow rules in the untracked `.claude/settings.local.json` apply without the workspace trust step, because the file belongs to the person. harnesspm's trust is the main gate here. |
+| Claude Code cloud sessions | A platform rule approves built-in tools, even in default mode, but not MCP tools. Deny rules from settings still apply and win. The gates are harnesspm's trust, which decides which hooks, MCP servers and scripts exist, the lock check in `harnesspm run`, and deny rules. |
+| Codex | Project `.codex/` files load only when the project is trusted. Each hook is reviewed by its hash in `/hooks`. |