projectstore-codex 0.0.1 → 0.28.2

package/node_modules/projectstore/harnesses/codex.json

@@ -0,0 +1,332 @@
+{
+  "_comment": "Harness capability manifest — Codex. The committed adapters/codex tree renders the source commands, roles, passive skills and hooks into Codex vocabulary. Measurements began with 759 captured hook firings on 2026-09-07/08; the complete built shell, isolated marketplace install, upgrade, validator and fresh-session skill load passed on codex-cli 0.153.4 on 2026-09-30. The validator reads only .codex-plugin/plugin.json, which from 0.28.2 is the shell's one manifest: Codex picks a root Agent Plugins plugin.json first and has loaded no hooks from that format since openai/codex#37027 (merged 2026-08-05).",
+  "id": "codex",
+  "display_name": "Codex",
+  "emit": true,
+  "source_layout": false,
+  "output_dir": "adapters/codex",
+  "docs": "https://developers.openai.com/codex/",
+  "verified": null,
+  "verified_reason": "Null, restored 2026-10-03. docs/harnesses.md calls a harness supported only when every installed surface has been exercised end to end, and contract 16 of the generation spec (Generated harness surfaces: manifests, the generator and the three invariants) derives that label from this field. The 2026-09-30 run (session 01a0f079-7ecd-7331-95a9-2471def3cb22) exercised one surface: a fresh `codex exec` session loaded projectstore-status from the materialised cache. The hooks were not exercised, and the first real install showed why that matters. Its cached hooks, run by hand through `zsh -lc` (a form the failure did not depend on: read from source, 0.153.4 runs a hook as `<session shell> -c` with the Codex process's environment, and `$SHELL -lc` only as a fallback), could not load the vault in any session; in the first, the failure sat beneath the welcome. The core had taken the shell's root for its own. That is fixed and pinned by a test that runs every rendered hook from the built shell. This block is set by a live run that exercises every installed surface: the hooks once registration has settled, including PreCompact, and the skill flows. The shell is published from 0.28.1, ahead of that run, by the maintainer's decision of 2026-10-04; publication does not set this block.",
+  "runtime": {
+    "detect_env": [
+      "PLUGIN_ROOT",
+      "PLUGIN_DATA",
+      "CODEX_HOME"
+    ],
+    "project_dir_env": null,
+    "project_dir_env_reason": "Codex exports no project-directory variable. Measured: a plugin hook process receives PLUGIN_ROOT, PLUGIN_DATA, CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA and nothing else of ours. The project comes from the hook payload's `cwd`, which the hooks adopt before they resolve anything (story: Every hook resolves the project before reading the payload that names it). Null, not absent: the key states the decision.",
+    "plugin_root_env": "PLUGIN_ROOT",
+    "home_env": "CODEX_HOME",
+    "home_default": ".codex",
+    "harness_dir": ".codex",
+    "harness_dir_reason": "Codex's own directory in a project. Never where projectstore's config lives — that is <project>/.projectstore/, one for every harness (the layout ADR).",
+    "overlay": "codex",
+    "overlay_reason": "The file under <project>/.projectstore/harness/ carrying this harness's agents block. Separate from claude-code's because a model name is harness-specific (ADR-008).",
+    "shared_env": [
+      "CLAUDE_PLUGIN_ROOT",
+      "CLAUDE_PLUGIN_DATA"
+    ],
+    "shared_env_reason": "Codex sets Claude Code's plugin-root names too, for compatibility — measured in every one of the 759 captured hook payloads. Without declaring them, a Codex session scores a strong detection hit for claude-code, ties with codex, and loses the tie to manifest filename order. A variable two harnesses both set identifies neither, so these are demoted to weak for every manifest (generation spec, contract 1, amended 2026-09-08).",
+    "session_env": [],
+    "session_env_reason": "Unmeasured. CODEX_HOME never appeared in a hook environment — it is a shell-profile signal, not a session marker — and no equivalent of CLAUDECODE was observed."
+  },
+  "tools": {
+    "write_tools": [
+      "apply_patch"
+    ],
+    "write_tools_reason": "The only file-writing tool observed: 26 apply_patch firings against 571 Bash. Bash writes too, and is excluded here for the same reason claude-code excludes it — a shell call is not a declared write and counting it would make every command an edit.",
+    "path_fields": [],
+    "path_fields_reason": "MEASURED EMPTY. apply_patch carries paths inside tool_input.command (26 of 26 firings), not in file_path/notebook_path/path. The shared manifest-driven extractor parses every `*** Add/Update/Delete File:` line (and `*** Move to:`) from patch_envelope_field, so multi-file patches feed the activity log and entry rule without a Codex branch.",
+    "patch_envelope_field": "command",
+    "approval_tool": null,
+    "approval_tool_reason": "UNMEASURED, and null rather than absent. Claude Code has AskUserQuestion; no equivalent structured-choice tool appeared in the 759 captured firings, and Codex's own tool list has not been read for one. Null means contract 10's approval-gate lint treats this harness as having no such tool — the safe reading — instead of inheriting the source harness's.",
+    "known_non_write_tools": [
+      "Bash",
+      "webrun",
+      "collaborationspawn_agent",
+      "collaborationlist_agents",
+      "collaborationwait_agent",
+      "collaborationsend_message",
+      "collaborationfollowup_task"
+    ],
+    "known_non_write_tools_reason": "Every other tool name observed. The collaboration* family is Codex's subagent mechanism — spawn_agent takes task_name, fork_turns and message — which is how it ran our roster's roles without loading agents/*.md (story: Subagent registration per host)."
+  },
+  "hooks": {
+    "config_file": "hooks/hooks.json",
+    "config_file_reason": "Codex's default hooks file. A legacy .codex-plugin/plugin.json with no `hooks` key falls back to hooks/hooks.json (DEFAULT_HOOKS_CONFIG_FILE in codex-rs/core-plugins/src/loader.rs at rust-v0.160.0), so the manifest names no hooks at all. The shell ships no root Agent Plugins plugin.json. Codex picks that manifest first and then loads no hooks from it, a runtime boundary since openai/codex#37027 (loader.rs:955 at rust-v0.153.4, 952-962 at rust-v0.160.0). With one, the maintainer's codex-cli 0.160.0 listed none of ours in /hooks on 2026-10-04; with the file renamed away in the installed cache, it listed all six. The app-server's hooks/list agrees: 0 for 0.28.1's root, 6 for 0.28.2's. The spike's inline form fired 757 events across five event types.",
+    "events": {
+      "SessionStart": "SessionStart",
+      "PreToolUse": "PreToolUse",
+      "PostToolUse": "PostToolUse",
+      "Stop": "Stop",
+      "PreCompact": "PreCompact"
+    },
+    "events_reason": "The five projectstore registers, and the list is checked against hooks/hooks.json rather than remembered: the map is what a generator would register, so an event here with no handler would render a hook that does nothing. Codex's full vocabulary, read from the binary, also has UserPromptSubmit (measured firing, and its payload is recorded under output_channels), PermissionRequest, PostCompact, SessionEnd, SubagentStart, SubagentStop and Interrupt, and no Notification. Handler kinds are Command, Async and MCP Server.",
+    "root_placeholder": "${PLUGIN_ROOT}",
+    "root_placeholder_literal": true,
+    "_root_placeholder_literal_comment": "true: Codex substitutes nothing in a hook command string. It does not need to — the hook process receives PLUGIN_ROOT in its environment (measured). The generator therefore renders an absolute interpreter and an absolute script path; a bare `node` is a PATH gamble."
+  },
+  "output_channels": {
+    "_comment": "Per-event payload fields, captured from live firings. `fields` here are the STDIN keys the event delivers — Codex's documented output channels (additionalContext and a decision object) are not yet measured, so `decision` stays null and `system_message` null rather than false.",
+    "SessionStart": {
+      "fields": [
+        "session_id",
+        "transcript_path",
+        "cwd",
+        "hook_event_name",
+        "model",
+        "permission_mode",
+        "source"
+      ],
+      "system_message": null,
+      "decision": null,
+      "evidence": "measured",
+      "note": "additionalContext reaches the model: asked to name the vault and count its ADRs without reading files, the model answered from the skeleton and was right."
+    },
+    "UserPromptSubmit": {
+      "fields": [
+        "session_id",
+        "turn_id",
+        "transcript_path",
+        "cwd",
+        "hook_event_name",
+        "model",
+        "permission_mode",
+        "prompt"
+      ],
+      "system_message": null,
+      "decision": null,
+      "evidence": "measured"
+    },
+    "PreToolUse": {
+      "fields": [
+        "session_id",
+        "turn_id",
+        "transcript_path",
+        "cwd",
+        "hook_event_name",
+        "model",
+        "permission_mode",
+        "tool_name",
+        "tool_input",
+        "tool_use_id"
+      ],
+      "system_message": null,
+      "decision": null,
+      "evidence": "measured",
+      "note": "372 firings. Codex has a dedicated PermissionRequest event, so whether a decision returned from PreToolUse is honoured is unmeasured and must not be assumed."
+    },
+    "PostToolUse": {
+      "fields": [
+        "session_id",
+        "turn_id",
+        "transcript_path",
+        "cwd",
+        "hook_event_name",
+        "model",
+        "permission_mode",
+        "tool_name",
+        "tool_input",
+        "tool_response",
+        "tool_use_id"
+      ],
+      "system_message": null,
+      "decision": null,
+      "evidence": "measured",
+      "note": "371 firings. tool_response is NOT one shape: 368 strings and 3 content-block arrays (all webrun). Claude Code sends an object. Nothing may depend on it."
+    },
+    "Stop": {
+      "fields": [
+        "session_id",
+        "turn_id",
+        "transcript_path",
+        "cwd",
+        "hook_event_name",
+        "model",
+        "permission_mode",
+        "stop_hook_active",
+        "last_assistant_message"
+      ],
+      "system_message": null,
+      "decision": null,
+      "evidence": "measured",
+      "note": "stop_hook_active is present, so hooks/session-stop.mjs's loop guard ports unchanged. last_assistant_message has no Claude Code counterpart."
+    },
+    "PreCompact": null
+  },
+  "surfaces": {
+    "agents": {
+      "supported": false,
+      "kind": "host",
+      "scope": "user",
+      "scope_reason": "Codex spawns subagents through a tool (collaborationspawn_agent), not by loading a plugin's agents/ directory.",
+      "why_unsupported": "Measured: told to run projectstore:critic, Codex spawned six of its own generic subagents named after our roster and briefed them itself; none of our agents/*.md prose reached them. No route from a plugin's agents/ entry to that mechanism has been found (roadmap B4)."
+    },
+    "agents_block": {
+      "supported": true,
+      "kind": "shared",
+      "format": "markdown-block",
+      "scope": "project",
+      "scope_reason": "Codex reads AGENTS.md from the project root; it does not read CLAUDE.md.",
+      "files": [
+        "AGENTS.md"
+      ],
+      "reads_natively": "AGENTS.md",
+      "reads_natively_reason": "Codex reads AGENTS.md from the project root by itself, and reads no other file of this kind — its `files` list is the same single entry, so placement and native reading coincide here and the distinction costs nothing.",
+      "files_reason": "One entry, deliberately. analyseBlock takes files[0] when it exists and the last entry otherwise; with claude-code's two-entry list and neither file present, a fresh install wrote CLAUDE.md — which Codex never reads. Measured on the smoke stand, where AGENTS.md had to be written by hand before Codex saw the rules at all.",
+      "source": "templates/claude-md-block.md.tmpl",
+      "marker": {
+        "open": "<!-- projectstore:agents v",
+        "close": "<!-- /projectstore:agents -->"
+      }
+    },
+    "commands": {
+      "supported": false,
+      "kind": "host",
+      "scope": "user",
+      "scope_reason": "Codex has no registrable root slash command; the /prompts: mechanism is deprecated.",
+      "why_unsupported": "Shipping commands/ is actively harmful here: Codex rewrites them into skills itself and keeps ${CLAUDE_PLUGIN_ROOT} in the body, producing entry points that exit 1 with Cannot find module '/bin/projectstore.mjs' (reproduced). The generator renders them as skills instead (roadmap B5)."
+    },
+    "hooks": {
+      "supported": true,
+      "kind": "host",
+      "scope": "user",
+      "scope_reason": "Loaded with the plugin from its default hooks/hooks.json, which .codex-plugin/plugin.json leaves to Codex by naming no hooks; trust is granted per hook, machine-wide, and cannot be silenced per checkout."
+    },
+    "mcp": {
+      "supported": false,
+      "kind": "host",
+      "scope": "project",
+      "scope_reason": "Codex auto-discovers a plugin-root .mcp.json even when the manifest does not declare mcpServers — measured.",
+      "why_unsupported": "Our .mcp.json is in Claude Code's dialect: its argv carries ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PROJECT_DIR}, which nothing substitutes there, so the server failed its handshake and printed a red error in every session. Ships only once the Codex dialect is rendered and the spike's criterion (h) says what cwd and environment the server receives."
+    },
+    "skills": {
+      "supported": true,
+      "kind": "host",
+      "scope": "user",
+      "scope_reason": "Codex loads skills from the plugin root's skills/ directory, declared in the manifest as skills: \"./skills/\" — 47 of the 64 curated plugin manifests on the measuring machine declare theirs that way, and ours loaded.",
+      "dir": "skills",
+      "file": "<name>/SKILL.md",
+      "registered_by": "plugin",
+      "frontmatter_required": [
+        "name",
+        "description"
+      ],
+      "frontmatter_reason": "\"The SKILL.md file must include name and description\" — learn.chatgpt.com/docs/build-skills, read 2026-09-08. DOCUMENTED, and it disagrees with what we measured: our four skills carried only `description` and loaded anyway, and the model listed them. Either the name falls back to the directory or the loader is laxer than the page. We now ship both fields, so the discrepancy stops mattering for us and stays recorded for whoever meets it.",
+      "invocation": "$<name>",
+      "invocation_evidence": "documented",
+      "invocation_reason": "Explicitly: type `$<skill-name>`, or `/skills` to list what is loaded (examples given: `$skill-installer linear`). Implicitly: the model chooses a skill when the task matches its `description` — `allow_implicit_invocation` defaults true and is disabled per skill in agents/openai.yaml. So `description` is the TRIGGER here, not a hint for a human picking from a menu, which is what it is on the source harness. learn.chatgpt.com/docs/build-skills, read 2026-09-08. NOT measured: nobody has typed a $ at this stand's prompt.",
+      "discovery": [
+        "$CWD/.agents/skills",
+        "$REPO_ROOT/.agents/skills",
+        "$HOME/.agents/skills",
+        "/etc/codex/skills",
+        "bundled with Codex"
+      ],
+      "discovery_reason": "The four scopes the documentation lists, in its order. Note what is ABSENT from that list: a plugin's own skills/ directory. Ours loads all the same, declared as skills: \"./skills/\" in the plugin manifest and measured on the spike — 47 of 64 curated plugin manifests on the measuring machine declare theirs the same way. The plugin route is real and undocumented on this page; do not conclude from the page that it does not exist.",
+      "description_limit": "shortened above 2% of the context window, or 8000 characters",
+      "unrendered_source": false,
+      "unrendered_source_reason": "Codex loads the committed adapters/codex/skills tree rendered from commands, roles and passive source skills. Generation fails if a Claude command namespace or root variable survives."
+    },
+    "statusline": {
+      "supported": false,
+      "kind": "host",
+      "scope": "user",
+      "scope_reason": "There is no per-project status-line slot to occupy: Codex has no status-line surface at all, so nothing of ours is written anywhere and the scope is the host's, not a file's.",
+      "why_unsupported": "No status-line mechanism was found in the harness — no settings slot, no plugin field, no handler contract. Recorded as a row rather than an absence so the generator's coverage invariant sees a stated omission (contract 9) instead of a surface that quietly does not exist here."
+    },
+    "plugin": {
+      "supported": true,
+      "kind": "registration",
+      "format": "portable-plugin-registration",
+      "scope": "user",
+      "scope_reason": "Measured on codex-cli 0.153.4: marketplace registration, plugin installation and the materialised cache live in CODEX_HOME. Trusted project config can override enablement but cannot create an installation, so ordinary project uninstall never removes this global surface.",
+      "ownership": "global",
+      "condition": "distribution_root",
+      "marketplace_name": "projectstore-npx",
+      "plugin_name": "projectstore",
+      "dir": [
+        "projectstore",
+        "marketplace"
+      ],
+      "plugin_subdir": "plugins/projectstore",
+      "manifest": ".agents/plugins/marketplace.json",
+      "ownership_manifest": ".projectstore-registration.json",
+      "provenance_key": "projectstore",
+      "registry": {
+        "format": "toml",
+        "global_config": ["config.toml"],
+        "project_config": ["config.toml"],
+        "cache_dir": ["plugins", "cache"]
+      },
+      "cli": {
+        "bin": "codex",
+        "verified": {
+          "version": "0.153.4",
+          "date": "2026-09-29",
+          "evidence": "measured with an isolated CODEX_HOME and a trusted project override"
+        },
+        "required": ["marketplace_add", "install", "uninstall", "list"],
+        "optional": ["validate", "update", "marketplace_remove", "enable", "disable"],
+        "fallbacks": {
+          "validate": "unsupported",
+          "update": "install",
+          "marketplace_remove": "explicit-global-only",
+          "enable": "project-config-only",
+          "disable": "project-config-only"
+        },
+        "commands": {
+          "marketplace_add": ["plugin", "marketplace", "add", "{dir}"],
+          "install": ["plugin", "add", "{id}"],
+          "uninstall": ["plugin", "remove", "{id}"],
+          "list": ["plugin", "list", "--json"],
+          "marketplace_remove": ["plugin", "marketplace", "remove", "{marketplace}"]
+        }
+      }
+    }
+  },
+  "capabilities": {},
+  "rewrites": [],
+  "install": {
+    "mechanism": "the package's portable plugin root, registered through its distribution shell and Codex's own marketplace CLI",
+    "shell": "projectstore-codex",
+    "shell_reason": "The built `projectstore-codex` shell carries the rendered Codex skills and hooks plus an exact bundled core, fixes --harness codex, stages a stable marketplace under CODEX_HOME, and asks Codex itself to install it. It is published from 0.28.1, by the maintainer's decision of 2026-10-04. Until then this key was absent, so generated guidance could not send users to the reserved 0.0.1 placeholder; the core alone is not Codex's plugin root and cannot register it.",
+    "why_not_scripted": "The shell does not edit Codex's registry or cache. It atomically stages the plugin source, previews the host commands, then runs `codex plugin marketplace add` and `codex plugin add`; a read-back verifies the installed version and payload digest. The global plugin survives ordinary project uninstall; `uninstall --global` is the explicit destructive form.",
+    "steps": [
+      "npx projectstore-codex install --project \"$PWD\"",
+      "restart Codex and approve the ProjectStore hooks when prompted",
+      "run `$projectstore-bind <vault-path>` in Codex"
+    ],
+    "notes": [
+      "The installation is user-global because Codex's marketplace, plugin row and cache live in CODEX_HOME; the AGENTS.md block is project-local.",
+      "Upgrade with `npx projectstore-codex@<version> upgrade --project \"$PWD\"`; the named package version is also the plugin version.",
+      "A second enabled ProjectStore plugin from another marketplace is a refusal, not silently disabled globally. Remove or disable that older registration explicitly, then retry.",
+      "Ordinary uninstall removes only project-owned surfaces. `npx projectstore-codex uninstall --global --project \"$PWD\"` also removes the user-global plugin registration after a preview."
+    ],
+    "docs": "https://github.com/SmartAndPoint/ProjectStore#install--one-message"
+  },
+  "update_instructions": "Run `npx projectstore-codex@<version> upgrade --project <dir>`. The installer atomically replaces its stable source and `codex plugin add projectstore@projectstore-npx` materialises the new version; this was measured across two dev builds on codex-cli 0.153.4. Restart Codex afterwards so the new skills and hooks are loaded.",
+  "agent_translation": {
+    "carries_model": false,
+    "carries_model_reason": "The surface projectstore ships — a plugin's agents/ entry — carries no model on Codex: surfaces.agents is supported:false because no route from a plugin's agents/ directory to collaborationspawn_agent has been found (measured). Codex DOES have a definition file that carries model and effort, recorded below, but it is project- or user-scoped and not plugin-shippable, so contract 12 holds as written: what we ship cannot carry a model. Was true here until 2026-09-08, which contradicted both contract 12 and this file's own agents row.",
+    "definition_file": ".codex/agents/<name>.toml",
+    "definition_file_evidence": "documented",
+    "definition_file_reason": "Codex agent definitions are TOML under .codex/agents/ (project) or ~/.codex/agents/ (personal) and accept `model`, `model_reasoning_effort`, `sandbox_mode` and `mcp_servers`. Documented at learn.chatgpt.com/docs/agent-configuration/subagents, read 2026-09-08; NOT measured, and not reachable from a plugin today. This is the route the rendering story (Per-agent effort returns, PS-AGENTS) has to decide on, and B4 has to measure.",
+    "cheap_model": "gpt-5.6-luna",
+    "cheap_model_evidence": "chosen",
+    "cheap_model_reason": "CHOSEN, not measured: the verified plugin session exercised the rendered skill surface, not this optional model pin. It reaches a user's overlay — `agents configure --harness codex` writes it as the clerk's pin — so if the id is wrong the failure is at spawn time, on the harness, not here. The transcriber's model. gpt-5.6-luna at $0.20/$1.20 per Mtok is the cost tier gpt-5.6-sol ($4/$20) is twenty times above, and the clerk composes nothing: it copies an approved file and runs a pinned ceremony (ADR-008). Chosen 2026-09-08 from the published model list, by the same reasoning that pins the clerk to the cheap tier on Claude Code.",
+    "effort_levels": [
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max",
+      "ultra"
+    ],
+    "effort_key": "model_reasoning_effort",
+    "effort_evidence": "documented",
+    "effort_precedence": "explicit spawn value, then the [agents] default from config, then the parent agent's value. A model chosen without an effort uses that model's default effort.",
+    "effort_reason": "Recorded, not yet consumed: the overlay's allowlist rejects an effort key and rewrites it out, deliberately, until the story Per-agent effort returns decides whether a role's effort travels in a rendered definition or at spawn. Documented 2026-09-08; the `ultra` level is Codex's and is not a level Claude Code accepts."
+  }
+}

package/node_modules/projectstore/hooks/hooks.json

@@ -0,0 +1,59 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs"
+          },
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-rules.mjs"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/touch-session.mjs"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/touch-session.mjs"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-stop.mjs"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pre-compact.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}

package/node_modules/projectstore/hooks/pre-compact.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+// projectstore — PreCompact hook.
+//
+// Fires before context compaction (both manual /compact and automatic).
+//
+// ONE channel: `systemMessage`, the line the user sees in their /compact
+// output. PreCompact has no `additionalContext` — the runtime rejects the whole
+// object when one is present, taking `systemMessage` down with it, so for its
+// entire history this hook assembled a packet, printed a red validation error,
+// and reached nobody. Agent-facing continuity after a compaction is
+// SessionStart's job, on `source: "compact"` (spec contract 19).
+//
+// What this hook may CLAIM is narrower than what it knows, and deliberately so:
+//   - naming the in-flight artifact is always safe — it is a fact about the log
+//     it just read, not a promise about the future;
+//   - promising that context comes back requires `trigger === "manual"` AND
+//     `auto_inject !== false`, the two falsifiers knowable at claim time;
+//   - promising that RECENT FILES come back additionally requires the log to
+//     have resolved nonempty, because an empty log renders nothing there.
+//
+// Session identity comes from Claude's own session_id in stdin input (so two
+// Claude instances on the same project don't share activity).
+// Silent no-op when no projectstore config is present.
+
+import { basename } from "node:path";
+import {
+  readConfig,
+  readStdinJson,
+  adoptHookInput,
+  loadLayout,
+  readActivityAsync,
+  resolveInFlightArtifact,
+  pathCell,
+} from "../scripts/lib.mjs";
+
+// Exits after the flush, never before: process.exit does not drain a pending
+// pipe write, and the budgeted read below can still be outstanding.
+function emit(systemMessage) {
+  process.stdout.write(JSON.stringify({ systemMessage }) + "\n", () => process.exit(0));
+}
+
+// Contract 13's budget applies here too. The session file lives inside the
+// vault, so an evicted copy blocks uninterruptibly — and hanging a compaction
+// is a worse outcome than a line with no artifact name. The READ itself comes
+// from lib.mjs: SessionStart reads the same file for the same reason, and
+// contract 24's argument against two implementations of one question does not
+// stop at the resolver.
+// No {readFile} seam here on purpose: this hook is only ever driven as a
+// process, so a seam nothing can reach would read as testability it does not
+// have. The race is unit-tested through the gather's copy of it.
+//   null → the read did not resolve in time
+//   []   → resolved: missing, unreadable and genuinely empty, indistinguishable
+async function readActivityBudgeted(vault, sid, budgetMs) {
+  if (!sid) return [];
+  let timer = null;
+  const deadline = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(null), budgetMs);
+  });
+  const out = await Promise.race([
+    readActivityAsync(vault, sid).catch(() => []),
+    deadline,
+  ]);
+  clearTimeout(timer);
+  return out;
+}
+
+async function main() {
+  // The payload before the project: readConfig() resolves through
+  // projectRoot(), and on a harness that exports no project-dir variable the
+  // payload's cwd is the only answer better than this process's cwd. Read once
+  // — fd 0 is empty on a second read.
+  const input = adoptHookInput(readStdinJson());
+
+  const cfg = readConfig();
+  if (!cfg) process.exit(0);
+
+  const sid = input?.session_id || null;
+  const activity = await readActivityBudgeted(cfg.vault_path, sid, 200);
+
+  // Defensive: loadLayout throws on an unknown layout name, and in this hook the
+  // outer catch produces a failure notice rather than a compaction line — so a
+  // layout throw would take the whole message down for the sake of one clause.
+  let layout = null;
+  try {
+    layout = loadLayout(cfg.layout);
+  } catch {}
+  const artifact = activity && layout
+    ? resolveInFlightArtifact(activity, layout, cfg.vault_path)
+    : null;
+
+  const parts = [`vault ${basename(cfg.vault_path)}`];
+  // Dropped rather than rendered empty when nothing resolves.
+  // Contract 19's "one path form, three renderings": the same 200-character
+  // front-truncated cell the skeleton uses, so a >200 path cannot render
+  // truncated in one place and whole one line away.
+  if (artifact) parts.push(`in flight: ${pathCell(artifact)}`);
+
+  // The delivery claim, and only where it is true. On `auto` this plugin makes
+  // no claim that SessionStart fires at all; under `auto_inject: false` the
+  // skeleton is deterministically not emitted, and gating on config presence
+  // alone would print the promise happily on exactly that configuration.
+  const mayPromise = input?.trigger === "manual" && cfg.auto_inject !== false;
+  if (mayPromise) {
+    // Recent files are a separate referent with a separate condition: an empty
+    // log renders no continuity section, so the stronger wording would be false
+    // on a path the activity log's last-tool-wins dedupe makes ordinary.
+    parts.push(activity && activity.length > 0
+      ? "orientation and this session's recent files return at session start"
+      : "orientation returns at session start");
+  } else {
+    // True on every path: plugin commands are installation-scoped and not
+    // gated by auto_inject.
+    parts.push("run /projectstore:status to reorient");
+  }
+
+  emit(`projectstore: compacting — ${parts.join(", ")}`);
+}
+
+main().catch((e) => {
+  emit(`projectstore: PreCompact hook failed — ${e.message}`);
+});

package/node_modules/projectstore/hooks/session-rules.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// projectstore — session-rules.mjs
+//
+// The SECOND SessionStart hook. It carries the standing rules an agent needs
+// before it starts working, and nothing else.
+//
+// Why a separate hook rather than more text in session-start.mjs: hook output
+// strings are capped at 10,000 characters PER VALUE, and over the cap the
+// harness replaces the text with a file path and a preview. session-start's
+// vault map is already over that line on a real vault (11,596 characters when
+// this was written), so anything appended to it would arrive as a reference
+// rather than as context. Several hooks returning additionalContext for one
+// event are all delivered, so a small second value is delivered inline no
+// matter how large the map grows. Keep this payload small — permanently.
+//
+// Spec: "Entry-rule detection: the score, the open-story predicate, and the
+// delivery seams", contract 17.
+
+import { readConfig, readStdinJson, adoptHookInput } from "../scripts/lib.mjs";
+
+// Kept well under the cap; asserted by a test rather than by intention.
+const RULES = `# projectstore — standing rules for this session
+
+**Artifact-first order.** A feature-sized request opens a vault artifact before
+it opens an editor: analysis → placement (which epic, which story) → an ADR
+and/or spec when the "how" is non-trivial → \`projectstore:critic\` → only then
+implementation → \`projectstore:reviewer\`. "Feature-sized" is not a judgement
+call about how the request was phrased — it is about what the work touches. If
+you are about to write across several source files, open the story first.
+
+**Report instruction conflicts; do not arbitrate them.** If a session-level or
+harness-level instruction contradicts these rules or the \`AGENTS.md\`
+registration block, say so and ask which wins. Resolving it silently is how the
+contradiction becomes invisible to the person who could have settled it.`;
+
+function emit(additionalContext) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: "SessionStart", additionalContext },
+  }) + "\n");
+}
+
+function main() {
+  // The RULES text below is the same for every project, so it is tempting to
+  // skip the payload here. The GATE is not: both `!cfg` and `auto_inject`
+  // are facts about one specific project, and this hook shares its event with
+  // session-start.mjs. If only one of the two adopted the payload, the pair
+  // could answer for two different projects in the same session start — one
+  // emitting a vault's skeleton while the other decided, from the process's
+  // cwd, whether to speak at all. One readFileSync(0) is the whole cost of
+  // keeping them symmetric.
+  adoptHookInput(readStdinJson());
+
+  const cfg = readConfig();
+  if (!cfg) return;
+  // Honour auto_inject: a session that opted out of context injection is
+  // exactly the case for which the AGENTS.md block remains the durable copy.
+  if (cfg.auto_inject === false) return;
+  emit(RULES);
+}
+
+try { main(); } catch {
+  // A hook must never break session startup.
+}