session-orchestrator 5.2.0 → 5.4.0

package/pi/prompts/session.md

@@ -1,6 +1,6 @@
 ---
 description: "Start a development session (housekeeping, feature, deep; ultradeep = deep + profile)"
-argument-hint: "[housekeeping|feature|deep|ultradeep]"
+argument-hint: "[housekeeping|feature|deep|ultradeep] [task context]"
 ---
 
 # /session

package/pi/prompts/test-audit.md

@@ -0,0 +1,12 @@
+---
+description: "Use when writing, reviewing, or pruning tests. Three modes, one value bar: a four-question gate before any new test is written, a focused audit of one scope, and a campaign over a whole repo or subsystem that removes the least useful tests under a coverage guard. Every delete, merge, or repair carries written evidence and a caught mutation. Triggered by \"audit the tests\", \"prune the test suite\", \"remove low-value tests\", \"test diet\", \"is this test worth adding\", /test-audit."
+argument-hint: "[gate|audit|campaign] [scope] [--goal \\\"<goal>\\\"]"
+---
+
+# /test-audit
+
+Use the Session Orchestrator skill definition at `skills/test-audit/SKILL.md`.
+
+Arguments: $@
+
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/rules/README.md

@@ -9,9 +9,14 @@ It is **not** the always-on rule set of *this* repository — those live in
 "rules" but play opposite roles: `rules/` ships rules **out** to other repos,
 `.claude/rules/` is what this repo runs on day-to-day.
 
-Every file here carries a
+Every rule file here carries a
 `<!-- source: session-orchestrator plugin (canonical: rules/<path>) -->` header.
-On sync, plugin-sourced files are overwritten in the consumer while its
+In a rule with frontmatter it stands on the first line directly after the
+closing `---` — the frontmatter itself must open on line 1, because Claude Code
+reads a rule's frontmatter only there. A rule without frontmatter carries the
+header on line 1. A path-scoped rule declares its file patterns twice, as
+`globs:` and `paths:` with identical lists: `paths:` is the only key Claude Code
+reads, `globs:` is what `rule-loader.mjs` reads first (#1449). On sync, plugin-sourced files are overwritten in the consumer while its
 locally-authored rules are preserved (copy-on-write). The canonical manifest of
 what vendors where is [`_index.md`](./_index.md).
 

package/rules/_index.md

@@ -40,7 +40,7 @@ baseline project type (`nextjs-saas`, `express-service`, `docker-service`,
 - `always-on/build-value.md` — BV-001..004: the seven-rung build ladder, the four protections never simplified away
 - `always-on/cross-session-messaging.md` — CSM-001..005: messaging is transport, not shared state; no permission laundering
 - `always-on/loop-and-monitor.md` — LM-001..008: routing between `/goal`, Workflows, Channels, Monitor, `/loop`, and Routines
-- `always-on/bash-harness-pitfalls.md` — six false-green shell-harness failure classes (path-scoped via its own `globs:`/`paths:` frontmatter)
+- `always-on/bash-harness-pitfalls.md` — six false-green shell-harness failure classes (path-scoped via `globs:` + `paths:` frontmatter carrying identical lists — `paths:` is what Claude Code reads, `globs:` what `rule-loader.mjs` reads first; #1449)
 
 ## opt-in-stack (vendored on match)
 
@@ -52,8 +52,8 @@ baseline project type (`nextjs-saas`, `express-service`, `docker-service`,
 
 ## opt-in-domain (vendored on match)
 
-- `opt-in-domain/prompt-caching.md` — Anthropic prompt caching (breakpoint placement, TTL selection, pre-warming, verification) [archetypes: nextjs-saas, express-service, docker-service, monorepo-oss, cli-tool]
+- `opt-in-domain/prompt-caching.md` — Anthropic prompt caching (breakpoint placement, TTL selection, pre-warming, verification) [archetypes: nextjs-saas, express-service, docker-service, monorepo-oss]
 
 ## Sync mechanism
 
-Consumer repos receive these files via `/bootstrap --sync-rules`. Re-running the command syncs every manifest category that has entries: universal entries always vendor, and archetype-tagged entries vendor only when the consumer repo's resolved archetype matches. Plugin-sourced files are overwritten while local rules are preserved (copy-on-write via the `<!-- source: session-orchestrator plugin ... -->` header on plugin files). Category entries must not share a basename, because all synced files flatten into `.claude/rules/`.
+Consumer repos receive these files via `/bootstrap --sync-rules`. Re-running the command syncs every manifest category that has entries: universal entries always vendor, and archetype-tagged entries vendor only when the consumer repo's resolved archetype matches. Plugin-sourced files are overwritten while local rules are preserved (copy-on-write via the `<!-- source: session-orchestrator plugin ... -->` header on plugin files). That header stands on the first line directly after the closing `---` of a rule's frontmatter, because Claude Code reads frontmatter only when it opens on line 1; only a rule without frontmatter carries it on line 1 (#1449). A consumer copy written in the older format (header on line 1, frontmatter after it) still counts as plugin-owned and is rewritten into the current format on the next sync. Category entries must not share a basename, because all synced files flatten into `.claude/rules/`.

package/rules/always-on/bash-harness-pitfalls.md

@@ -1,4 +1,3 @@
-<!-- source: session-orchestrator plugin (canonical: rules/always-on/bash-harness-pitfalls.md) -->
 ---
 globs:
   - "**/*.sh"
@@ -6,8 +5,15 @@ globs:
   - scripts/**
   - tests/**
   - .husky/**
+paths:
+  - "**/*.sh"
+  - "**/*.bash"
+  - scripts/**
+  - tests/**
+  - .husky/**
 tier: wave-only
 ---
+<!-- source: session-orchestrator plugin (canonical: rules/always-on/bash-harness-pitfalls.md) -->
 # Bash / Shell-Harness Pitfalls (Path-scoped)
 
 Six recurring bash-harness failure classes, each surfaced by a live run rather

package/rules/opt-in-domain/prompt-caching.md

@@ -1,11 +1,15 @@
-<!-- source: session-orchestrator plugin (canonical: rules/opt-in-domain/prompt-caching.md) -->
 ---
 globs:
   - "**/lib/ai/**"
   - "**/lib/llm/**"
   - "**/providers/**"
+paths:
+  - "**/lib/ai/**"
+  - "**/lib/llm/**"
+  - "**/providers/**"
 tier: wave-only
 ---
+<!-- source: session-orchestrator plugin (canonical: rules/opt-in-domain/prompt-caching.md) -->
 # Prompt Caching Rules (Path-scoped — repos using `@anthropic-ai/sdk` or `@ai-sdk/anthropic`)
 
 > Path-scoped — applies anywhere a project imports `@anthropic-ai/sdk` or uses the `@ai-sdk/anthropic` provider. Out of scope: `session-orchestrator` itself (no SDK use; `backend.md` § "AI Provider Abstraction" already forbids direct SDK imports in business logic, and the orchestrator runs inside Claude Code's harness which manages caching at the platform layer).
@@ -267,4 +271,4 @@ The four PoCs filed against this rule. Each adopts in <30 LOC and is independent
 
 ## See Also
 
-backend.md · testing.md · development.md
+backend.md

package/rules/opt-in-stack/backend-data.md

@@ -1,4 +1,3 @@
-<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/backend-data.md) -->
 ---
 globs:
   - src/lib/db/**
@@ -8,8 +7,17 @@ globs:
   - migrations/**
   - src/lib/redis/**
   - src/lib/queue/**
+paths:
+  - src/lib/db/**
+  - src/lib/cache/**
+  - src/services/db/**
+  - supabase/**
+  - migrations/**
+  - src/lib/redis/**
+  - src/lib/queue/**
 tier: wave-only
 ---
+<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/backend-data.md) -->
 # Backend Data Rules (Path-scoped)
 
 ## Database (Supabase)
@@ -185,4 +193,4 @@ async function updateUser(id: string, data: Partial<User>): Promise<void> {
 - Batch operations: use `.upsert()` or `.insert()` with arrays instead of individual inserts in loops.
 
 ## See Also
-development.md · security.md · security-web.md · testing.md · frontend.md · backend.md · swift.md · mvp-scope.md · cli-design.md · parallel-sessions.md
+security-web.md · frontend.md · backend.md · swift.md · parallel-sessions.md

package/rules/opt-in-stack/backend.md

@@ -1,4 +1,3 @@
-<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/backend.md) -->
 ---
 globs:
   - src/app/**
@@ -6,8 +5,15 @@ globs:
   - src/lib/api/**
   - src/routes/**
   - src/app/api/**
+paths:
+  - src/app/**
+  - src/services/**
+  - src/lib/api/**
+  - src/routes/**
+  - src/app/api/**
 tier: wave-only
 ---
+<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/backend.md) -->
 # Backend Rules (Path-scoped)
 
 ## Server Actions (Next.js)
@@ -165,7 +171,7 @@ Split api and worker into separate processes when any of these apply: queue-base
 - Named events (`event: <name>\n`) instead of untyped `data:` payloads, so client code reads `source.addEventListener('<name>', ...)` rather than switching on payload shape.
 - Naming: lowercase, dot-scoped, noun-verb. Examples: `draft.ready`, `classification.done`, `job.failed`, `stream.heartbeat`, `stream.end`.
 - Scope events by domain, not by endpoint. Two endpoints emitting `job.failed` is fine if the payload shape is identical.
-- Document the event catalog in the service's `CLAUDE.md` or `docs/api.md` — consumers need to know what to listen for without reading source.
+- Document the event catalog in the service's `CLAUDE.md` or `docs/api.md` — consumers need to know what to listen for without reading source. <!-- path-check: example -->
 
 ### Client reconnect pattern
 - `EventSource` reconnects automatically on network drop. Use the `Last-Event-ID` header to resume from the last received ID — set `id: <number>\n` on each server event for this to work.
@@ -285,7 +291,7 @@ Uses the canonical envelope from the [Canonical API Response Envelope](#canonica
 - **Reusable helper:** candidate for `@your-org/http-client` or a dedicated `@your-org/ringbuffer` package if demand grows past 2 consumer repos.
 
 ## Feature Flags
-- Use environment-variable-backed typed flags as default (see `docs/feature-flags.md`).
+- Use environment-variable-backed typed flags as default (see `docs/feature-flags.md`). <!-- path-check: example -->
 - Naming convention: `FF_<FEATURE_NAME>` in `.env`.
 - Every flag must have an expiry date. Remove within 30 days of full rollout.
 
@@ -387,4 +393,4 @@ export async function askAI(prompt: string, options?: { model?: string; maxToken
 - Checking budget after the LLM call (check before, enforce before spending)
 
 ## See Also
-development.md · security.md · security-web.md · testing.md · frontend.md · backend-data.md · swift.md · mvp-scope.md · cli-design.md · parallel-sessions.md
+security-web.md · frontend.md · backend-data.md · swift.md · parallel-sessions.md

package/rules/opt-in-stack/frontend.md

@@ -1,12 +1,17 @@
-<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/frontend.md) -->
 ---
 globs:
   - src/**/*.tsx
   - src/**/*.css
   - src/**/*.module.css
   - "**/components/**/*.{ts,tsx}"
+paths:
+  - src/**/*.tsx
+  - src/**/*.css
+  - src/**/*.module.css
+  - "**/components/**/*.{ts,tsx}"
 tier: wave-only
 ---
+<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/frontend.md) -->
 # Frontend Rules (Path-scoped)
 
 ## React & Next.js
@@ -95,4 +100,4 @@ tier: wave-only
 - No arbitrary z-index (`z-index: 999 / 9999`). Build a semantic z-index scale (dropdown → sticky → modal → toast → tooltip); never magic numbers.
 
 ## See Also
-development.md · security.md · security-web.md · testing.md · backend.md · backend-data.md · mvp-scope.md · parallel-sessions.md
+security-web.md · backend.md · backend-data.md · parallel-sessions.md

package/rules/opt-in-stack/security-web.md

@@ -1,4 +1,3 @@
-<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/security-web.md) -->
 ---
 globs:
   - src/middleware*.ts
@@ -6,8 +5,15 @@ globs:
   - next.config.*
   - src/lib/csp*
   - src/lib/cors*
+paths:
+  - src/middleware*.ts
+  - src/app/**
+  - next.config.*
+  - src/lib/csp*
+  - src/lib/cors*
 tier: wave-only
 ---
+<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/security-web.md) -->
 
 # Security — Web & API (Path-scoped)
 
@@ -67,7 +73,7 @@ CSRF, rate limiting, CSP, and transport security. Core security rules are in `se
 
 #### SEC-011: CSP single-source enforcement
 - Advisory rules are silent when they regress. Wire the single-source rule into a mechanical check so duplicates fail fast.
-- Canonical hook: `templates/shared/hooks/check-csp-single-source.sh`. Greps all TS/JS under the given paths for `Content-Security-Policy`, filters to `proxy.ts` / `middleware.ts` / `next.config.*`, fails if more than one file matches.
+- Canonical hook: `templates/shared/hooks/check-csp-single-source.sh`. Greps all TS/JS under the given paths for `Content-Security-Policy`, filters to `proxy.ts` / `middleware.ts` / `next.config.*`, fails if more than one file matches. <!-- path-check: example -->
 - **Wire into pre-push (Husky):**
   ```json
   // package.json
@@ -77,7 +83,7 @@ CSRF, rate limiting, CSP, and transport security. Core security rules are in `se
   # .husky/pre-push
   pnpm run hook:check-csp
   ```
-- **Wire into CI security stage:** copy the `check-csp-single-source` job from `templates/shared/hooks/README.md` into `.gitlab-ci.yml`. Runs on every merge request.
+- **Wire into CI security stage:** copy the `check-csp-single-source` job from `templates/shared/hooks/README.md` into `.gitlab-ci.yml`. Runs on every merge request. <!-- path-check: example -->
 - Exit codes: `0` pass, `1` duplicate CSP source (SEC-011 violation), `2` tool error.
 - Why: browsers receiving two `Content-Security-Policy` headers take the intersection — nonces and `strict-dynamic` break silently. Humans miss this in review; a grep doesn't.
 
@@ -191,4 +197,4 @@ securityMiddleware(app);
 - **Template Literals**: Never use tagged template literals with user input for SQL, HTML, or shell commands. Use parameterized queries, DOMPurify, or `child_process.execFile()` respectively.
 
 ## See Also
-development.md · security.md · testing.md · frontend.md · backend.md · backend-data.md · swift.md · mvp-scope.md · cli-design.md · parallel-sessions.md
+frontend.md · backend.md · backend-data.md · swift.md · parallel-sessions.md

package/rules/opt-in-stack/swift.md

@@ -1,11 +1,15 @@
-<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/swift.md) -->
 ---
 globs:
   - "**/*.swift"
   - "**/Package.swift"
   - "**/*.xcodeproj/**"
+paths:
+  - "**/*.swift"
+  - "**/Package.swift"
+  - "**/*.xcodeproj/**"
 tier: wave-only
 ---
+<!-- source: session-orchestrator plugin (canonical: rules/opt-in-stack/swift.md) -->
 # Swift Rules (Path-scoped)
 
 ## Language & Style
@@ -62,4 +66,4 @@ tier: wave-only
 - Validate all server-sent data with Codable schemas. Never `force-unwrap` optional JSON fields.
 
 ## See Also
-development.md · security.md · testing.md · frontend.md · backend.md · mvp-scope.md · parallel-sessions.md
+frontend.md · backend.md · parallel-sessions.md