session-orchestrator 3.16.0

package/skills/test-runner/rubric-v1.md

@@ -0,0 +1,388 @@
+# UX Rubric v1
+
+> Readable specification of the 4 UX checks applied by the `ux-evaluator` agent.
+> Stable spec — v2 will live as a sibling `rubric-v2.md` in this same directory.
+> The `findings.jsonl` metadata record carries `rubric_version: "v1"` so consumers
+> can distinguish evaluations run against different rubric revisions.
+
+---
+
+## Findings JSON schema (per finding)
+
+Each finding in `findings.jsonl` is a JSON object on its own line (NDJSON). The
+first line of the file is a metadata record (`"_meta": true`). All subsequent
+lines conform to this schema:
+
+```json
+{
+  "run_id":           "<string — test-runner run identifier, e.g. '12345-1715688000123'>",
+  "rubric_version":   "v1",
+  "severity":         "<'critical' | 'high' | 'medium' | 'low'>",
+  "check":            "<'onboarding-step-count' | 'axe-violations' | 'console-errors' | 'liquid-glass-conformance'>",
+  "fingerprint":      "<16-hex-char string — see Fingerprint formula below>",
+  "evidence_path":    "<relative path from run-dir root to the supporting artifact>",
+  "suggested_priority": "<'critical' | 'high' | 'medium' | 'low' — same as severity for v1>",
+  "scope":            "<short label: 'onboarding' | 'a11y' | 'console' | 'liquid-glass'>",
+  "checkId":          "<check identifier used as fingerprint input — see per-check section>",
+  "locator":          "<DOM selector, AX path, entry URL, or screen.frame identifier>",
+  "title":            "<one-sentence summary of the violation>",
+  "description":      "<2–4 sentence explanation including evidence reference and rubric citation>",
+  "recommendation":   "<actionable next step specific enough to act on without re-reading the finding>"
+}
+```
+
+**Invariants:**
+- `fingerprint` is unique within a single run (collisions are logged, only first occurrence emitted).
+- `evidence_path` must point to an artifact that exists in the run directory at evaluation time.
+- `severity` and `suggested_priority` are lowercase in the JSON record (uppercase only in human-readable stdout tables).
+- No field may be `null` or absent. Use `""` for fields where the value is genuinely unavailable, and explain in `description`.
+
+**Metadata record (first line of `findings.jsonl`):**
+
+```json
+{
+  "_meta": true,
+  "rubric_version": "v1",
+  "run_id": "<run-id>",
+  "evaluated_at": "<ISO-8601-UTC timestamp>",
+  "checks_applied": 4,
+  "findings_count": <integer>,
+  "collisions": <integer — normally 0>
+}
+```
+
+---
+
+## Fingerprint formula
+
+```javascript
+fingerprint = sha256(`${scope}\n${checkId}\n${locator}`).slice(0, 16)
+```
+
+**Inputs** (joined with `\n` newline separator):
+
+| Input | Description |
+|---|---|
+| `scope` | Short namespace label — `'onboarding'`, `'a11y'`, `'console'`, `'liquid-glass'` |
+| `checkId` | Check-specific identifier — see each check section for the exact value |
+| `locator` | Stable DOM selector, AX path, entry URL, or screen.frame string |
+
+**Design rationale for `\n` separator:** Newlines are forbidden in shell argument
+boundaries by the `ARG_BOUNDARY_DANGEROUS` pattern (`/[\n\r\0]/`) established in
+`scripts/lib/autopilot/mr-draft.mjs`. Using `\n` as the separator means it can never
+appear within a locator string that passed validation, so the concatenated input is
+collision-free by construction.
+
+**Implementation:** `scripts/lib/test-runner/fingerprint.mjs` exports
+`fingerprintFinding({scope, checkId, locator})`. The function uses Node.js
+`crypto.createHash('sha256')` (no external dependencies) and returns the first 16
+hex characters of the digest (64 bits of collision resistance — sufficient for the
+expected finding volume of < 10 000 per run).
+
+**Truncation rule for long locators:** Locators longer than 256 characters are
+truncated to their first 256 characters before fingerprinting. This is consistent
+with the `ux-evaluator` agent's description field convention. Both the evaluator
+and the fingerprint module must apply truncation to guarantee matching fingerprints.
+
+**Stability guarantee:** Given identical `(scope, checkId, locator)` inputs, the
+fingerprint is identical across any two evaluation runs, regardless of timestamp,
+run-id, or system state. Never include runtime-varying values in fingerprint inputs.
+
+---
+
+## Check 1: onboarding-step-count
+
+**Purpose:** Count distinct onboarding or wizard steps reachable from the flow's
+entry point. Flag when the step count exceeds 7.
+
+**Why 7:** The "7 ± 2" rule (Miller, 1956) characterises the capacity of short-term
+working memory. Onboarding flows that require users to hold more than 7 steps in
+mind reliably correlate with drop-off. A typical mobile app's V3.3 release shipped a
+10-step onboarding flow with no E2E coverage; user-completion rate dropped significantly.
+This rubric was inspired by that incident and is cited in project PRDs as the canonical
+example for onboarding quality gates.
+
+**Severity mapping:**
+
+| Step count | Severity |
+|---|---|
+| ≤ 7 | No finding |
+| 8–9 | HIGH |
+| ≥ 10 | CRITICAL |
+
+**What counts as a step:** A distinct page, screen, or wizard panel the user must
+navigate through sequentially to complete onboarding. A "confirm" dialog on top of
+a step does not count as a separate step. A branch path (e.g., "optional profile
+setup") counts only if the user cannot skip it.
+
+**Evidence required:**
+- AX-tree snapshot with each step's primary heading text and a screenshot per step
+  (both written by test fixtures in the target repo to `<run-dir>/ax-snapshots/` and
+  `<run-dir>/screenshots/` — runner.mjs pre-creates these directories but does not
+  emit the content).
+- The test fixtures must have navigated through the full onboarding sequence and
+  captured an AX snapshot at each step transition. If the fixtures did not cover the
+  full flow, the evaluator logs a warning and emits no finding (evidence requirement
+  is not met).
+
+**Fingerprint inputs:**
+- `scope = 'onboarding'`
+- `checkId = 'step-count-over-7'`
+- `locator = <entry-route-URL-for-web | entry-screen-name-for-macOS>`
+
+**Example finding (HIGH):**
+
+```json
+{
+  "run_id": "42-1715700000000",
+  "rubric_version": "v1",
+  "severity": "high",
+  "check": "onboarding-step-count",
+  "fingerprint": "a3f1c8e72d904b1a",
+  "evidence_path": "screenshots/onboarding-step-8.png",
+  "suggested_priority": "high",
+  "scope": "onboarding",
+  "checkId": "step-count-over-7",
+  "locator": "/onboarding/start",
+  "title": "Onboarding flow has 9 steps (limit: 7)",
+  "description": "The onboarding sequence starting at /onboarding/start requires the user to complete 9 distinct steps before reaching the dashboard. Steps 8 and 9 are a 'verify email' confirmation screen and a 'set notification preferences' screen. The 7-step limit is defined in rubric-v1 Check 1 based on Miller's short-term memory model.",
+  "recommendation": "Merge 'verify email' into the account-creation step (step 2) or defer 'notification preferences' to a post-onboarding nudge. Target ≤7 steps in the critical path."
+}
+```
+
+---
+
+## Check 2: axe-violations (critical + serious)
+
+**Purpose:** Read axe-core JSON output captured by the Playwright driver and flag
+every accessibility violation tagged `critical` or `serious` by axe-core's impact
+rating. Lower severity levels (`moderate`, `minor`) are out of scope for v1 — they
+belong in a separate `/discovery` pass or a future `rubric-v2.md` extension.
+
+**Why axe critical/serious only:** WCAG AA conformance requires that critical and
+serious violations be eliminated before launch. Moderate and minor violations are
+important but rarely block release; including them in v1 would produce too much noise
+for the reconcile pipeline's per-finding issue creation to handle economically.
+
+**Severity mapping:**
+
+| axe-core impact | Finding severity |
+|---|---|
+| `'critical'` | CRITICAL |
+| `'serious'` | HIGH |
+| `'moderate'` | (not a finding in v1) |
+| `'minor'` | (not a finding in v1) |
+
+**Artifact location:** `<run-dir>/ax-snapshots/axe-*.json`
+(written by test fixture using `@axe-core/playwright`; runner.mjs pre-creates the
+`ax-snapshots/` directory but does NOT write these files — axe-core SOFT-SKIPs
+if `@axe-core/playwright` is absent from the target repo)
+
+Each file is a JSON array of axe-core `Result` objects. The evaluator iterates every
+result entry in every snapshot file and emits one finding per unique
+`(ruleId, nodes[0].target)` pair that is `critical` or `serious`.
+
+**Evidence required:**
+- The verbatim axe-core `Result` object embedded in the finding's `description` field
+  (JSON-stringified, or as a structured sub-object if the reconcile pipeline supports it).
+- The screenshot file from the same route, if present (referenced in `evidence_path`).
+
+**Fingerprint inputs:**
+- `scope = 'a11y'`
+- `checkId = 'axe-' + ruleId` (e.g., `'axe-color-contrast'`, `'axe-image-alt'`)
+- `locator = nodes[0].target` — the CSS selector array joined with ` > ` if it is
+  a nested selector, or the first string element if it is already a string
+
+**Example finding (CRITICAL):**
+
+```json
+{
+  "run_id": "42-1715700000000",
+  "rubric_version": "v1",
+  "severity": "critical",
+  "check": "axe-violations",
+  "fingerprint": "b9d2041ef3a77c50",
+  "evidence_path": "ax-snapshots/axe-dashboard-2025-05-14T14-00-00.json",
+  "suggested_priority": "critical",
+  "scope": "a11y",
+  "checkId": "axe-button-name",
+  "locator": "#submit-btn",
+  "title": "axe-core critical: button-name — submit button has no accessible name",
+  "description": "axe-core reports a critical violation of the 'button-name' rule on selector '#submit-btn' (dashboard route, snapshot axe-dashboard-2025-05-14T14-00-00.json). The button has no visible text, aria-label, or aria-labelledby. This violates WCAG 2.1 Success Criterion 4.1.2 (Name, Role, Value). Users relying on screen readers cannot identify or activate this control.",
+  "recommendation": "Add aria-label='Submit' or visible button text to the '#submit-btn' element. Verify with a screen reader (VoiceOver or NVDA) after fix."
+}
+```
+
+---
+
+## Check 3: console-errors
+
+**Purpose:** Read the browser or application console output captured by the driver
+and flag error-level messages that are visible to end users — uncaught exceptions,
+unhandled promise rejections, and network errors surfaced in the UI.
+
+**Why console errors matter:** TypeScript compile checks and lint catch static
+errors; axe-core catches accessibility violations; but runtime errors only surface
+during actual execution. A JavaScript exception that crashes a component or a 404
+that silently removes a UI section degrades user trust and is the class of bug most
+likely to slip through until a real user reports it.
+
+**What is an error-level message (flag these):**
+- Lines prefixed with `ERROR`, `UNCAUGHT`, `Unhandled`, `TypeError`, `ReferenceError`
+- HTTP 4xx or 5xx responses logged to the console (e.g., `Failed to load resource: the server responded with a status of 404`)
+- Unhandled Promise rejections (text contains `UnhandledPromiseRejection` or `UnhandledRejection`)
+
+**What is developer-tooling noise (do NOT flag):**
+- React or Vue hydration mismatch hints (often informational in dev mode)
+- Hot Module Replacement (HMR) status messages
+- Browser extension warnings (`[extension]`, `chrome-extension://`)
+- `[Violation]` warnings from Chrome about long tasks (performance, not UX-blocking)
+- Source map warnings
+
+**Severity mapping:**
+
+| Error class | Severity |
+|---|---|
+| Uncaught exception / unhandled rejection | HIGH |
+| Visible HTTP 4xx/5xx (resource load failure in UI) | MEDIUM |
+
+**Artifact location:** `<run-dir>/console.log` — runner.mjs appends raw Playwright
+process stdout/stderr to this file; structured NDJSON `{ts, type, text, location}`
+entries are fixture-emitted via `page.on('console', ...)` and are what the evaluator
+parses. Each line has the shape:
+`{"ts":<epoch-ms>,"type":"error"|"warning"|...,"text":"<message>","location":{...}}`.
+The evaluator parses each line as JSON and inspects the `type` and `text` fields.
+If the file is absent, skip check 3.
+
+**Fingerprint inputs:**
+- `scope = 'console'`
+- `checkId = 'error-' + msgClass` where `msgClass` is the normalized error class:
+  - `'uncaught-exception'` for TypeError/ReferenceError/UnhandledRejection
+  - `'http-4xx'` or `'http-5xx'` for network errors
+- `locator = <origin-URL-if-present | file:line-if-stack-frame-available | 'unknown'>`
+
+**Example finding (HIGH):**
+
+```json
+{
+  "run_id": "42-1715700000000",
+  "rubric_version": "v1",
+  "severity": "high",
+  "check": "console-errors",
+  "fingerprint": "c7a140b8fe291d63",
+  "evidence_path": "console.log",
+  "suggested_priority": "high",
+  "scope": "console",
+  "checkId": "error-uncaught-exception",
+  "locator": "src/components/InvoiceTable.tsx:87",
+  "title": "Uncaught TypeError: Cannot read property 'id' of undefined",
+  "description": "The browser console captured an uncaught TypeError at InvoiceTable.tsx:87 during the dashboard flow. The error fires when the invoices array contains a null entry, causing the component to crash. This is a runtime error that is not caught by any existing test and is directly visible to the user via a blank component area.",
+  "recommendation": "Add a null guard before accessing .id in the map callback at InvoiceTable.tsx:87. Also add a test case that renders InvoiceTable with a null entry in the invoices prop."
+}
+```
+
+---
+
+## Check 4: liquid-glass-conformance
+
+**Purpose:** For SwiftUI targets where `Package.swift` declares iOS 26+ or macOS
+Tahoe (26+), verify that UI surfaces using translucent or blurred backgrounds apply
+Apple's Liquid Glass API (`.glassEffect()`) rather than legacy `.background(.thinMaterial)`
+or custom `.blur(radius:)` modifiers.
+
+**Why Liquid Glass:** Apple Liquid Glass was introduced at WWDC 2025 and is the
+canonical platform baseline for translucent surfaces in SwiftUI 26+. Apps that
+continue using legacy material modifiers on iOS 26+ / macOS Tahoe risk visual
+inconsistency with system UI, rejection in App Store review for "non-standard
+appearance", and future deprecation of the legacy API. PRD §1.2 names this check
+as the secondary motivation for the UX rubric alongside accessibility compliance.
+
+**Applicability condition:** This check is only executed when both conditions hold:
+1. `Package.swift` exists in the repository root (or nearest ancestor).
+2. `Package.swift` declares `.iOS("26")` or higher, OR `.macOS("26")` or higher,
+   in its `platforms: [...]` array.
+
+If neither condition is met, skip check 4 and note the skip in the stdout summary.
+This is the expected behavior for pure web projects and Swift projects targeting
+earlier OS versions.
+
+**What to flag:** Screens or frames where the AX-tree dump or screenshot metadata
+indicates a translucent/blurred background that uses:
+- `.background(.thinMaterial)` or `.background(.ultraThinMaterial)` etc.
+- `.background(Material.*)` (any Material enum case)
+- A `.blur(radius:)` modifier applied to a container as a background effect
+
+**What is compliant (do NOT flag):**
+- `.glassEffect()` — correct Liquid Glass API
+- `.glassEffect(.regular)` / `.glassEffect(.prominent)` — parametrised Liquid Glass
+- Solid color backgrounds (no blur) — these are not Liquid Glass candidates
+- Explicitly documented exceptions in `docs/apple-hig-exceptions.md`
+
+**Severity mapping:**
+
+| Condition | Severity |
+|---|---|
+| Non-compliant surface, no documented exception | MEDIUM |
+| Non-compliant surface, documented exception in `docs/apple-hig-exceptions.md` | LOW |
+
+**Evidence required:**
+- Peekaboo screenshot of the non-compliant surface (referenced in `evidence_path`).
+- The AX-path or frame identifier (referenced in `locator`).
+
+> **Note (v1):** peekaboo-driver may emit `ax-snapshots/glass-modifiers-*.json` artifacts carrying `schema_version: v1, status: stub` for forward compatibility. The v1 rubric does NOT read these — Check 4 operates from screenshots + AX dump annotations only. Future ux-evaluator versions may consume the JSON to classify frames directly.
+
+**Fingerprint inputs:**
+- `scope = 'liquid-glass'`
+- `checkId = 'missing-glassEffect'`
+- `locator = <screen-name>.<frame-id>` (e.g., `'DashboardScreen.headerBlurFrame'`)
+
+**Example finding (MEDIUM):**
+
+```json
+{
+  "run_id": "42-1715700000000",
+  "rubric_version": "v1",
+  "severity": "medium",
+  "check": "liquid-glass-conformance",
+  "fingerprint": "d4e9f2a63c518b07",
+  "evidence_path": "screenshots/DashboardScreen-headerBlurFrame.png",
+  "suggested_priority": "medium",
+  "scope": "liquid-glass",
+  "checkId": "missing-glassEffect",
+  "locator": "DashboardScreen.headerBlurFrame",
+  "title": "Legacy .background(.thinMaterial) on DashboardScreen header — should use .glassEffect()",
+  "description": "The DashboardScreen header frame (DashboardScreen.headerBlurFrame) uses .background(.thinMaterial) for its translucent background. The project targets macOS 26+, where .glassEffect() is the canonical Liquid Glass API (WWDC25). Using the legacy Material modifier produces a subtly different visual output and may trigger App Store review flags on macOS Tahoe.",
+  "recommendation": "Replace .background(.thinMaterial) with .glassEffect() on the header container in DashboardScreen.swift. If the legacy appearance is intentional for this surface, document the exception in docs/apple-hig-exceptions.md to suppress this finding."
+}
+```
+
+---
+
+## Out-of-scope (v1)
+
+The following concern areas are deliberately excluded from v1. They may be addressed
+in a future `rubric-v2.md` or a separate evaluation skill.
+
+- **Visual-diff / pixel regression.** Pixel-level before/after comparison requires
+  a baseline screenshot corpus and a diff algorithm. This is a separate driver
+  capability not yet available in test-runner v1.
+
+- **Performance metrics (LCP, FCP, CLS, INP).** Core Web Vitals and layout shift
+  metrics require instrumentation beyond the Playwright AX + screenshot capture
+  available in test-runner v1. These belong in a dedicated performance rubric.
+
+- **Cross-platform Windows / Linux targets.** The liquid-glass check is macOS/iOS
+  specific. Windows and Linux desktop targets are out of scope for all 4 checks
+  in v1. Web targets are in scope for checks 1, 2, and 3.
+
+- **Mobile (iOS / Android) native targets.** Playwright does not cover native mobile;
+  XCUITest or Appium integration is deferred to a future driver.
+
+- **Stagehand v3 / Browserbase cloud probes.** Cloud-based headless browser pools
+  introduce network latency and session management complexity. v1 is scoped to
+  local Playwright runs only.
+
+- **Automated recommendation generation via LLM.** The `recommendation` field is
+  written by the `ux-evaluator` agent (an LLM). LLM-generated recommendations are
+  advisory — they are not automatically filed as code changes. A human or a
+  `code-implementer` agent must review and apply them.

package/skills/test-runner/soul.md

@@ -0,0 +1,46 @@
+# Test Runner — Soul
+
+## Identity
+
+You are the test-runner — an agentic end-to-end test orchestrator. You wire drivers, dispatch the evaluator, reconcile findings, and write the roll-up. You do NOT execute tests yourself. You do NOT judge UX quality directly — that is the `ux-evaluator` agent's job. You do NOT call glab or gh directly — that is `issue-reconcile.mjs`'s job.
+
+You exist to wire upstream tools together with discipline: token-frugal artifact storage, fingerprint-based dedup, severity-driven routing.
+
+## Principles
+
+### Token-frugal
+Every AX dump and screenshot goes to disk under `${RUN_DIR}`. The coordinator context stays small. If a tool outputs 10,000 bytes of AX tree, it belongs in a file, not in your prompt.
+
+### Idempotent
+Re-running against the same DOM produces the same fingerprints. The dedup set prevents duplicate issues regardless of how many times the orchestrator runs. Build the fingerprint set before reconciling — always.
+
+### Composable
+Each phase has a clean boundary:
+- Phase 2 → drivers write to disk
+- Phase 3 → evaluator reads from disk, writes `findings.jsonl`
+- Phase 4 → reconciler reads `findings.jsonl`, writes to issue tracker
+- Phase 5 → reporter reads everything, writes `report.md` + JSONL roll-up
+
+No phase reaches across another's boundary.
+
+### Wrap-not-fork
+Playwright and Peekaboo stay on their mainlines. The test-runner's value is orchestration — not reimplementing driver logic. Dispatch via the wrapper skills; do not duplicate their contracts inline.
+
+## Decision-Making
+
+When a driver exits non-zero, continue — test failures are findings, not orchestrator failures.
+
+When `findings.jsonl` is missing after evaluator dispatch, warn and skip reconciliation — do not fail the run.
+
+When glab query fails for fingerprint dedup, proceed with an empty set and log the error. Creating a duplicate issue is safer than silently skipping a real finding.
+
+When severity is `critical` or `high`, auto-create without AUQ — these require no user gate. When severity is `medium` or `low`, present via AUQ and respect the user's triage decision.
+
+## What You Are NOT
+
+- Not a tester — you orchestrate test execution, you do not write or run tests
+- Not a UX evaluator — that is `agents/ux-evaluator.md`'s role
+- Not a Playwright driver — that is `skills/playwright-driver/SKILL.md`'s role
+- Not a Peekaboo driver — that will be `skills/peekaboo-driver/SKILL.md` once #381 lands
+- Not an issue tracker — you reconcile findings via `scripts/lib/test-runner/issue-reconcile.mjs`
+- Not a `@playwright/mcp` user — R5 hard-gate, 4× token cost, never bypass

package/skills/tmux-layout/SKILL.md

@@ -0,0 +1,104 @@
+---
+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".
+model: inherit
+color: cyan
+tools: Read, Bash, Grep, Glob
+---
+
+# tmux-layout — Operator-Side Visualization Substrate
+
+> Status: PROPOSED per ADR-0007 (`docs/adr/0007-tmux-visualization-substrate.md`). Opt-in skill — NOT default.
+> Project-instruction file resolution: this is `CLAUDE.md` on Claude Code / Cursor IDE; the equivalent on Codex CLI is `AGENTS.md`. See `skills/_shared/instruction-file-resolution.md`.
+
+## Purpose
+
+Render a prepared tmux layout for *operator-side observability* of the session's asynchronous side-channels — STATE.md updates, CI status, events.jsonl wave/gate transitions. NOT a coordinator chat surface, NOT a wave-agent host. The coordinator chat remains in the operator's original terminal, period (per AUQ-001 in `.claude/rules/ask-via-tool.md`).
+
+## When to Use
+
+- During a long deep-session when you want CI status visible alongside Quality-Gate output without polling `glab ci status` manually.
+- During `/debug` Phase 2 hypothesis testing (use `--layout debug`).
+- Anywhere `tail -F .claude/STATE.md` + a CI watcher would speed up your loop.
+
+## When NOT to Use
+
+- For wave-agent visualization — wave agents are in-process `Agent()` calls; no PID, no TTY, no pane to attach.
+- For autopilot multi-story panes — autopilot.jsonl currently shows 11 entries / 8 dry-runs; below the value threshold for a pane-per-story UI.
+- As your coordinator chat surface — that stays in the terminal where you invoked /tmux-layout.
+
+## Usage
+
+```
+/tmux-layout                        # default layout (4 panes)
+/tmux-layout --layout debug         # debug layout (4 panes, /debug companion)
+/tmux-layout --json                 # machine-readable output (no attach)
+/tmux-layout --session-name my-ws   # custom tmux session name
+/tmux-layout --force                # replace existing session (PSA-003 escape hatch)
+/tmux-layout --with-status-pane     # add a 5th pane tailing agent-status telemetry (#565)
+/tmux-layout --help                 # full CLI usage
+```
+
+The skill prints a one-line tmux command. Paste it into a SECOND terminal (do not run it where /tmux-layout was invoked). That second terminal becomes the layout. Your original terminal (the coordinator chat) stays where it is.
+
+## Default Layout (4 panes; 5 with `--with-status-pane`)
+
+| Pane | Content | Command |
+|---|---|---|
+| 1 | **Shell** (operator scratch — NOT claude) | `bash` (interactive) |
+| 2 | STATE.md tail | `tail -F <state-dir>/STATE.md` |
+| 3 | CI watch (poll-loop wrapper) | `while true; do clear; glab ci status --pipeline-id LATEST --output json \| jq ...; sleep 15; done` |
+| 4 | events.jsonl wave/gate filter | `tail -F .orchestrator/metrics/events.jsonl \| jq --unbuffered 'select(.event \| test("wave\|gate\|spiral"))'` |
+| 5 | agent-status telemetry (#565, only with `--with-status-pane`) | `while true; do clear; jq . .orchestrator/runtime/agent-status-current.json 2>/dev/null \|\| echo ...; sleep 2; done` |
+
+`<state-dir>` is resolved via `resolveStateDir()` from `scripts/lib/platform.mjs` (`.claude/`, `.codex/`, or `.cursor/`).
+Pane 3 command is vcs-aware (`glab` for gitlab, `gh pr checks` for github, informational `echo` fallback when no CLI).
+
+## Debug Layout (4 panes — `--layout debug`, depends-on #562)
+
+| Pane | Content | Command |
+|---|---|---|
+| 1 | **Shell** (operator scratch) | `bash` (interactive) |
+| 2 | Hypothesis-test runner | `npm test -- --watch <scope>` (or per-skill-config) |
+| 3 | Debug-artifact tail | `tail -F .orchestrator/debug/*.md` |
+| 4 | Diff-watch | `watch -n 2 'git diff --stat \| head -30'` |
+
+## Architecture
+
+Three sibling modules under `scripts/lib/tmux-layout/`:
+
+- `layouts.mjs` — `renderDefaultLayout()`, `renderDebugLayout()`, `detectVcsCommand()`.
+- `vcs-detector.mjs` — `detectVcsCommand({config, projectRoot})` returns `{bin, args, fallback, blocking}` per vcs key.
+- `tmux-shell.mjs` — `detectTmuxVersion()`, session-collision policy helpers.
+
+Entry point: `scripts/tmux-layout.mjs` (parseArgs from `node:util`, dispatcher to layout functions).
+
+## PSA-003 Compliance
+
+Session-collision policy: **refuse + `--force`**. The skill NEVER kills, overwrites, or modifies a tmux session it did not create unless the operator passes `--force` explicitly. See `.claude/rules/parallel-sessions.md` § PSA-003.
+
+## AUQ-001 Compliance
+
+The coordinator chat (where AskUserQuestion fires) stays in the operator's ORIGINAL terminal. Pane 1 of the tmux layout is intentionally a scratch shell, NOT a new `claude` session — there is no second AUQ surface, no decision-authority split. See `.claude/rules/ask-via-tool.md` § AUQ-001.
+
+## Telemetry & Promotion Gate (#563)
+
+This skill emits structured events to `.orchestrator/metrics/events.jsonl`:
+- `tmux-layout.invoked`
+- `tmux-layout.degraded` (tmux missing, version too old, session collision without --force, etc.)
+- `tmux-layout.completed` (when the user closes the tmux session)
+
+Promotion criteria from opt-in skill to default-recommended in session-start banner: invocation count ≥ 5 across ≥ 3 distinct deep sessions over ≥ 2 calendar weeks, layout-completion rate ≥ 80%, zero AUQ-001 / PSA-003 regressions. See ADR-0007 § Follow-ups.
+
+## Troubleshooting
+
+- **tmux not found** → install: `brew install tmux` (macOS) / `apt install tmux` (Linux). Minimum tmux ≥ 3.0.
+- **Session already exists** → use `--force` (acknowledges PSA-003) or `--session-name my-other`.
+- **CI pane shows nothing** → `glab` or `gh` not installed, or `vcs:` not set in `## Session Config`. Pane will show a clear fallback message.
+
+## See Also
+
+- `docs/adr/0007-tmux-visualization-substrate.md` — design rationale.
+- `skills/_shared/monitor-patterns.md` — comparison: tmux-layout vs Monitor vs /loop.
+- `skills/debug/SKILL.md` — Phase 2 hypothesis testing (use `--layout debug` as companion).
+- GitLab #561 #562 #563.

package/skills/ubiquitous-language/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: ubiquitous-language
+description: Use when the user wants to define domain terms, build a glossary, harden terminology, create a ubiquitous language, or mentions "domain model" or "DDD". Extracts a DDD-style glossary from the current conversation into UBIQUITOUS_LANGUAGE.md, flags ambiguities and synonyms, and proposes opinionated canonical terms.
+model: inherit
+disable-model-invocation: true
+derived-from: mattpocock/skills@90ea8ee
+license: MIT
+upstream-url: https://github.com/mattpocock/skills/tree/main/ubiquitous-language
+---
+
+# Ubiquitous Language
+
+Extract and formalize domain terminology from the current conversation into a consistent glossary, saved to a local file.
+
+## Process
+
+1. **Scan the conversation** for domain-relevant nouns, verbs, and concepts
+2. **Identify problems**:
+   - Same word used for different concepts (ambiguity)
+   - Different words used for the same concept (synonyms)
+   - Vague or overloaded terms
+3. **Propose a canonical glossary** with opinionated term choices
+4. **Write to `UBIQUITOUS_LANGUAGE.md`** in the working directory using the format below
+5. **Output a summary** inline in the conversation
+
+## Output Format
+
+Write a `UBIQUITOUS_LANGUAGE.md` file with this structure:
+
+```md
+# Ubiquitous Language
+
+## Order lifecycle
+
+| Term        | Definition                                              | Aliases to avoid      |
+| ----------- | ------------------------------------------------------- | --------------------- |
+| **Order**   | A customer's request to purchase one or more items      | Purchase, transaction |
+| **Invoice** | A request for payment sent to a customer after delivery | Bill, payment request |
+
+## People
+
+| Term         | Definition                                  | Aliases to avoid       |
+| ------------ | ------------------------------------------- | ---------------------- |
+| **Customer** | A person or organization that places orders | Client, buyer, account |
+| **User**     | An authentication identity in the system    | Login, account         |
+
+## Relationships
+
+- An **Invoice** belongs to exactly one **Customer**
+- An **Order** produces one or more **Invoices**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed. A single **Order** can produce multiple **Invoices** if items ship in separate **Shipments**."
+> **Dev:** "So if a **Shipment** is cancelled before dispatch, no **Invoice** exists for it?"
+> **Domain expert:** "Exactly. The **Invoice** lifecycle is tied to the **Fulfillment**, not the **Order**."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — these are distinct concepts: a **Customer** places orders, while a **User** is an authentication identity that may or may not represent a **Customer**.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously in the conversation, call it out in the "Flagged ambiguities" section with a clear recommendation.
+- **Only include terms relevant for domain experts.** Skip the names of modules or classes unless they have meaning in the domain language.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include domain terms.** Skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning.
+- **Group terms into multiple tables** when natural clusters emerge (e.g. by subdomain, lifecycle, or actor). Each group gets its own heading and table. If all terms belong to a single cohesive domain, one table is fine — don't force groupings.
+- **Write an example dialogue.** A short conversation (3-5 exchanges) between a dev and a domain expert that demonstrates how the terms interact naturally. The dialogue should clarify boundaries between related concepts and show terms being used precisely.
+
+<example>
+
+## Example dialogue
+
+> **Dev:** "How do I test the **sync service** without Docker?"
+
+> **Domain expert:** "Provide the **filesystem layer** instead of the **Docker layer**. It implements the same **Sandbox service** interface but uses a local directory as the **sandbox**."
+
+> **Dev:** "So **sync-in** still creates a **bundle** and unpacks it?"
+
+> **Domain expert:** "Exactly. The **sync service** doesn't know which layer it's talking to. It calls `exec` and `copyIn` — the **filesystem layer** just runs those as local shell commands."
+
+</example>
+
+## Re-running
+
+When invoked again in the same conversation:
+
+1. Read the existing `UBIQUITOUS_LANGUAGE.md`
+2. Incorporate any new terms from subsequent discussion
+3. Update definitions if understanding has evolved
+4. Re-flag any new ambiguities
+5. Rewrite the example dialogue to incorporate new terms