session-orchestrator 5.7.0 → 5.8.0

package/skills/session-start/SKILL.md

@@ -326,7 +326,7 @@ Operator-selected issues (from Phase 6) are appended AFTER this loop, not interl
 
 ## Phase 7.1: Issue Premise Verification (#730/H3)
 
-> Skip for `housekeeping` sessions (Phase 7 already skips deep research there).
+> Housekeeping too (#1521).
 > Runs on the shortlisted candidate issues from Phase 6 Pattern Recognition
 > (cap: 8 issues — cost control; prioritize the issues most likely to enter scope).
 
@@ -354,7 +354,7 @@ Invokes `buildLiveSignals` (single SSOT for the signals shape) then `selectMode(
 
 > Skip silently when `persistence: false` (no ledger for the event). Runs BEFORE the first writing action; everything not stated here is in `skills/_shared/fleet-protocol.md`.
 
-Build the check-in JSON (fields per the reference; `session` from `.orchestrator/current-session.json`, `modus` = session type, `kandidaten` = the issue numbers you intend to claim) and pipe it into `node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/fleet-checkin.mjs"` — it validates, stores `checkin/<session_id>.json` (0600) under `~/.config/navigator/` and emits `orchestrator.fleet.checkin`. Its stdout carries `navigator_state` and `navigator_adresse` (the lease's validated `adresse`, else `null`): on `active`, and only when `navigator_adresse` is non-null and reachable via `ListAgents`, send ONE hint to exactly that name, naming the file path — never expect or wait for a reply (CSM-004). Then read `auflagen/<session_id>.json`; if it is still absent at the stdout's `fallback_due_at`, the reference's Standard-Auflagen apply (the CLI computes that deadline: `zeit` plus `CHECKIN_FALLBACK_MIN` while a navigator is active, `zeit` itself — immediately — otherwise). Reading work and edits in the own worktree continue meanwhile.
+Build the check-in JSON (fields per the reference; `session` from `.orchestrator/current-session.json`, `modus` = session type, `kandidaten` = the issue numbers you intend to claim) and pipe it into `node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/fleet-checkin.mjs"` — it validates, stores `checkin/<session_id>.json` (0600) under `~/.config/navigator/` and emits `orchestrator.fleet.checkin`. Its stdout carries `navigator_state` and `navigator_adresse` (the lease's validated `adresse`, else `null`): on `active`, and only when `navigator_adresse` is non-null and reachable via `ListAgents`, send ONE hint to exactly that name, naming the file path — never expect or wait for a reply (CSM-004). Then read `auflagen/<session_id>.json` via `node "${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$PLUGIN_ROOT}}/scripts/fleet-auflagen.mjs" <session_id>` (only a file whose `repo` resolves to this repo's git common dir is `accepted`; a `rejected` one counts as absent); if it is still absent at the stdout's `fallback_due_at`, the reference's Standard-Auflagen apply (the CLI computes that deadline: `zeit` plus `CHECKIN_FALLBACK_MIN` while a navigator is active, `zeit` itself — immediately — otherwise). Reading work and edits in the own worktree continue meanwhile.
 
 ## Phase 8: Structured Presentation & Q&A
 

package/skills/session-start/phase-7-1-premise-check.md

@@ -18,6 +18,7 @@ For each claim, run exactly ONE Grep or Read against the actual codebase (or
 transcript discipline as `.claude/rules/parallel-sessions.md` § PSA-006.
 Budget: this phase is a spot-check, not a deep audit. If one grep cannot
 ground the claim, mark UNVERIFIED and move on — do not rabbit-hole.
+Per issue, also run `git log --grep='#<N>'`: fixes often land without closing the issue.
 
 ## Verdicts
 
@@ -44,4 +45,4 @@ decomposing) without re-running the greps.
 
 - Re-verifying every sentence of every issue — cap 3 claims/issue, 8 issues.
 - Treating UNVERIFIED as a blocker — it is informational only.
-- Running this for housekeeping sessions — predefined tasks carry no premise risk worth the latency.
+- Skipping it in housekeeping — items go stale there too (#1521: 4 of 7 were fixed).

package/skills/session-start/references/operations-contract.md

@@ -50,7 +50,10 @@ workflow with its own verified scope, tests and review; it does not turn this en
 into a fabricated wave session.
 Before the first writing action, write the fleet check-in and read the fleet's constraints —
 the same step as session-start Phase 7.6 (`scripts/fleet-checkin.mjs`; fields and the
-Standard-Auflagen in `skills/_shared/fleet-protocol.md`). If no `auflagen/` file has appeared by
+Standard-Auflagen in `skills/_shared/fleet-protocol.md`). Read the Auflagen with
+`node scripts/fleet-auflagen.mjs <session_id>`, never the file directly: only a file whose `repo`
+resolves to this repo's git common dir is `accepted`, and a `rejected` one counts as absent
+(`skills/_shared/fleet-protocol.md` § `auflagen/<session_id>.json`). If no `auflagen/` file has appeared by
 the `fallback_due_at` on the CLI's stdout, the Standard-Auflagen apply: the CLI sets it
 `CHECKIN_FALLBACK_MIN` after `zeit` while a navigator is active, and to `zeit` itself —
 immediately — otherwise. A hint to the navigator is optional and never awaited.

package/skills/tmux-layout/SKILL.md

@@ -6,6 +6,7 @@ description: >
   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".
+user-invocable: true
 model: inherit
 color: cyan
 tools: Read, Bash, Grep, Glob

package/skills/vault-mirror/SKILL.md

@@ -10,6 +10,7 @@ description: >
   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>
+user-invocable: false
 model: haiku
 ---
 

package/skills/vault-sync/SKILL.md

@@ -10,6 +10,7 @@ description: >
   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>
+user-invocable: false
 model: haiku
 ---
 
@@ -28,9 +29,8 @@ Phase 1 ships a self-contained validator that reads every `.md` file under `VAUL
 ### Files
 
 - `validator.mjs` — Node.js ESM validator. Uses `zod` + `yaml` npm packages. Reads `VAULT_DIR` (env or default cwd), walks the tree, skipping `node_modules/`, `.git/`, `.obsidian/`. `90-archive/` is walked but never *checked* (#833): archived notes stay in the link-target register — so an inbound `[[wiki-link]]` to an archived note resolves instead of dangling — while their frontmatter is skipped and counted in `archived_skipped_count`. For each `.md`: parses frontmatter, validates against the inline Zod schema, extracts `[[wiki-links]]`, verifies each target resolves. Emits JSON report on stdout.
-- `validator.sh` — Thin POSIX wrapper. Resolves `VAULT_DIR` from arg 1 or env, self-bootstraps deps via `pnpm install --silent` on first run, execs the Node validator. Session-end and other callers use this entry point.
-- `package.json` — Declares `zod` (`^3.24.0`, matching projects-baseline) and `yaml` (`^2.5.0`) as deps. `pnpm-lock.yaml` is committed; `node_modules/` is gitignored.
-- `tests/validator.bats` — 16 BATS cases covering clean vaults, broken frontmatter, missing required fields, dangling links, no-vault skipping, README-style files, nested directories, and archive/obsidian exclusion.
+- `validator.sh` — Thin POSIX wrapper. Resolves `VAULT_DIR` from arg 1 or env, checks that `zod` and `yaml` resolve from the skill directory, execs the Node validator. It never installs anything: unresolvable deps exit 2 with `"reason":"setup-required"` and the one setup command, `npm ci` in the plugin root (#1070). Session-end and other callers use this entry point.
+- `package.json` — Declares `zod` (`^3.24.0`, matching projects-baseline) and `yaml` (`^2.5.0`) as deps. No lockfile is committed (`skills/vault-sync/package-lock.json` is gitignored at the repo root); `node_modules/` is gitignored.
 - `tests/fixtures/` — Seven fixture vaults matching each test scenario.
 
 ### Schema source
@@ -41,9 +41,9 @@ The inline Zod schema is vendored from the canonical source at `projects-baselin
 
 `skills/vault-sync/package.json` pins `yaml ^2.5.0` / `zod ^3.24.0` — intentionally NOT the root's `yaml ^2.9.0` / `zod ^3.25.76`. This is not drift to fix:
 
-- Both CI hosts install this sub-package on its own, independent of the root install (`.gitlab-ci.yml:121` and `.github/workflows/test.yml:93`, both: `(cd skills/vault-sync && npm install --no-audit --no-fund)`).
-- The root `package.json` declares no `workspaces`, so `npm ci` at the root never touches this folder's deps; `skills/vault-sync/node_modules/` is the only place `zod` resolves for this skill (`scripts/lib/vault-archive.mjs:19-21`).
-- The `zod ^3.24.0` pin deliberately tracks the projects-baseline version, not this repo's own (`scripts/release.mjs:488`).
+- Nothing installs this sub-package. Neither CI host runs a nested install any more — both run only the root `npm ci`, and `.husky/pre-push` links only the root `node_modules/` into its tracked-tree clone. The nested install was dropped on 2026-10-05: it pulled unlocked `zod`/`yaml` versions (this folder's lockfile is gitignored) that the root `npm audit` never saw, and the vault-sync test files ran 125 passed / 0 failed without it.
+- The root `package.json` declares no `workspaces`, so `npm ci` at the root never touches this folder's deps. Node resolves `zod`/`yaml` from this folder via the root's own `dependencies` (`yaml ^2.9.0`, `zod ^3.25.76`) — measured 2026-10-05 via `import.meta.resolve('zod')` from this folder → `<root>/node_modules/zod`. That is the runtime path in CI, in every worktree and for every end user, so the root dependencies must stay. A stale local `skills/vault-sync/node_modules/` from an older manual install would still win resolution; delete it if versions disagree.
+- The `zod ^3.24.0` pin deliberately tracks the projects-baseline version, not this repo's own (`scripts/release.mjs:622`).
 
 The root's dependency versions are NOT the SSOT for this folder — do not "fix" this pin to match the root.
 

package/skills/vault-sync/validator.sh

@@ -8,13 +8,18 @@
 # Behavior:
 #   - Resolves VAULT_DIR from arg 1 or env.
 #   - Ensures `node` is available.
-#   - Auto-installs deps on first run (pnpm install --silent) if node_modules missing.
+#   - Checks that `zod` and `yaml` resolve from this directory. They are
+#     runtime dependencies of the ROOT package (package.json `dependencies`),
+#     so Node resolves them from the plugin root's node_modules/. Missing →
+#     exit 2 with status `setup-required` and the one npm-canonical setup
+#     command. Never installs anything itself (#1070 AC3/AC6).
 #   - Execs validator.mjs; propagates exit code.
 #
 # Exit codes (mirror validator.mjs):
 #   0 — vault valid (or skipped: no vault)
 #   1 — validation errors
-#   2 — infrastructure error (missing node / pnpm, missing validator.mjs)
+#   2 — infrastructure error (missing node, missing validator.mjs,
+#       dependencies not installed → status `setup-required`)
 #
 # Output: JSON report on stdout (machine-readable).
 
@@ -36,18 +41,32 @@ if ! command -v node >/dev/null 2>&1; then
   exit 2
 fi
 
+# Emit the infra-error envelope via node so a path containing a quote or a
+# backslash still yields valid JSON (paths travel through env, never through
+# the JSON text). Args: reason [detail] [setup].
+infra_error() {
+  SO_VS_REASON="$1" SO_VS_DETAIL="${2:-}" SO_VS_SETUP="${3:-}" node -e '
+    const o = { status: "infra-error", reason: process.env.SO_VS_REASON };
+    if (process.env.SO_VS_DETAIL) o.detail = process.env.SO_VS_DETAIL;
+    if (process.env.SO_VS_SETUP) o.setup = process.env.SO_VS_SETUP;
+    console.error(JSON.stringify(o));' >&2
+}
+
 if [[ ! -f "$VALIDATOR_MJS" ]]; then
-  echo "{\"status\":\"infra-error\",\"reason\":\"validator.mjs not found at $VALIDATOR_MJS\"}" >&2
+  infra_error "validator.mjs not found at $VALIDATOR_MJS"
   exit 2
 fi
 
-# ── Self-bootstrap node_modules on first run ───────────────────────────────
-if [[ ! -d "$SCRIPT_DIR/node_modules" ]]; then
-  if ! command -v pnpm >/dev/null 2>&1; then
-    echo '{"status":"infra-error","reason":"pnpm not found; cannot bootstrap dependencies"}' >&2
-    exit 2
-  fi
-  (cd "$SCRIPT_DIR" && pnpm install --silent) >&2
+# ── Dependency readiness (no install, no foreign package manager) ─────────
+# `zod`/`yaml` come from the root package's `dependencies`; a nested
+# skills/vault-sync/node_modules/ is NOT required. Probe resolution from this
+# directory instead of testing for a particular node_modules folder, so an npm
+# install (deps hoisted above the package) and a plugin checkout both pass.
+if ! (cd "$SCRIPT_DIR" && node --input-type=module \
+      -e "import.meta.resolve('zod'); import.meta.resolve('yaml');") >/dev/null 2>&1; then
+  PLUGIN_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+  infra_error "setup-required" "zod/yaml not resolvable from $SCRIPT_DIR" "cd $(printf %q "$PLUGIN_ROOT") && npm ci"
+  exit 2
 fi
 
 # ── Execute validator ──────────────────────────────────────────────────────

package/skills/wave-executor/references/wave-loop-scope-manifest.md

@@ -87,7 +87,7 @@ Before each wave dispatch:
 
    The per-agent path IS `$AGENT_FILESCOPE_JSON` — the same file `--assert-subset` (#796 below), Grounding Injection (#85), the Learnings-Index (#1014) and File-Scope Injection (#1020) consume. Never write a `$TMPDIR` copy: it degrades to a signal-free allow when an injector cannot find the addressable wave-keyed file. The coordinator's record is materialized as `coordinator.json` and included in the aggregate, so its direct edits are covered by the two checks below.
 
-   > **`<state-dir>/filescopes/` is control state, like `wave-scope.json` itself — never a wave territory.** Step 3.1 necessarily runs before the union exists, so writing these files reports `bash-write-verify: N file(s) changed by a Bash call OUTSIDE the wave's allowedPaths` naming `filescopes/wave-<N>/*.json`. Expected once per wave rollover at this step; it is information, not a scope violation. Never widen `allowedPaths` to silence it — that would grant agents write access to the deconfliction record itself.
+   > **`<state-dir>/filescopes/` is control state, like `wave-scope.json` itself — never a wave territory.** Step 3.1 necessarily runs before the union exists, so `hooks/post-bash-write-verify.mjs` drops these files from its out-of-scope report the same way it drops `wave-scope.json` — keyed on the active manifest's state dir (`isScopeDeclarationPath`, #1027 Pkt 5) — and writing them reports nothing. Never widen `allowedPaths` instead: that would grant agents write access to the deconfliction record itself.
 
    **3.1a — a peer session's declared paths are their OWN record (#1195).** When a reachable peer session runs in this same checkout and has sent a Peer-Scope-Union request (`skills/_shared/parallel-aware-auq.md` § Peer-Scope-Union), carry its complete path list into the record array as exactly ONE record `{"id":"peer-session-<id>","files":[…]}` — `<id>` being the peer's semantic session id. Never merge peer paths into an agent's record: an agent record is a territory ONE agent may write, and a peer's paths are a territory NO agent of this wave may write. Keeping them separate is also what makes the disjointness check meaningful — a peer path colliding with an agent's scope is a real collision that must surface at 3.2, not be laundered by living in that agent's own record. Mechanically, a peer record takes part in `--assert-disjoint` and is EXCLUDED from `--union` (`unionFileScopes`, `scripts/lib/scope-gate.mjs`), so `allowedPaths` never grants a peer's paths to this wave's agents — which is precisely what keeps them a territory no agent may write. It also gets NO per-agent shape-(a) file: `materialize-wave-scope.mjs` writes peer records into the aggregate only, because `$AGENT_FILESCOPE_JSON` is addressed by an agent id at dispatch and no agent is dispatched for a peer session. `hooks/post-bash-write-verify.mjs` reads the same aggregate sidecar and reports a change under a `peer-session-*` record as a peer write instead of a violation — reachable only BECAUSE the union excludes it (the hook sees a path only while it is outside `allowedPaths`).
 
@@ -121,11 +121,11 @@ Before each wave dispatch:
 
    > **Fail-closed:** an ABSENT or unrecognised `role` does **not** expand. Omitting it fails loudly (an agent's write to its own test is blocked, recoverable by one re-union); the opposite default would silently hand a Quality phase-1 simplification agent write access to the suite. `{ enabled: false }` is the unconditional opt-out and `{ enabled: true }` the explicit opt-in — both override the role.
 
-   **It emits a GLOB, never a computed concrete path.** Resolve via the production file's basename, e.g. `foo.mjs` → `tests/**/foo*.test.mjs` — the same form `§ 4. Test-consolidation branch` already uses, stated once. Measured over all **439** tracked production `.mjs` in THIS repo (production = `scripts/**` + `hooks/**` + `skills/**`; tests = a top-level `tests/**` mirror with the `scripts/` prefix dropped): a same-basename test exists somewhere under `tests/` for **375/439 (85.4%)**, whereas a naive 1:1 mirror path resolves for only **272/439 (62.0%)**. So the glob is right ~85% of the time and *harmless* when wrong — it grants write access to a path that may not exist; a computed concrete path would be wrong ~38% of the time **and still deny the real test**. The ~15% residual is real, mostly semantic naming (`scripts/lib/learnings/*.mjs` → `tests/unit/learnings.test.mjs`): when an agent's test sibling does not match the glob, add it by hand to that agent's "Files:" scope in the session plan. This is an 85% default, not a guarantee.
+   **It emits a GLOB, never a computed concrete path.** Resolve via the production file's basename, e.g. `foo.mjs` → `tests/**/foo*.test.mjs` — the same form `§ 4. Test-consolidation branch` already uses, stated once. The measurement is `scripts/lib/test-sibling-coverage.mjs`, not a count restated here — run `node scripts/lib/test-sibling-coverage.mjs --json` and cite its envelope (it carries its own definition, `ref` and the uncovered list). It counts production files by negation (every tracked file a sibling-rule source matches that is not test-side) and reports three figures: **glob** (the scope gate's own `testSiblingsFor()` + `pathMatchesPattern()`), **exact** (a `tests/**/<stem>.test.mjs` exists), **mirror** (the naive 1:1 path `tests/<path minus scripts/>.test.mjs`). Measured at `HEAD=af58a173`, 2026-10-03, index clean, over the script's population (tracked `.mjs` matched by the sibling-rule source minus every test-side path, 571 files): glob **511/571 (89.5 %)**, exact **491/571 (86.0 %)**, mirror **353/571 (61.8 %)**. So the glob is right ~9 times in 10 and *harmless* when wrong — it grants write access to a path that may not exist; a computed mirror path would be wrong ~38 % of the time **and still deny the real test**. The residual is real, mostly semantic naming (`scripts/lib/learnings/*.mjs` → `tests/unit/learnings.test.mjs`) and untested root config files: when an agent's test sibling does not match the glob, add it by hand to that agent's "Files:" scope in the session plan. This is a default, not a guarantee.
 
-   > Measured at `HEAD=730ee9d`, 2026-08-03, clean-tree, via `git ls-files | grep -E '^(scripts|hooks|skills)/.*\.mjs$'` for the denominator, matched against `git ls-files | grep -E '^tests/.*\.test\.mjs$'` by basename (85.4% figure) and by mirrored path (62.0% figure). Re-measure before citing these downstream — a count re-briefed later is a claim about the past (`.claude/rules/parallel-sessions.md` § PSA-006).
+   > Re-measure before citing these figures downstream — a count re-briefed later is a claim about the past (`.claude/rules/parallel-sessions.md` § PSA-006). The previous hand count (`730ee9d`, 2026-08-03: 375 / 272 of 439, denominator `scripts/` + `hooks/` + `skills/` only) is superseded by the script (#1030 P3).
 
-   > **Over-grant ceiling (#1030):** the glob is a basename *prefix* (`tests/**/{basename}*.test.mjs`, `scripts/lib/scope-gate.mjs:312`), so a production file sharing a basename with another receives the other's test siblings — and a stem that prefixes another (`cli` → `cli-flags`) does too, so the figure below is a lower bound. Measured at `HEAD=0e0c4b08`, 2026-10-03: `git ls-files '*.mjs' | grep -v '^tests/' | xargs -n1 basename | sort | uniq -d | wc -l` → **34** colliding basenames, covering **80 of 572** production `.mjs` (**14.0 %**; files via `… | sort | uniq -D | wc -l`, denominator via `git ls-files '*.mjs' | grep -v '^tests/' | wc -l`; top: `schema.mjs` 8×). The error direction is the harmless one — a too-wide grant, never a denied write. **Revisit-Trigger:** a plan author disables the sibling expansion to dodge a false-positive collision between two same-named production files — then scope the glob by directory, but NOT by a raw `{dir}`: `renderSiblingTemplate` fills it with `scripts/lib`, while the test tree drops the `scripts/` prefix (`tests/lib/`), so a raw `{dir}` would deny real test writes; it needs a source→test prefix mapping first.
+   > **Over-grant ceiling (#1030):** the glob is a basename *prefix* (`tests/**/{basename}*.test.mjs`, `scripts/lib/scope-gate.mjs:312`), so a production file sharing a basename with another receives the other's test siblings — and a stem that prefixes another (`cli` → `cli-flags`) does too, so the figure below is a lower bound. Measured at `HEAD=0e0c4b08`, 2026-10-03: `git ls-files '*.mjs' | grep -v '^tests/' | xargs -n1 basename | sort | uniq -d | wc -l` → **34** colliding basenames, covering **80 of 572** production `.mjs` (**14.0 %**; population = tracked `.mjs` outside `tests/` at `0e0c4b08`, which still counts the one co-located test `skills/vault-sync/tests/schema-drift.test.mjs` — the whole gap to the script's 571, the same recipe also gives 572 at `af58a173`; files via `… | sort | uniq -D | wc -l`, denominator via `git ls-files '*.mjs' | grep -v '^tests/' | wc -l`; top: `schema.mjs` 8×). The error direction is the harmless one — a too-wide grant, never a denied write. **Revisit-Trigger:** a plan author disables the sibling expansion to dodge a false-positive collision between two same-named production files — then scope the glob by directory, but NOT by a raw `{dir}`: `renderSiblingTemplate` fills it with `scripts/lib`, while the test tree drops the `scripts/` prefix (`tests/lib/`), so a raw `{dir}` would deny real test writes; it needs a source→test prefix mapping first.
 
    **The sibling rule is repo-configurable, not a hardcoded layout.** THIS repo has zero `__tests__/` directories and no co-located tests; consumer-repo shapes (`<file>.test.*` beside the source, `<dir>/__tests__/**`, `supabase/migrations/** → supabase/tests/**`) are configured per repo and do not apply here.
 

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

@@ -1,6 +1,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".
+user-invocable: true
 model: inherit
 color: green
 tools: Read, Grep, Glob, Bash, Write