session-orchestrator 5.6.0 → 5.8.0

package/.agents/skills/architecture/SKILL.md

@@ -3,6 +3,7 @@ name: architecture
 description: Use when the user asks to improve architecture, find refactoring opportunities, surface deepening opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Surfaces shallow modules and hypothetical seams using a precise vocabulary (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality from LANGUAGE.md).
 license: MIT
 metadata:
+  user-invocable: "true"
   model: inherit
   derived-from: mattpocock/skills@90ea8ee
   upstream-url: https://github.com/mattpocock/skills/tree/main/improve-codebase-architecture
@@ -18,3 +19,5 @@ metadata:
 > Regenerate with `node scripts/generate-agents-skills.mjs`.
 
 Read the linked document in full and follow its complete workflow, including prechecks and stop conditions. Resolve its link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root and relative links in the canonical document from its own directory. Keep the user’s project as the target of project operations.
+
+`$ARGUMENTS` means the trailing user input after the selected command skill, or an empty string when absent. Preserve flags, quoted text, and Unicode as data. Do not perform global substitution in the command document, shell expansion on the argument string, or execution of that string as shell code. Pass command arguments through structured tool parameters or safely quoted individual arguments.

package/.agents/skills/architecture/agents/openai.yaml

@@ -0,0 +1,5 @@
+# Generated by scripts/generate-agents-skills.mjs; do not edit.
+interface:
+  display_name: architecture
+policy:
+  allow_implicit_invocation: true

package/.agents/skills/claude-md-drift-check/SKILL.md

@@ -2,6 +2,7 @@
 name: claude-md-drift-check
 description: "Use when detecting drift between CLAUDE.md (or AGENTS.md, the Codex CLI alias) / _meta narrative and live repository state. Ten checks: absolute-path resolution, 01-projects/ count claims, issue-reference freshness, session-file existence, command-count sync, session-config-parity (mandatory template keys = error, opt-in gaps = note, unknown local keys = warning), vault-dir-parity (CLAUDE.md vs AGENTS.md), generated-rule-staleness (WARN-only), rule-scoping (paths:/globs: frontmatter defects, dangling rule citations, zero-match globs), and docs-parity (docs/components.md count-claims vs on-disk counts, template-vs-reference config-key parity, stale .claude/metrics/ paths). Full per-check spec in the body table. Invoked as an opt-in session-end phase; mirrors vault-sync's lean JSON+exit-code contract."
 metadata:
+  user-invocable: "false"
   model: haiku
 ---
 

package/.agents/skills/eval/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: eval
-description: Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v2 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score.
+description: Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v3 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score.
 metadata:
   user-invocable: "true"
   argument-hint: "[--session <id>] [--no-write] [--verify <run-id>]"

package/.agents/skills/frontmatter-guard/SKILL.md

@@ -2,6 +2,7 @@
 name: frontmatter-guard
 description: "Injects the canonical vault frontmatter schema snippet into agent prompts before any vault-write task, preventing malformed YAML frontmatter in Obsidian notes. <example>Context: wave-executor is about to dispatch a vault-mirror agent that writes learning notes under ~/Projects/vault/40-learnings/. user: \"dispatch vault-write agent\" assistant: \"Injecting frontmatter-guard snippet into agent prompt (vault scope detected). Required fields: id, type, created, updated. Enum type: note|daily|project|person|reference|idea|learning|session.\" <commentary>The wave-executor pre-dispatch hook calls detectVaultTaskScope() — the fileScope contains /Projects/vault/40-learnings/ so the guard triggers and the snippet is prepended to the agent system prompt.</commentary></example>"
 metadata:
+  user-invocable: "false"
   model: inherit
 ---
 

package/.agents/skills/gitlab-portfolio/SKILL.md

@@ -2,6 +2,7 @@
 name: gitlab-portfolio
 description: "Use when you need a single-pane cross-repo health view across all vault-registered GitLab and GitHub projects. Discovers repos from `_overview.md` frontmatter in `<vault>/01-projects/*/`, aggregates open issues, MRs, critical labels, and stale signals via parallel `glab`/`gh` calls, then writes an idempotent `_PORTFOLIO.md` dashboard. Runs automatically at session-start Phase 2 when `gitlab-portfolio.enabled=true`. Triggers: \"show portfolio status\", \"refresh the portfolio dashboard\", \"which repos have critical issues\", \"run /portfolio\". <example>Context: session-start, gitlab-portfolio.enabled=true, vault has 5 registered repos. user: \"/session deep\" assistant: \"Portfolio: 3 critical issues across 2 repos — run /portfolio for details. Dashboard written to vault/01-projects/_PORTFOLIO.md.\"</example>"
 metadata:
+  user-invocable: "false"
   model: sonnet
 ---
 

package/.agents/skills/hook-development/SKILL.md

@@ -2,6 +2,7 @@
 name: hook-development
 description: Use when creating, modifying, or debugging Claude Code hooks — PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification. Covers the plugin `hooks/hooks.json` wrapper format vs. the user `settings.json` direct format, matchers, security patterns, `$CLAUDE_PLUGIN_ROOT` portability, lifecycle limitations, and debugging. Trigger on "add a hook", "validate tool use", "block dangerous commands", "enforce completion", "hook-based automation".
 metadata:
+  user-invocable: "false"
   model: sonnet
 ---
 

package/.agents/skills/mcp-builder/SKILL.md

@@ -2,6 +2,7 @@
 name: mcp-builder
 description: Use when creating a new MCP (Model Context Protocol) server, extending an existing one, or debugging tool discoverability/performance. Guides through research → implementation → test → eval phases with TypeScript-first guidance matching our stack. Trigger on phrases like "build an MCP server", "expose X as an MCP tool", "write MCP tools for Y", "integrate Z via MCP".
 metadata:
+  user-invocable: "false"
   model: sonnet
 ---
 

package/.agents/skills/tmux-layout/SKILL.md

@@ -2,6 +2,7 @@
 name: tmux-layout
 description: "Use this skill when the operator wants a prepared tmux visualization layout for the session's side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug layout. Read-only side-channel observability — the coordinator chat stays in the operator's original terminal. Trigger phrases: \"tmux layout\", \"split panes for ci watch\", \"visualize session side-channels\", \"show me state-md tail and ci\"."
 metadata:
+  user-invocable: "true"
   model: inherit
   color: cyan
 allowed-tools:
@@ -21,3 +22,5 @@ allowed-tools:
 > Regenerate with `node scripts/generate-agents-skills.mjs`.
 
 Read the linked document in full and follow its complete workflow, including prechecks and stop conditions. Resolve its link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root and relative links in the canonical document from its own directory. Keep the user’s project as the target of project operations.
+
+`$ARGUMENTS` means the trailing user input after the selected command skill, or an empty string when absent. Preserve flags, quoted text, and Unicode as data. Do not perform global substitution in the command document, shell expansion on the argument string, or execution of that string as shell code. Pass command arguments through structured tool parameters or safely quoted individual arguments.

package/.agents/skills/tmux-layout/agents/openai.yaml

@@ -0,0 +1,5 @@
+# Generated by scripts/generate-agents-skills.mjs; do not edit.
+interface:
+  display_name: tmux-layout
+policy:
+  allow_implicit_invocation: true

package/.agents/skills/vault-mirror/SKILL.md

@@ -2,6 +2,7 @@
 name: vault-mirror
 description: "Use when you need to populate the Meta-Vault with machine-generated notes derived from session-orchestrator JSONL records. Converts entries from `.orchestrator/metrics/sessions.jsonl` and `.orchestrator/metrics/learnings.jsonl` into vault-conformant Markdown under `50-sessions/` and `40-learnings/`. Called automatically at session-end Phase 3.7 and after evolve Phase 3.5 — only when `vault-integration.enabled=true` and `vault-integration.mode != \"off\"`. Idempotent: re-runs safely; skips hand-authored notes. Triggers: \"mirror to vault\", \"sync session notes to vault\", \"write learning notes to vault\", \"vault-mirror failed at session close\". <example>Context: session-end is finalizing, vault-integration.mode is \"warn\". user: \"/close\" assistant: \"Running vault-mirror to write 50-sessions/session-2026-05-17.md from the closing session record — 1 created, 0 skipped.\"</example>"
 metadata:
+  user-invocable: "false"
   model: haiku
 ---
 

package/.agents/skills/vault-sync/SKILL.md

@@ -2,6 +2,7 @@
 name: vault-sync
 description: "Use when you need to validate the Meta-Vault's Markdown frontmatter and wiki-link integrity before closing a session or after vault edits. Runs as a hard gate at session-end Phase 1 — blocks close if any `.md` file fails the Zod frontmatter schema or has dangling `[[wiki-links]]`. Supports three modes: `hard` (blocks on errors), `warn` (reports without blocking), `off` (skip). Reads `vault-sync.*` from Session Config; respects per-vault exclude globs from `CLAUDE.md`. Triggers: \"vault validation failed at session close\", \"fix vault frontmatter errors\", \"check vault wiki-links\", \"why is session-end blocked by vault-sync\". <example>Context: session-end Phase 1 quality gate, vault-sync.enabled=true, vault-sync.mode=\"hard\". user: \"/close\" assistant: \"vault-sync found 2 frontmatter errors in vault/40-learnings/ml-notes.md — missing required `id` field. Fixing before close.\"</example>"
 metadata:
+  user-invocable: "false"
   model: haiku
 ---
 

package/.agents/skills/write-executable-plan/SKILL.md

@@ -2,6 +2,7 @@
 name: write-executable-plan
 description: Use when you have a PRD or design spec and need a bite-sized, executable implementation plan that any agent can follow without re-deriving structure. Produces `docs/plans/YYYY-MM-DD-<feature>.md` with per-task Files block, complete code per step (no placeholders), and exact verification commands. Rejects "TBD", "TODO", "add error handling", "similar to Task N".
 metadata:
+  user-invocable: "true"
   model: inherit
   color: green
 allowed-tools:
@@ -22,3 +23,5 @@ allowed-tools:
 > Regenerate with `node scripts/generate-agents-skills.mjs`.
 
 Read the linked document in full and follow its complete workflow, including prechecks and stop conditions. Resolve its link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root and relative links in the canonical document from its own directory. Keep the user’s project as the target of project operations.
+
+`$ARGUMENTS` means the trailing user input after the selected command skill, or an empty string when absent. Preserve flags, quoted text, and Unicode as data. Do not perform global substitution in the command document, shell expansion on the argument string, or execution of that string as shell code. Pass command arguments through structured tool parameters or safely quoted individual arguments.

package/.agents/skills/write-executable-plan/agents/openai.yaml

@@ -0,0 +1,5 @@
+# Generated by scripts/generate-agents-skills.mjs; do not edit.
+interface:
+  display_name: write-executable-plan
+policy:
+  allow_implicit_invocation: true

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
-    "version": "5.6.0"
+    "version": "5.8.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "session-orchestrator",
-  "version": "5.6.0",
+  "version": "5.8.0",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.6.0+codex.20261003103620",
+  "version": "5.8.0+codex.20261005120103",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "keywords": [
     "session",

package/.codex-plugin/skills/architecture/SKILL.md

@@ -3,6 +3,7 @@ name: architecture
 description: Use when the user asks to improve architecture, find refactoring opportunities, surface deepening opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Surfaces shallow modules and hypothetical seams using a precise vocabulary (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality from LANGUAGE.md).
 license: MIT
 metadata:
+  user-invocable: 'true'
   model: inherit
   derived-from: mattpocock/skills@90ea8ee
   upstream-url: https://github.com/mattpocock/skills/tree/main/improve-codebase-architecture
@@ -17,4 +18,6 @@ The linked document is authoritative, including its prechecks, argument rules, a
 
 Resolve this link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root; resolve relative links inside the canonical document from its own directory. Keep the user’s project as the target of project operations.
 
+`$ARGUMENTS` means the trailing user input after the selected command skill, or an empty string when absent. Preserve flags, quoted text, and Unicode as data. Do not perform global substitution in the command document, shell expansion on the argument string, or execution of that string as shell code. When the workflow needs a command, pass its arguments through structured tool parameters or safely quoted individual arguments.
+
 Regenerate with `node scripts/generate-codex-skills.mjs`.

package/.codex-plugin/skills/architecture/agents/openai.yaml

@@ -0,0 +1,5 @@
+# Generated by scripts/generate-codex-skills.mjs; do not edit.
+interface:
+  display_name: architecture
+policy:
+  allow_implicit_invocation: true

package/.codex-plugin/skills/claude-md-drift-check/SKILL.md

@@ -2,6 +2,7 @@
 name: claude-md-drift-check
 description: 'Use when detecting drift between CLAUDE.md (or AGENTS.md, the Codex CLI alias) / _meta narrative and live repository state. Ten checks: absolute-path resolution, 01-projects/ count claims, issue-reference freshness, session-file existence, command-count sync, session-config-parity (mandatory template keys = error, opt-in gaps = note, unknown local keys = warning), vault-dir-parity (CLAUDE.md vs AGENTS.md), generated-rule-staleness (WARN-only), rule-scoping (paths:/globs: frontmatter defects, dangling rule citations, zero-match globs), and docs-parity (docs/components.md count-claims vs on-disk counts, template-vs-reference config-key parity, stale .claude/metrics/ paths). Full per-check spec in the body table. Invoked as an opt-in session-end phase; mirrors vault-sync''s lean JSON+exit-code contract.'
 metadata:
+  user-invocable: 'false'
   model: haiku
 ---
 

package/.codex-plugin/skills/eval/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: eval
-description: Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v2 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score.
+description: Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v3 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score.
 metadata:
   user-invocable: 'true'
   argument-hint: '[--session <id>] [--no-write] [--verify <run-id>]'

package/.codex-plugin/skills/frontmatter-guard/SKILL.md

@@ -2,6 +2,7 @@
 name: frontmatter-guard
 description: 'Injects the canonical vault frontmatter schema snippet into agent prompts before any vault-write task, preventing malformed YAML frontmatter in Obsidian notes. <example>Context: wave-executor is about to dispatch a vault-mirror agent that writes learning notes under ~/Projects/vault/40-learnings/. user: "dispatch vault-write agent" assistant: "Injecting frontmatter-guard snippet into agent prompt (vault scope detected). Required fields: id, type, created, updated. Enum type: note|daily|project|person|reference|idea|learning|session." <commentary>The wave-executor pre-dispatch hook calls detectVaultTaskScope() — the fileScope contains /Projects/vault/40-learnings/ so the guard triggers and the snippet is prepended to the agent system prompt.</commentary></example>'
 metadata:
+  user-invocable: 'false'
   model: inherit
 ---
 

package/.codex-plugin/skills/gitlab-portfolio/SKILL.md

@@ -2,6 +2,7 @@
 name: gitlab-portfolio
 description: 'Use when you need a single-pane cross-repo health view across all vault-registered GitLab and GitHub projects. Discovers repos from `_overview.md` frontmatter in `<vault>/01-projects/*/`, aggregates open issues, MRs, critical labels, and stale signals via parallel `glab`/`gh` calls, then writes an idempotent `_PORTFOLIO.md` dashboard. Runs automatically at session-start Phase 2 when `gitlab-portfolio.enabled=true`. Triggers: "show portfolio status", "refresh the portfolio dashboard", "which repos have critical issues", "run /portfolio". <example>Context: session-start, gitlab-portfolio.enabled=true, vault has 5 registered repos. user: "/session deep" assistant: "Portfolio: 3 critical issues across 2 repos — run /portfolio for details. Dashboard written to vault/01-projects/_PORTFOLIO.md."</example>'
 metadata:
+  user-invocable: 'false'
   model: sonnet
 ---
 

package/.codex-plugin/skills/hook-development/SKILL.md

@@ -2,6 +2,7 @@
 name: hook-development
 description: Use when creating, modifying, or debugging Claude Code hooks — PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification. Covers the plugin `hooks/hooks.json` wrapper format vs. the user `settings.json` direct format, matchers, security patterns, `$CLAUDE_PLUGIN_ROOT` portability, lifecycle limitations, and debugging. Trigger on "add a hook", "validate tool use", "block dangerous commands", "enforce completion", "hook-based automation".
 metadata:
+  user-invocable: 'false'
   model: sonnet
 ---
 

package/.codex-plugin/skills/mcp-builder/SKILL.md

@@ -2,6 +2,7 @@
 name: mcp-builder
 description: Use when creating a new MCP (Model Context Protocol) server, extending an existing one, or debugging tool discoverability/performance. Guides through research → implementation → test → eval phases with TypeScript-first guidance matching our stack. Trigger on phrases like "build an MCP server", "expose X as an MCP tool", "write MCP tools for Y", "integrate Z via MCP".
 metadata:
+  user-invocable: 'false'
   model: sonnet
 ---
 

package/.codex-plugin/skills/tmux-layout/SKILL.md

@@ -2,6 +2,7 @@
 name: tmux-layout
 description: 'Use this skill when the operator wants a prepared tmux visualization layout for the session''s side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug layout. Read-only side-channel observability — the coordinator chat stays in the operator''s original terminal. Trigger phrases: "tmux layout", "split panes for ci watch", "visualize session side-channels", "show me state-md tail and ci".'
 metadata:
+  user-invocable: 'true'
   model: inherit
   color: cyan
 allowed-tools:
@@ -20,4 +21,6 @@ The linked document is authoritative, including its prechecks, argument rules, a
 
 Resolve this link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root; resolve relative links inside the canonical document from its own directory. Keep the user’s project as the target of project operations.
 
+`$ARGUMENTS` means the trailing user input after the selected command skill, or an empty string when absent. Preserve flags, quoted text, and Unicode as data. Do not perform global substitution in the command document, shell expansion on the argument string, or execution of that string as shell code. When the workflow needs a command, pass its arguments through structured tool parameters or safely quoted individual arguments.
+
 Regenerate with `node scripts/generate-codex-skills.mjs`.

package/.codex-plugin/skills/tmux-layout/agents/openai.yaml

@@ -0,0 +1,5 @@
+# Generated by scripts/generate-codex-skills.mjs; do not edit.
+interface:
+  display_name: tmux-layout
+policy:
+  allow_implicit_invocation: true

package/.codex-plugin/skills/vault-mirror/SKILL.md

@@ -2,6 +2,7 @@
 name: vault-mirror
 description: 'Use when you need to populate the Meta-Vault with machine-generated notes derived from session-orchestrator JSONL records. Converts entries from `.orchestrator/metrics/sessions.jsonl` and `.orchestrator/metrics/learnings.jsonl` into vault-conformant Markdown under `50-sessions/` and `40-learnings/`. Called automatically at session-end Phase 3.7 and after evolve Phase 3.5 — only when `vault-integration.enabled=true` and `vault-integration.mode != "off"`. Idempotent: re-runs safely; skips hand-authored notes. Triggers: "mirror to vault", "sync session notes to vault", "write learning notes to vault", "vault-mirror failed at session close". <example>Context: session-end is finalizing, vault-integration.mode is "warn". user: "/close" assistant: "Running vault-mirror to write 50-sessions/session-2026-05-17.md from the closing session record — 1 created, 0 skipped."</example>'
 metadata:
+  user-invocable: 'false'
   model: haiku
 ---
 

package/.codex-plugin/skills/vault-sync/SKILL.md

@@ -2,6 +2,7 @@
 name: vault-sync
 description: 'Use when you need to validate the Meta-Vault''s Markdown frontmatter and wiki-link integrity before closing a session or after vault edits. Runs as a hard gate at session-end Phase 1 — blocks close if any `.md` file fails the Zod frontmatter schema or has dangling `[[wiki-links]]`. Supports three modes: `hard` (blocks on errors), `warn` (reports without blocking), `off` (skip). Reads `vault-sync.*` from Session Config; respects per-vault exclude globs from `CLAUDE.md`. Triggers: "vault validation failed at session close", "fix vault frontmatter errors", "check vault wiki-links", "why is session-end blocked by vault-sync". <example>Context: session-end Phase 1 quality gate, vault-sync.enabled=true, vault-sync.mode="hard". user: "/close" assistant: "vault-sync found 2 frontmatter errors in vault/40-learnings/ml-notes.md — missing required `id` field. Fixing before close."</example>'
 metadata:
+  user-invocable: 'false'
   model: haiku
 ---
 

package/.codex-plugin/skills/write-executable-plan/SKILL.md

@@ -2,6 +2,7 @@
 name: write-executable-plan
 description: Use when you have a PRD or design spec and need a bite-sized, executable implementation plan that any agent can follow without re-deriving structure. Produces `docs/plans/YYYY-MM-DD-<feature>.md` with per-task Files block, complete code per step (no placeholders), and exact verification commands. Rejects "TBD", "TODO", "add error handling", "similar to Task N".
 metadata:
+  user-invocable: 'true'
   model: inherit
   color: green
 allowed-tools:
@@ -21,4 +22,6 @@ The linked document is authoritative, including its prechecks, argument rules, a
 
 Resolve this link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root; resolve relative links inside the canonical document from its own directory. Keep the user’s project as the target of project operations.
 
+`$ARGUMENTS` means the trailing user input after the selected command skill, or an empty string when absent. Preserve flags, quoted text, and Unicode as data. Do not perform global substitution in the command document, shell expansion on the argument string, or execution of that string as shell code. When the workflow needs a command, pass its arguments through structured tool parameters or safely quoted individual arguments.
+
 Regenerate with `node scripts/generate-codex-skills.mjs`.

package/.codex-plugin/skills/write-executable-plan/agents/openai.yaml

@@ -0,0 +1,5 @@
+# Generated by scripts/generate-codex-skills.mjs; do not edit.
+interface:
+  display_name: write-executable-plan
+policy:
+  allow_implicit_invocation: true

package/.cursor/commands/architecture.md

@@ -0,0 +1,13 @@
+---
+description: Use when the user asks to improve architecture, find refactoring opportunities, surface deepening opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Surfaces shallow modules and hypothetical seams using a precise vocabulary (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality from LANGUAGE.md).
+---
+
+# /architecture
+
+Use the Session Orchestrator skill definition at `skills/architecture/SKILL.md`.
+
+Arguments: $ARGUMENTS
+
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+
+Cursor has no Skill tool. When the skill says to invoke another skill, Read `skills/<skill-name>/SKILL.md` and follow it. Supporting files (`soul.md`, phase docs) live in that same `skills/<skill-name>/` directory.

package/.cursor/commands/eval.md

@@ -1,5 +1,5 @@
 ---
-description: "Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v2 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score."
+description: "Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v3 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score."
 argument-hint: "[--session <id>] [--no-write] [--verify <run-id>]"
 ---
 

package/.cursor/commands/tmux-layout.md

@@ -0,0 +1,13 @@
+---
+description: "Use this skill when the operator wants a prepared tmux visualization layout for the session's side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug layout. Read-only side-channel observability — the coordinator chat stays in the operator's original terminal. Trigger phrases: \"tmux layout\", \"split panes for ci watch\", \"visualize session side-channels\", \"show me state-md tail and ci\"."
+---
+
+# /tmux-layout
+
+Use the Session Orchestrator skill definition at `skills/tmux-layout/SKILL.md`.
+
+Arguments: $ARGUMENTS
+
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+
+Cursor has no Skill tool. When the skill says to invoke another skill, Read `skills/<skill-name>/SKILL.md` and follow it. Supporting files (`soul.md`, phase docs) live in that same `skills/<skill-name>/` directory.

package/.cursor/commands/write-executable-plan.md

@@ -0,0 +1,13 @@
+---
+description: "Use when you have a PRD or design spec and need a bite-sized, executable implementation plan that any agent can follow without re-deriving structure. Produces `docs/plans/YYYY-MM-DD-<feature>.md` with per-task Files block, complete code per step (no placeholders), and exact verification commands. Rejects \"TBD\", \"TODO\", \"add error handling\", \"similar to Task N\"."
+---
+
+# /write-executable-plan
+
+Use the Session Orchestrator skill definition at `skills/write-executable-plan/SKILL.md`.
+
+Arguments: $ARGUMENTS
+
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.
+
+Cursor has no Skill tool. When the skill says to invoke another skill, Read `skills/<skill-name>/SKILL.md` and follow it. Supporting files (`soul.md`, phase docs) live in that same `skills/<skill-name>/` directory.

package/.cursor/skills/architecture/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: architecture
 description: Use when the user asks to improve architecture, find refactoring opportunities, surface deepening opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Surfaces shallow modules and hypothetical seams using a precise vocabulary (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality from LANGUAGE.md).
-disable-model-invocation: true
 ---
 
 # architecture

package/.cursor/skills/eval/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: eval
-description: "Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v2 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score."
+description: "Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v3 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score."
 ---
 
 # eval

package/.cursor/skills/tmux-layout/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: tmux-layout
 description: "Use this skill when the operator wants a prepared tmux visualization layout for the session's side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug layout. Read-only side-channel observability — the coordinator chat stays in the operator's original terminal. Trigger phrases: \"tmux layout\", \"split panes for ci watch\", \"visualize session side-channels\", \"show me state-md tail and ci\"."
-disable-model-invocation: true
 ---
 
 # tmux-layout

package/.cursor/skills/write-executable-plan/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: write-executable-plan
 description: "Use when you have a PRD or design spec and need a bite-sized, executable implementation plan that any agent can follow without re-deriving structure. Produces `docs/plans/YYYY-MM-DD-<feature>.md` with per-task Files block, complete code per step (no placeholders), and exact verification commands. Rejects \"TBD\", \"TODO\", \"add error handling\", \"similar to Task N\"."
-disable-model-invocation: true
 ---
 
 # write-executable-plan

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.6.0",
+  "version": "5.8.0",
   "description": "A repeatable Plan, Go, Close workflow for AI coding sessions: /session reads your repo and agrees the scope, /go runs the work in waves with a quality gate between each, /close verifies and commits. Runs on Claude Code, Codex CLI, Cursor and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer"

package/CHANGELOG.md

@@ -7,6 +7,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.8.0] - 2026-10-05
+
+### Added
+
+- **`scripts/lib/plugin-package-stage.mjs`** (#1518): one packed staging for Claude and Codex installs — `npm pack --ignore-scripts`, extract, optional `npm ci --omit=dev --ignore-scripts` and a validate callback on the new copy, then swap; a failed swap restores the previous stage, stale work dirs are swept.
+- **`atomicWriteText`** (#1032): async twin of `atomicWriteWithBackup` in `scripts/lib/io.mjs` that never rejects and cleans up its tmp; the error envelope gains `code`, and `envelopeToError` re-throws it for sites that must throw.
+- **`orchestrator.ledger.unreadable` event** (#1505): the orphan-reaper scan records why it skipped (`refused` for a symlink, EACCES or a non-regular file; `reader-threw`) before ending with `ledger-unreadable`, so an unreadable process register no longer disables the scan silently. A failing emit never fails the scan.
+- **`scripts/lib/test-sibling-coverage.mjs`** (#1030): measures how many production files have a test sibling under the scope gate's own matchers (glob, exact basename, mirror path); `--json` carries its definition. The wave-scope manifest reference now points at it instead of hard-coded counts.
+- **ADR-0016 Cross-session messaging** (#1053): Adopt for the live cross-session axis, Spike for Remote Control (#1056, closed negative); anchors "entries vs messages" (files hold state, messages are hints).
+- **Validator rule R9** (#1515): every `SKILL.md` states `user-invocable:` explicitly.
+
+### Changed
+
+- **`codex-install` installs from the packed copy** (#1518) instead of the checkout, so the Codex plugin cache no longer receives `.env.local`; it refuses while a local Codex marketplace reads the clone and hints at `~/.agents/plugins/marketplace.json` entries that resolve to it.
+- **`update:local` checks installation first** (#1519): not installed → skipped without touching the stage; a `kanevry` marketplace on another source joins the printed remove list; a relative `CLAUDE_CONFIG_DIR` is ignored.
+- **Hand-rolled atomic writes use the shared helpers** (#1032): seventeen sites in quality-gate, reconcile, skill-evolution, memory-proposals, auto-dialectic, auto-dream, peer-cards, worktree meta, slopcheck, two vault scripts and the learnings sweep, byte-identical; tmp names carry `.tmp` (mostly `.<base>.tmp.<hex>`), and that shape is ignored under `.orchestrator/metrics/`.
+- **Events ledger lives in the main checkout** (#1514): `eventsFilePath(repoRoot)` maps a root inside a linked worktree to its main checkout (spawn-free, via `.git` → `commondir`), and the launch dir from the environment goes through the same mapping. Hooks, scope-echo, materialize-wave-scope and about twenty readers (banners, backfill, eval, telemetry sync, retention) resolve the same file, including sessions launched inside a worktree and work in a second repo. Scope files and the dispatch ledger stay on the session root.
+- **`/` picker semantics** (#1515): a missing `user-invocable` key counts as true, as in Claude Code; all 51 skills now state it (28 operator commands, 23 helpers). `architecture`, `tmux-layout` and `write-executable-plan` became commands, the other seven helpers. Counters and all four adapter generators share `isUserInvocableSkill`; README, components, steering and site say 30 slash commands.
+- **`npm run update:local` installs from `npm pack`** (#1515): only package files reach the plugin cache (no `.env.local`, no `.orchestrator/` beyond `policy/`). It refuses only while a `directory` marketplace points at the clone and names the exact remove/add/install commands; GitHub and npm sources update as before. `evals/` ships in the package (without `evals/results/`).
+- **vault-mirror re-learn** (#1506): new disambiguation files get `-<sha256(record key)[0:8]>` (existing `-<uuid8>` files keep their name); a strictly newer record takes over the main note and the older one moves to its own disambiguation file, crash-safe in write order.
+- **Bootstrap consumer ignore block** (#1507): the three rotated-ledger patterns are ignored in consumer repos too.
+- **`vault-sync/validator.sh` installs nothing** (#1070): it checks that `zod`/`yaml` resolve (they are root dependencies) and otherwise exits 2 with `reason: setup-required` and a shell-quoted `npm ci` hint, emitted as valid JSON; session-end shows that reason instead of discarding stderr. The former silent `pnpm install` is gone.
+- **One source listing for the plugin surface** (#1240): `scripts/lib/plugin-surface.mjs` holds the frontmatter parser, the `commands/`/`skills/` listing and the `_`/`.` private-name filter used by all four adapter generators and the slash-command census. Generated output is unchanged.
+- **Nine more hand-rolled tmp+rename writes use the shared helper** (#1032): reconcile writer, ux-grill run record, vault-sync baseline, bootstrap-lock refresh, autopilot telemetry, and the backfill, migrate, cross-repo-migrate and session-record-repair scripts; their own backup schemes stay. `appendJsonlAtomic` now creates a missing parent directory.
+- **Phase 7.1 premise check runs in housekeeping sessions too** (#1521).
+- **Eval rubric-v3** (#1487): a quality_gate event counts as failed when it exited non-zero, timed out, or was recorded as `orchestrator.quality_gate.failed`. A killed reporting gate run with exit code 0 used to score `pass`. Only `verification-evidence` and `gate-health` change. The 9 stored `rubric-v2` records are not re-scored; `--verify` reports `VERSION-MISMATCH` for them.
+
+### Deprecated
+
+- **Frontend-slop hook** (#1121): `hooks/post-tooluse-frontend-slop.mjs` and the `frontend-slop-hook:` block are removed in the next major. With `enabled: true` the hook writes one deprecation line to stderr per run and otherwise works as before.
+
+### Removed
+
+- **`buildCandidatePoolsFromFile`** (#1021) from `scripts/lib/learnings/candidates.mjs`: no consumer besides its own test (never a documented public API; use `buildCandidatePools`).
+- **The separate `skills/vault-sync` dependency install** in GitLab CI, GitHub Actions and the pre-push gate (#1070): it pulled unlocked `zod`/`yaml` versions that no root `npm audit` saw; the root install already provides both.
+
+### Fixed
+
+- **Three watchers resolved the project from `CLAUDE_PLUGIN_ROOT`** (#1517): `wave-transcript-tail`, `convergence-monitor` and `ecosystem-health` read state inside the installed plugin directory; they use `getProjectDir()` now.
+- **A failed atomic write no longer leaves its tmp file** (#1032) when the write created it and then failed.
+- **vault-mirror refreshes a changed main note in the run that archives a stale disambig** (#1519) instead of one run later.
+- **A UTF-8 BOM on the first line of `learnings.jsonl` is stripped** (#1506) instead of making the record malformed.
+- **Unused learnings exports removed** (#1021): twelve exports without a consumer outside their own module.
+- **`OPTIONAL_FIELDS` declares every field the session validator checks** (#986): eleven were missing; the parity test now takes its census from `validateSession` itself.
+- **`mirror: none` is honoured at /close** (#1034): the GitHub mirror push checked only for a `github` remote, so such a repo pushed anyway. An explicit `none` now skips it; no key keeps today's behaviour; an unknown value fails loudly.
+- **A rule stays active through its `expires-at` day** (#1521): the loader used to drop it at 00:00 UTC of that date. Loader, budget guard and expiry sweep share one `ruleExpiryInstantMs`.
+- **A rate-limit HTTP 403 is `query-failed`, not `auth-error`** (#1034) in the mirror-issues banner and the GitHub protection audit, so a rate limit no longer advises a re-login; an unauthenticated rate limit and a 403 without rate-limit wording stay `auth-error`.
+- **Stale docs corrected**: memory-proposal provenance tag (#1027), `auto-commit-per-wave` described as the planned no-op it is (#1219), steering counts (#1515), two gate-event measurement docblocks (#966).
+
+## [5.7.0] - 2026-10-03
+
+### Added
+
+- **`scripts/vault-mirror-prune.mjs`** (#1513): applies the vault-mirror retention rules to the existing `40-learnings/` and `50-sessions/` notes. Dry run by default with a JSON manifest (`--manifest`: path, reason, action, target, kept copy, rollup); `--apply` writes the month rollups, then moves archived notes to `90-archive/mirror/<zone>/<same path>` with `status: archived` + `archived-reason`, then renames alias-folder and flat notes into their namespace. Reasons: `duplicate`, `superseded`, `expired`, `metrics-only-session`, `namespace-alias`, `flat-relocate`. Only notes with the mirror's `_generator` marker are touched; nothing is deleted; a second run plans nothing.
+
+### Changed
+
+- **vault-mirror narrative gate for sessions** (#1513): `vault-mirror.quality.min-narrative-chars` now measures the record's free text (`notes`, `narrative`, `summary`) instead of the rendered body with its tables. A record below it gets no note but one row in `50-sessions/<repo>/_rollup-YYYY-MM.md` (action `skipped-metrics-only`; idempotent). `0` disables the gate.
+- **vault-mirror learnings lifecycle** (#1513): the pre-#725 slug variant of a note is updated in place instead of getting a hyphenated twin; a new note whose normalised insight already exists in the namespace is refused (`skipped-duplicate-insight`); an expired learning is never created (`skipped-expired`) and its existing note becomes `status: archived` + `archived-reason: expired`; `--kind learning` also reads the sibling `learnings-archive.jsonl` and marks the notes of archived records (`expired` / `superseded`). `backfill-learnings-from-vault.mjs` falls back to `90-archive/mirror/40-learnings/`.
+- **`session-close-backfill.log` carries events only** (#1513): `skipped-*` outcomes are no longer appended (86 % of the Meta-Vault's 723 KB log); they remain queryable as ledger events.
+- **`sweep-expired-rules` removes expired single-entry rule files** (#1513): a generated rule with one learning and no counter sentence was skipped as `no-counter-sentence` forever; it is now deleted (pair stamped first) once the later of its frontmatter `expires-at` and the learning's store date has passed.
+- **Commit guard names the manifest** (#1514): a parse error and each block header now carry the manifest path (`.claude/wave-scope.json` vs `pkg/.claude/wave-scope.json`), and the "To proceed" hint prints once when both manifests block.
+- **Read failures other than a missing file are reported** (#1216): `countProposalsForWave` and the transcript tail's `readAgentType` now warn on stderr instead of silently returning `0` / `unknown`.
+- **Lint rejects the deprecated locks shim and the deleted `OWNER_YAML_PATH`** (#1234): `no-restricted-imports` with the replacement named in the message.
+- **ADR-0002 verdict corrected to Stay** (#1053): native session↔session and agent→coordinator messaging (Claude Code 2.1.224) removed the one capability Agent Teams added; ADR-0003/0007/0010 and the rules point at the addendum. LM-002a separates Channels from cross-session messaging.
+
+### Fixed
+
+- **Drift-check Check 7 derives learning keys with the shared `learningKeyOf`** (#1021): a learning with a blank title or an untrimmed type no longer produces a key that differs from the one the rule emitter stamps.
+- Shared helpers instead of private copies: one `tombstoneGap` for the three archive-gap sites (#1505), and `deriveFenceToken`, `learningKeyOf`, `kebab` imported where they were copied (#1021). Behaviour unchanged.
+
+### Removed
+
+- **H3 Agent Teams test harness** (`hooks/agent-teams-h3-test.sh`, `scripts/spikes/h3-agent-teams/`) — the question it measured is closed (#1061).
+
 ## [5.6.0] - 2026-10-03
 
 ### Added

package/README.md

@@ -1,7 +1,7 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-5.6.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.8.0-blue.svg)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/session-orchestrator.svg)](https://www.npmjs.com/package/session-orchestrator)
 
 **Give your agents a working rhythm.**
@@ -111,7 +111,7 @@ When you type `/session feature`:
 .claude/STATE.md                    # wave progress and deviations (harness-specific directory)
 ```
 
-The plugin is **51 skills, 27 slash commands, 14 typed subagents and 29 hook files across 10 event types**. A slash command is a skill whose frontmatter says `user-invocable: true` (25 of them) or one of the two remaining `commands/*.md` files (`/session`, `/templates-ack`) — one definition per name, so nothing is listed twice in the `/` picker. Skills, commands and agents are Markdown with YAML frontmatter; the code that dispatches, validates and records runs in `scripts/lib/*.mjs` and `hooks/*.mjs`. There is no build step and no compiled artifact — when a session does something you did not expect, you can open the file that decided it. Full inventory: [`docs/components.md`](docs/components.md).
+The plugin is **51 skills, 30 slash commands, 14 typed subagents and 29 hook files across 10 event types**. A slash command is a skill whose frontmatter says `user-invocable: true` (28 of them) or one of the two remaining `commands/*.md` files (`/session`, `/templates-ack`) — one definition per name, so nothing is listed twice in the `/` picker. Skills, commands and agents are Markdown with YAML frontmatter; the code that dispatches, validates and records runs in `scripts/lib/*.mjs` and `hooks/*.mjs`. There is no build step and no compiled artifact — when a session does something you did not expect, you can open the file that decided it. Full inventory: [`docs/components.md`](docs/components.md).
 
 ## Why it is built this way
 
@@ -129,7 +129,7 @@ How this compares to other orchestrators, with measured results kept separate fr
 
 | Feature | Claude Code | Codex CLI | Cursor IDE | Pi |
 |---|---|---|---|---|
-| All 27 commands | Native slash commands | Generated skills (`$session-orchestrator:<name>`) | Native `.cursor/commands` slash commands | Prompt templates |
+| All 30 commands | Native slash commands | Generated skills (`$session-orchestrator:<name>`) | Native `.cursor/commands` slash commands | Prompt templates |
 | Parallel agents | Agent tool | Multi-agent roles | Sequential only | Sequential (parallel planned) |
 | Session persistence | `.claude/STATE.md` | `.codex/STATE.md` | `.cursor/STATE.md` | `.pi/STATE.md` |
 | Scope enforcement | Active PreToolUse hook; blocking in `strict`, reporting in `warn` | Instructions only; no compatible `apply_patch` handler | `preToolUse` + `beforeShellExecution` bridge; scope blocking requires `strict`; `afterFileEdit` is post-hoc | `tool_call` bridge; scope blocking requires `strict` |
@@ -139,15 +139,15 @@ How this compares to other orchestrators, with measured results kept separate fr
 
 All four platforms share the same skills, commands and scripts; only the hooks differ, because each harness fires different events. Codex leaves its `PreToolUse` handlers empty because these guards do not yet match its tool names and edit payloads ([why](docs/codex-setup.md#why-our-pretooluse-guards-stay-unwired--the-reason-corrected)). Cursor and Pi have known event-coverage limits — see [`docs/cursor-setup.md`](docs/cursor-setup.md) and [`docs/pi-setup.md`](docs/pi-setup.md).
 
-## Recent highlights (v5.6.0)
+## Recent highlights (v5.8.0)
 
-Highlights of the v5.6.0 line:
+Highlights of the v5.8.0 line:
 
-- **Clearer about what you get.** The website, this README and the npm page now open with the problem the plugin solves and list the features by benefit: what each part does for you, then how it works.
-- **Sessions in a worktree or a subdirectory report their own tree.** A wave's start commit, changed files, HEAD and the stop record's branch now describe the tree the session works in, and the commit guard also checks the manifest of a session launched in a subdirectory, never less strictly than before (#1511).
-- **One rule for how scope paths are spelled.** The overlap check before dispatch and the scope tools now compare paths the same way, and `validate-wave-scope --assert-disjoint --no-manifest` checks a plan's file lists without a dummy manifest (#1510).
-- **A changed scope sidecar can no longer hide a violation.** If the per-wave sidecar changes under a standing manifest, peer records stop counting and you get one notice (#1504).
-- **Close-backfill reads ledger gaps only inside the session's own time window**, so one pruned archive no longer holds back every later session (#1512).
+- **Your secrets stay out of the plugin cache.** Claude and Codex installs now come from the packed package (`npm pack`), so `.env.local` and session state no longer land in `~/.claude` or `~/.codex` plugin caches (#1515, #1518).
+- **`mirror: none` means none.** `/close` no longer pushes to a GitHub remote when the repo opted out, and a fresh shell without `PLUGIN_ROOT` no longer breaks the mirror push (#1034).
+- **Honest gate scores.** Eval rubric v3 counts a gate run that was killed but exited 0 as failed; older records keep their own rubric version and are never re-scored silently (#1487).
+- **Rules live through their expiry day.** A rule's `expires-at` date is inclusive in the loader, the budget probe, the drift check and the expiry sweep alike (#1521).
+- **vault-sync needs no second install.** The validator resolves `zod`/`yaml` from the plugin's own dependencies and, if they are missing, says exactly which command fixes it (#1070).
 
 Full changes and verification: [CHANGELOG.md](CHANGELOG.md).