projectstore-codex 0.0.1 → 0.28.1

package/node_modules/projectstore/harnesses/claude-code.json

@@ -0,0 +1,483 @@
+{
+  "_comment": "Harness capability manifest — Claude Code. This is the SOURCE layout (generation spec, contract 2): the plugin's own commands/, agents/, skills/ and hooks/hooks.json are already in Claude Code's shapes, so nothing is emitted for it (emit: false). The manifest still exists in full because the portability lint reads every harness's vocabulary, and a token only Claude Code understands is only detectable as unmapped in another harness's tree if Claude Code's own names are written down somewhere. It carries no `lint` block and an empty `rewrites` because linting runs over emitted trees only. Shape contributed by Maxim Podreshetnikov (PR #13); `verified`, `output_channels`, `scope_reason`, `root_placeholder_literal` and `agent_overrides` are the spec's additions.",
+  "id": "claude-code",
+  "display_name": "Claude Code",
+  "emit": false,
+  "source_layout": true,
+  "output_dir": null,
+  "docs": "https://code.claude.com/docs",
+  "verified": {
+    "session": "the shipped plugin's own hooks, run continuously in this repository under Claude Code 2.1.163+ — not one session but daily operation; each output_channels row cites where the fact is observed",
+    "date": "2026-09-04"
+  },
+  "install": {
+    "mechanism": "the package's own registration through its distribution shell, or the built-in plugin marketplace",
+    "shell": "projectstore-claude",
+    "shell_reason": "the distribution shell that installs this harness from npm (the layout ADR decision 6; the shells ADR): `npx projectstore-claude install --project <dir>` is the core's `install --harness claude-code`, with the core pinned at the same version and bundled inside the shell's tarball. Data, not `projectstore-<id>`: the id is claude-code and the reserved, published name is projectstore-claude. Every command a finding or a deferred reason names is built from this key (harness.mjs packageCommand).",
+    "why_not_scripted": "Two channels. `npx projectstore-claude install --project <dir>` registers the plugin for that project from the npm package itself — the shell bundles the core and fixes the harness; the core's low-level form is `npx projectstore install --harness claude-code --project <dir>` — through a local marketplace under the Claude home, driven by Claude Code's own `claude plugin` CLI. `/plugin install projectstore@SmartAndPoint` installs it from the git marketplace. `/plugin` lists and toggles either. Upgrading the npm registration is `npx projectstore-claude@<version> upgrade --project <dir>` — that is also the pin.",
+    "steps": [
+      "npx projectstore-claude install --project \"$PWD\"   (npm; registers the plugin for this project — the shell runs the core's install with the harness fixed)",
+      "/plugin marketplace add SmartAndPoint/ProjectStore && /plugin install projectstore@SmartAndPoint   (git marketplace, user-wide)",
+      "restart Claude Code"
+    ],
+    "notes": [
+      "Git marketplace only: auto-update is OFF by default for third-party plugins: /plugin -> Marketplaces -> SmartAndPoint -> toggle auto-update. The npm registration updates when you run `npx projectstore-claude upgrade --project <dir>`.",
+      "Pin a git-marketplace release with: /plugin marketplace add SmartAndPoint/ProjectStore#<tag>; pin the npm registration with npx projectstore-claude@<version>.",
+      "Two enabled copies of the plugin (git marketplace and npm) in one checkout would load twice; the npm registration silences the other one for that checkout only (settings.local.json), and says so in its preview.",
+      "From a checkout instead: claude --plugin-dir ./ProjectStore",
+      "The npm registration is per checkout (local scope) and per machine; a fresh clone or a new worktree runs the install command again. It must run from a terminal outside a Claude Code session: the host CLI and a live session both rewrite settings files."
+    ],
+    "docs": "https://github.com/SmartAndPoint/ProjectStore#install--one-message"
+  },
+  "runtime": {
+    "detect_env": [
+      "CLAUDE_PLUGIN_ROOT",
+      "CLAUDE_PROJECT_DIR",
+      "CLAUDE_CONFIG_DIR"
+    ],
+    "project_dir_env": "CLAUDE_PROJECT_DIR",
+    "plugin_root_env": "CLAUDE_PLUGIN_ROOT",
+    "home_env": "CLAUDE_CONFIG_DIR",
+    "home_default": ".claude",
+    "harness_dir": ".claude",
+    "harness_dir_reason": "the harness's own directory in a project: how it is detected, where its settings live — never where projectstore's config is (the layout ADR, 2026-09-06: that is <project>/.projectstore/, one for every harness)",
+    "agent_overrides": [
+      {
+        "env": "CLAUDE_CODE_EFFORT_LEVEL",
+        "kind": "effort",
+        "beats": "agent frontmatter"
+      },
+      {
+        "env": "CLAUDE_CODE_SUBAGENT_MODEL",
+        "kind": "model",
+        "beats": "every projectstore model configuration, per-invocation parameter included"
+      }
+    ],
+    "session_env": [
+      "CLAUDECODE"
+    ],
+    "session_env_reason": "set to 1 in every Bash tool of a live session (measured 2026-09-05, 2.1.261); detect_env names the variables a hook or plugin process receives, which a Bash tool does not — the two questions differ.",
+    "overlay": "claude-code",
+    "overlay_reason": "the file under <project>/.projectstore/harness/ that carries this harness's agents block — the models, per agent, that plugin surfaces pass per invocation (ADR-008; the layout ADR decision 3)"
+  },
+  "tools": {
+    "write_tools": [
+      "Write",
+      "Edit",
+      "MultiEdit",
+      "NotebookEdit"
+    ],
+    "path_fields": [
+      "file_path",
+      "notebook_path",
+      "path"
+    ],
+    "patch_envelope_field": null,
+    "approval_tool": "AskUserQuestion",
+    "write_tool_name": "the Write tool",
+    "edit_tool_name": "the Edit tool",
+    "known_non_write_tools": [
+      "Bash",
+      "Read",
+      "Grep",
+      "Glob",
+      "LS",
+      "WebFetch",
+      "WebSearch",
+      "Task",
+      "TodoWrite"
+    ]
+  },
+  "hooks": {
+    "config_file": "hooks/hooks.json",
+    "events": {
+      "SessionStart": "SessionStart",
+      "PreToolUse": "PreToolUse",
+      "PostToolUse": "PostToolUse",
+      "Stop": "Stop",
+      "PreCompact": "PreCompact"
+    },
+    "unsupported_events": [],
+    "matchers": {
+      "write": "Edit|Write|MultiEdit|NotebookEdit"
+    },
+    "root_placeholder": "${CLAUDE_PLUGIN_ROOT}",
+    "root_placeholder_literal": false,
+    "_root_placeholder_literal_comment": "true = the harness passes the placeholder through as literal text and the installer must substitute an absolute path; false = the harness expands it. Claude Code expands ${CLAUDE_PLUGIN_ROOT}, so false. Measured value for Codex comes from the spike."
+  },
+  "output_channels": {
+    "_comment": "Per-event output channels (generation spec, contract 17). `fields` are the hookSpecificOutput keys the event honours; `system_message` is the top-level systemMessage; `decision` names the decision object where one exists. `evidence` is `measured` only where this repository's own hooks observe the fact, `documented` where the Claude Code hooks reference says so and we never emit it.",
+    "SessionStart": {
+      "fields": [
+        "additionalContext"
+      ],
+      "system_message": true,
+      "decision": null,
+      "evidence": "measured",
+      "note": "hooks/session-start.mjs emits additionalContext and systemMessage in one object; the ~10,000-character cap on additionalContext was measured (vault story: SessionStart context exceeds the hook output cap)."
+    },
+    "PreToolUse": {
+      "fields": [
+        "permissionDecision",
+        "permissionDecisionReason",
+        "updatedInput",
+        "additionalContext"
+      ],
+      "system_message": true,
+      "decision": "permissionDecision",
+      "evidence": "measured",
+      "note": "systemMessage measured — scripts/touch-session.mjs uses it for the pointer nudge and the name offer. additionalContext and permissionDecision (allow|deny|ask) are documented; projectstore never emits them. A separate PermissionRequest event carries its own decision object."
+    },
+    "PostToolUse": {
+      "fields": [
+        "additionalContext"
+      ],
+      "system_message": null,
+      "decision": null,
+      "evidence": "measured",
+      "note": "scripts/touch-session.mjs — the entry-rule reminder's primary carrier (entry-rule spec, contract 14)."
+    },
+    "PostToolUseFailure": {
+      "fields": [
+        "additionalContext"
+      ],
+      "system_message": null,
+      "decision": null,
+      "evidence": "documented",
+      "note": "Hooks reference; not registered by projectstore."
+    },
+    "PostToolBatch": {
+      "fields": [
+        "additionalContext"
+      ],
+      "system_message": null,
+      "decision": null,
+      "evidence": "documented",
+      "note": "Hooks reference; not registered by projectstore."
+    },
+    "UserPromptSubmit": {
+      "fields": [
+        "additionalContext"
+      ],
+      "system_message": null,
+      "decision": null,
+      "evidence": "documented",
+      "note": "Hooks reference; not registered by projectstore."
+    },
+    "Stop": {
+      "fields": [
+        "additionalContext"
+      ],
+      "system_message": null,
+      "decision": "block",
+      "evidence": "measured",
+      "min_version": "2.1.163",
+      "note": "additionalContext on Stop CONTINUES the turn (2.1.163 changelog) — hooks/session-stop.mjs runs a create-then-emit election because of it. Below 2.1.163 only decision:block + reason exists."
+    },
+    "SubagentStop": {
+      "fields": [
+        "additionalContext"
+      ],
+      "system_message": null,
+      "decision": "block",
+      "evidence": "documented",
+      "note": "Same channel as Stop per the 2.1.163 changelog; not registered by projectstore — a subagent is the actor that cannot open a story."
+    },
+    "PreCompact": {
+      "fields": [],
+      "system_message": true,
+      "decision": null,
+      "evidence": "measured",
+      "note": "Measured NEGATIVELY: an output object containing additionalContext is rejected whole, taking systemMessage down with it (hooks/pre-compact.mjs; vault story: PreCompact survival packet targets a channel PreCompact does not have). Only top-level decision/reason and systemMessage exist."
+    }
+  },
+  "surfaces": {
+    "commands": {
+      "supported": true,
+      "kind": "host",
+      "dir": "commands",
+      "file": "<name>.md",
+      "format": "command-md",
+      "invocation": "/projectstore:<name>",
+      "scope": "user",
+      "scope_reason": "Claude Code loads commands from the plugin installation itself, not from a per-project directory.",
+      "registered_by": "plugin"
+    },
+    "agents": {
+      "supported": true,
+      "kind": "host",
+      "dir": "agents",
+      "file": "<name>.md",
+      "format": "agent-md",
+      "invocation": "projectstore:<name>",
+      "scope": "user",
+      "scope_reason": "Claude Code loads agents from the plugin installation itself, not from a per-project directory.",
+      "registered_by": "plugin"
+    },
+    "skills": {
+      "supported": true,
+      "kind": "host",
+      "dir": "skills",
+      "file": "<name>/SKILL.md",
+      "format": "skill-md",
+      "scope": "user",
+      "scope_reason": "Claude Code loads skills from the plugin installation itself, not from a per-project directory.",
+      "registered_by": "plugin",
+      "frontmatter_required": [
+        "name",
+        "description"
+      ],
+      "frontmatter_reason": "`description` is what Claude Code matches a skill on; `name` was added 2026-09-08 because Codex's documentation requires it and this is the tree both harnesses load until the generator renders one per harness. Harmless here, required there.",
+      "invocation": null,
+      "invocation_reason": "UNMEASURED. Claude Code activates a skill from its description rather than from a form the user types; there is no explicit call syntax to record, and null says that rather than leaving the key out and reading as forgotten.",
+      "unrendered_source": false,
+      "unrendered_source_reason": "This IS the source tree (source_layout: true), so there is nothing to render and no foreign vocabulary to leak into it."
+    },
+    "hooks": {
+      "supported": true,
+      "kind": "host",
+      "dir": "hooks",
+      "file": "hooks.json",
+      "format": "hooks-json",
+      "scope": "user",
+      "scope_reason": "Claude Code loads the plugin's hooks.json from the plugin installation itself; per-project hooks live in settings, which projectstore does not write.",
+      "registered_by": "plugin"
+    },
+    "agents_block": {
+      "supported": true,
+      "kind": "shared",
+      "format": "markdown-block",
+      "scope": "project",
+      "scope_reason": "Claude Code reads CLAUDE.md from the project root; AGENTS.md is the cross-tool convention, bridged by an @AGENTS.md import (ADR-002 decision 3).",
+      "files": [
+        "AGENTS.md",
+        "CLAUDE.md"
+      ],
+      "reads_natively": "CLAUDE.md",
+      "reads_natively_reason": "The file this harness reads BY ITSELF. `files` is the block's placement preference and conflates two things: AGENTS.md is first because it is the cross-tool convention, but Claude Code reaches it only through the @AGENTS.md import WE install — remove the bridge and the block is invisible. So installing for this harness must leave CLAUDE.md present: holding the block when it lands here, holding the import when it lands in AGENTS.md. Measured 2026-09-09: a project with an AGENTS.md and no CLAUDE.md took the block into AGENTS.md and created no bridge, so the harness that ran the install could not see it.",
+      "source": "templates/claude-md-block.md.tmpl",
+      "marker": {
+        "open": "<!-- projectstore:agents v",
+        "close": "<!-- /projectstore:agents -->"
+      }
+    },
+    "statusline": {
+      "supported": true,
+      "kind": "shared",
+      "format": "json-entry",
+      "scope": "project",
+      "scope_reason": "The statusLine slot is per project and not plugin-declarable (ADR-006); our entry lives in settings.local.json, which is machine-specific.",
+      "file": ".claude/settings.local.json",
+      "marker": {
+        "pointer": "statusLine.command",
+        "predicate": "statusLineIsOurWiring"
+      }
+    },
+    "statusline_launcher": {
+      "supported": true,
+      "kind": "exclusive",
+      "format": "mjs",
+      "scope": "project",
+      "scope_reason": "The launcher resolves the currently installed plugin on every render, so the wired command carries no version; it is written only when the plugin runs from the marketplace cache — a dev checkout is wired directly.",
+      "file": ".projectstore/state/claude-code/statusline.mjs",
+      "source": "scripts/statusline-launcher.mjs",
+      "condition": "plugin_cache_install",
+      "file_reason": "the harness's generated runtime files live under .projectstore/state/<harness id>/ (layout ADR decision 4); the 0.27.x path .claude/.projectstore/statusline.mjs is read as ours through 0.29",
+      "legacy_file": ".claude/.projectstore/statusline.mjs"
+    },
+    "mcp": {
+      "supported": true,
+      "kind": "host",
+      "dir": ".",
+      "file": ".mcp.json",
+      "scope": "plugin",
+      "scope_reason": "Claude Code loads a plugin's .mcp.json from the plugin installation itself and expands ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PROJECT_DIR} in it per session, so the one shipped file binds each server to one project (MCP ADR decision 6, amended 2026-09-05); nothing is installed and nothing is derived — the host kind install-harness skips, which the install spec's contract 0 does not yet name.",
+      "launch": {
+        "cwd": "project",
+        "project_dir_in_env": true,
+        "expands_measured": [
+          "args",
+          "env"
+        ],
+        "expands_inferred": [
+          "command"
+        ],
+        "default_syntax": "${VAR:-default}",
+        "unset_placeholder_in_env": "literal",
+        "unset_placeholder_in_args": "inferred literal — the server refuses a --project still carrying a dollar-brace placeholder",
+        "entrypoint": "sdk-cli (headless -p), plugin loaded with --plugin-dir; the marketplace install and an interactive session are A9's",
+        "protocol_era": "initialize",
+        "protocol_version_seen": "2025-11-25",
+        "shutdown_signal": "SIGINT",
+        "evidence": "measured",
+        "client": "claude 2.1.261",
+        "date": "2026-09-05"
+      },
+      "registered_by": "plugin"
+    },
+    "mcp_project_entry": {
+      "supported": false,
+      "kind": "shared",
+      "format": "json-entry",
+      "scope": "project",
+      "scope_reason": "A project-root .mcp.json registers the server with an absolute --project for a host that does not expand placeholders (MCP ADR, decision 6); per project because the server binds to one.",
+      "file": ".mcp.json",
+      "marker": {
+        "pointer": "mcpServers.projectstore"
+      },
+      "why_unsupported": "the plugin-bundled registration already binds per project in Claude Code; this row is for hosts without plugin MCP and lands with their adapters (roadmap B3/C3)"
+    },
+    "plugin": {
+      "supported": true,
+      "kind": "registration",
+      "format": "host-plugin-registration",
+      "scope": "local",
+      "scope_reason": "Claude Code registers a plugin per scope (user, project, local, managed). The registration carries a machine-absolute path and an enablement, so it lands in the checkout's settings.local.json — the same machine-specific file the status line uses — never in the committed settings.json and never in the user's own settings (install spec contract 4′, 2026-09-05). Local scope is per checkout: a worktree registers again.",
+      "condition": "npm_package_root",
+      "marketplace_name": "projectstore-npm",
+      "plugin_name": "projectstore",
+      "dir": [
+        "projectstore",
+        "marketplace"
+      ],
+      "plugin_subdir": "projectstore",
+      "manifest": ".claude-plugin/marketplace.json",
+      "provenance_key": "projectstore",
+      "registry": {
+        "installed": [
+          "plugins",
+          "installed_plugins.json"
+        ],
+        "marketplaces": [
+          "plugins",
+          "known_marketplaces.json"
+        ],
+        "user_settings": [
+          "settings.json"
+        ],
+        "project_settings": [
+          "settings.local.json"
+        ],
+        "cache_dir": [
+          "plugins",
+          "cache"
+        ],
+        "enabled_pointer": "enabledPlugins",
+        "known_pointer": "extraKnownMarketplaces",
+        "install_path_layout": "<cache_dir>/<marketplace>/<plugin>/<version>"
+      },
+      "cli": {
+        "bin": "claude",
+        "verified": {
+          "version": "2.1.261",
+          "date": "2026-09-05",
+          "evidence": "measured in a sandboxed CLAUDE_CONFIG_DIR with two projects",
+          "notes": [
+            "plugin.json wins over the marketplace entry's version",
+            "--scope local writes only <project>/.claude/settings.local.json (extraKnownMarketplaces, enabledPlugins) and one registry row per project carrying projectPath",
+            "`plugin update <id> --scope local -y` swaps that project's row in place after the directory is rewritten; without --scope it looks at user scope and fails",
+            "`plugin uninstall --scope local -y` removes only the calling project's row and enablement",
+            "`marketplace remove` (any scope) empties known_marketplaces.json AND every project's rows for that marketplace — run only when no other project uses it; the project's own extraKnownMarketplaces entry is removed by install itself",
+            "`plugin validate` warns about the unknown `projectstore` field and exits 0",
+            "-y accepts a marketplace-declared command; this marketplace declares none",
+            "the project of a --scope local command is the process cwd; there is no --project flag",
+            "a live session marks its Bash environment with CLAUDECODE=1 (not the plugin-root or project-dir variables, which reach hooks only); the registration defers on that marker",
+            "`plugin update` at an unchanged version answers \"already at the latest version\" and copies nothing, even after `marketplace update`: a same-version content refresh is uninstall + install"
+          ]
+        },
+        "commands": {
+          "validate": [
+            "plugin",
+            "validate",
+            "{dir}"
+          ],
+          "marketplace_add": [
+            "plugin",
+            "marketplace",
+            "add",
+            "{dir}",
+            "--scope",
+            "local"
+          ],
+          "marketplace_update": [
+            "plugin",
+            "marketplace",
+            "update",
+            "{marketplace}"
+          ],
+          "marketplace_remove": [
+            "plugin",
+            "marketplace",
+            "remove",
+            "{marketplace}",
+            "--scope",
+            "local"
+          ],
+          "install": [
+            "plugin",
+            "install",
+            "{id}",
+            "--scope",
+            "local",
+            "-y"
+          ],
+          "update": [
+            "plugin",
+            "update",
+            "{id}",
+            "--scope",
+            "local",
+            "-y"
+          ],
+          "uninstall": [
+            "plugin",
+            "uninstall",
+            "{id}",
+            "--scope",
+            "local",
+            "-y"
+          ],
+          "disable": [
+            "plugin",
+            "disable",
+            "{other}",
+            "--scope",
+            "local"
+          ],
+          "enable": [
+            "plugin",
+            "enable",
+            "{other}",
+            "--scope",
+            "local"
+          ]
+        }
+      },
+      "condition_reason": "any root that is not the host's own plugin cache — the npm package under npx, a global install, a dev checkout — registers; a session running from the cache never registers a second copy of itself."
+    }
+  },
+  "capabilities": {
+    "statusline": true,
+    "interactive_approval_tool": true,
+    "permission_decision_hook": "PreToolUse",
+    "subagent_tool_allowlist": true,
+    "subagent_model_per_invocation": true
+  },
+  "rewrites": [],
+  "update_instructions": [
+    "**About future updates**: installed from the git marketplace, Claude Code does NOT auto-update third-party marketplaces by default (an npm registration updates with `npx projectstore-claude upgrade --project <dir>`). To get notified of new releases (v0.7+):",
+    "1. Open `/plugin` → **Marketplaces** tab.",
+    "2. Find **SmartAndPoint**.",
+    "3. Toggle **auto-update** on.",
+    "",
+    "Without it, you would run `/plugin marketplace update SmartAndPoint` manually. See https://github.com/SmartAndPoint/ProjectStore#upgrading for details.",
+    "",
+    "**Upgrading from 0.27.x to 0.28**: restart after the update, then move the project's files to `.projectstore/` with the one command the first session names, run from a terminal outside the session: for a git-marketplace install, the installed copy's own `bin/projectstore.mjs upgrade --harness claude-code --no-register --project <dir>`, which leaves the registration as it is; for the npm registration, `npx projectstore-claude@<version> upgrade --no-register --project <dir>`. The same run re-stamps the status-line launcher, and until then every reader falls back to the old paths. `status` and `search` answer from artifact facts; `doctor` gains surface, version-drift and mcp lines and exits 1 on findings; the plugin registers an MCP server the host may ask you to approve once. On 0.28.0-rc.1 or rc.2, update first: their startup line named the shell form without `--no-register` (`npx projectstore-claude@<version> upgrade`), which also switches a git-marketplace install to npm for the checkout (the README's Upgrading section has the way back). Before the move, a rollback to 0.27.x keeps working and the move is the way forward again; after the move, 0.27.x reads the project as unbound."
+  ],
+  "agent_translation": {
+    "carries_model": true,
+    "cheap_model": "sonnet",
+    "cheap_model_evidence": "measured",
+    "cheap_model_reason": "The model the clerk is pinned to when a strong default would otherwise lift it (ADR-008). A literal here, in the one file allowed to name a harness's vocabulary; it used to be a literal in scripts/cli.mjs, which made `agents configure --harness codex` write an Anthropic model name into a Codex overlay. MEASURED in the sense that matters: this is the model the clerk has been running on since ADR-008, in this repository, and tests/overlay.test.mjs asserts the pin end to end."
+  }
+}