session-orchestrator 3.16.0

package/skills/domain-model/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: domain-model
+description: Use when the user wants to stress-test a plan against the existing domain model and documented decisions. Grilling session that interviews the user one question at a time, sharpens fuzzy terminology inline, updates CONTEXT.md lazily, and offers ADRs sparingly under a 3-criteria gate. Reads docs/adr/ and CONTEXT.md if present.
+model: inherit
+disable-model-invocation: true
+derived-from: mattpocock/skills@90ea8ee
+license: MIT
+upstream-url: https://github.com/mattpocock/skills/tree/main/domain-model
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+## Domain awareness
+
+During codebase exploration, also look for existing documentation:
+
+### File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+## During the session
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+Don't couple `CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

package/skills/ecosystem-health/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: ecosystem-health
+user-invocable: false
+tags: [reference, health, monitoring, ci, endpoints]
+model: haiku
+model-preference: sonnet
+model-preference-codex: gpt-5.4-mini
+model-preference-cursor: claude-sonnet-4-6
+description: >
+  Monitor health across configured service endpoints, CI pipelines, and critical
+  issues. Automatically invoked during session-start when ecosystem-health is
+  enabled in Session Config.
+---
+
+# Ecosystem Health Check
+
+## Platform-native (CC 2.1.105+)
+
+This skill's watcher is registered as a plugin monitor via `.claude-plugin/plugin.json`'s `experimental.monitors` reference to `monitors/monitors.json`. Each session that loads this plugin auto-starts the watcher in the background (see `scripts/lib/ecosystem-health.mjs`). Each NDJSON stdout line from the watcher becomes a `<task_notification>` event Claude sees mid-session.
+
+For harness < 2.1.105 (no monitor support), the skill's manual probes documented below serve as the fallback path.
+
+## Session Config Fields Used
+
+This skill reads from the project's `## Session Config` section in the platform instruction file:
+
+- **`health-endpoints`** — list of `{name, url}` objects for service health checks
+- **`cross-repos`** — list of related repositories for critical issue scanning
+
+Both fields are optional. The skill degrades gracefully when either is missing. On Codex this means `AGENTS.md`; on Claude/Cursor it means `CLAUDE.md`.
+
+## Service Health
+
+Read the `health-endpoints` field from Session Config. If not configured or empty, print:
+
+> No health endpoints configured in Session Config. Add `health-endpoints` to enable service monitoring.
+
+and skip this section.
+
+Otherwise, for each configured endpoint, run a health check:
+
+```bash
+# Example health-endpoints config:
+#   health-endpoints:
+#     - name: API
+#       url: https://api.example.com/health
+#     - name: Worker
+#       url: http://worker:8080/healthz
+#     - name: Dashboard
+#       url: http://localhost:3000/api/health
+
+# For EACH endpoint in health-endpoints, run:
+# NAME=<name> URL=<url>
+curl -s --max-time 6 -w '\nHTTP_STATUS:%{http_code}' "$URL" 2>/dev/null \
+  | python3 -c "
+import sys, json
+raw = sys.stdin.read()
+body, _, status_line = raw.rpartition('\nHTTP_STATUS:')
+http_code = int(status_line.strip() or '0')
+status = None
+try:
+    d = json.loads(body)
+    if isinstance(d, dict) and 'status' in d:
+        bs = str(d['status']).lower()
+        status = 'DEGRADED' if bs == 'degraded' else ('OK' if bs in ('ok', 'healthy', 'up') else 'DOWN')
+except Exception:
+    pass
+if status is None:
+    status = 'OK' if 200 <= http_code < 400 else 'DOWN'
+print(f'\$NAME: {status}')
+" 2>/dev/null || echo "\$NAME: unreachable"
+```
+
+Generate the check commands dynamically from the config — do not hardcode any service names or URLs.
+
+## Critical Issues Across Projects
+
+Read the `cross-repos` field from Session Config. If not configured or empty, print:
+
+> No cross-repos configured in Session Config. Add `cross-repos` to enable cross-project issue scanning.
+
+and skip this section.
+
+### Detect VCS
+
+> **VCS Reference:** Detect the VCS platform per the "VCS Auto-Detection" section of the gitlab-ops skill.
+> Use CLI commands per the "Common CLI Commands" section. For cross-project queries, see "Dynamic Project Resolution."
+
+### For each cross-repo, query critical issues
+
+Using the detected VCS CLI (per gitlab-ops "Common CLI Commands" and "Dynamic Project Resolution" sections):
+
+1. Resolve the project ID or owner/repo slug for each cross-repo
+2. Query open issues with `priority:critical` or `priority:high` labels (limit 5 per repo)
+3. Collect results across all configured repos
+
+## CI Pipeline Status
+
+Query the latest pipeline/workflow runs for the current repo using the detected VCS CLI (per gitlab-ops "Common CLI Commands" section). Report the 3 most recent runs.
+
+## Report Format
+
+Present as a compact health dashboard. Build the table dynamically from whichever endpoints are configured:
+
+```
+## Ecosystem Health
+| Service       | Status            |
+|---------------|-------------------|
+| <name>        | [OK/DEGRADED/DOWN/unreachable]  |
+| ...           | ...               |
+
+Critical issues: [N total across cross-repos]
+CI: [green/red/pending]
+```
+
+If no health endpoints are configured, omit the service table entirely.
+If no cross-repos are configured, omit the critical issues line.
+
+Flag any service that is DOWN or DEGRADED, or any critical issue count > 0 as requiring attention.

package/skills/ecosystem-health/wizard.md

@@ -0,0 +1,193 @@
+---
+name: ecosystem-health-wizard
+user-invocable: false
+tags: [bootstrap, ecosystem-health, wizard, config]
+description: >
+  Wizard prompt spec for /bootstrap --ecosystem-health. Detects CI provider
+  and package manager, prompts for service endpoints, CI pipelines, and
+  critical issue labels, then writes Session Config + policy file.
+---
+
+# Ecosystem-Health Wizard Spec
+
+## Purpose
+
+Populate the fields consumed by `skills/ecosystem-health/SKILL.md` interactively.
+Without this wizard, `health-endpoints`, `cross-repos`, and CI pipeline config in
+Session Config must be hand-written. This wizard detects what it can automatically,
+then asks the user only for values that cannot be inferred.
+
+**Local-only.** No network calls. The wizard reads the filesystem and writes two
+files. The user reviews `git status` and commits manually.
+
+---
+
+## Step 1: Detection
+
+Run silently before prompting.
+
+```bash
+node "$PLUGIN_ROOT/scripts/lib/ecosystem-wizard.mjs" --repo-root "$(pwd)" [--dry-run]
+```
+
+The detection phase reads:
+
+| Signal | Command |
+|---|---|
+| CI provider | `[[ -f .gitlab-ci.yml ]] && echo gitlab` / `[[ -d .github/workflows ]] && echo github` |
+| Package manager | Lockfile probe: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, `package-lock.json` → npm |
+| Available scripts | `node -e "const p=require('./package.json'); console.log(Object.keys(p.scripts||{}).join(','))"` |
+
+Detected values are shown to the user as context before prompting:
+
+```
+Ecosystem-Health Wizard
+Detected: CI=gitlab, package-manager=pnpm
+```
+
+---
+
+## Step 2: Prompt Sequence
+
+Three sequential prompts. Each accepts a blank answer to skip that field.
+
+### Prompt 2a — Health Endpoints
+
+```
+Health endpoints (format "Name|URL", comma-separated, blank to skip):
+> API|https://api.example.com/health, Worker|http://worker:8080/healthz
+```
+
+- Format per entry: `<display-name>|<url>` (pipe separator).
+- Comma-separated for multiple entries.
+- URL must be non-empty when name is provided; malformed entries are skipped with a warning.
+- Produces `health-endpoints` list in Session Config.
+
+### Prompt 2b — CI Pipeline Identifiers
+
+```
+CI pipeline identifiers (format "id" or "id:label", comma-separated, blank to skip):
+> main, deploy-production:Deploy
+```
+
+- Format per entry: `<id>` or `<id>:<display-label>`.
+- For GitLab: branch name or numeric pipeline ID.
+- For GitHub: workflow file name (e.g. `ci.yml`).
+- Produces `pipelines` list in policy file.
+
+### Prompt 2c — Critical Issue Labels
+
+```
+Critical issue labels (comma-separated, e.g. "priority:critical,severity:blocker", blank to skip):
+> priority:critical, severity:blocker
+```
+
+- Raw label strings as they appear in the VCS issue tracker.
+- Produces `criticalIssueLabels` list in policy file.
+
+---
+
+## Step 3: Validation
+
+Before writing, the collected data is shape-validated using the plain-JS
+validator in `scripts/lib/ecosystem-wizard.mjs` (`validateEcosystemPolicy`).
+
+Validation rules (no Zod, no Ajv — plain JS):
+
+- `version` must equal `1`
+- `endpoints[]`: each item must have non-empty `name` and `url` strings
+- `pipelines[]`: each item must have non-empty `id` string
+- `criticalIssueLabels[]`: each item must be a non-empty string
+
+When validation fails, no files are written and the errors are reported.
+
+---
+
+## Step 4: Output
+
+Two files are written (or confirmed skipped if already present):
+
+### 4a — Session Config block in CLAUDE.md (or AGENTS.md)
+
+Appended inside the `## Session Config` section:
+
+```yaml
+ecosystem-health:
+  health-endpoints:
+    - name: API
+      url: https://api.example.com/health
+    - name: Worker
+      url: http://worker:8080/healthz
+  pipelines:
+    - id: main
+    - id: deploy-production # Deploy
+  critical-issue-labels: ["priority:critical", "severity:blocker"]
+```
+
+**Idempotency:** If an `ecosystem-health:` key already exists in Session Config,
+the block is NOT overwritten. The wizard prints "Skipped (already present)" and
+exits 0. Re-run to edit: remove the existing block first, then re-run.
+
+### 4b — `.orchestrator/policy/ecosystem.json`
+
+```json
+{
+  "version": 1,
+  "rationale": "Ecosystem health configuration. Generated by /bootstrap --ecosystem-health.",
+  "endpoints": [
+    { "name": "API", "url": "https://api.example.com/health" }
+  ],
+  "pipelines": [
+    { "id": "main" },
+    { "id": "deploy-production", "label": "Deploy" }
+  ],
+  "criticalIssueLabels": ["priority:critical", "severity:blocker"]
+}
+```
+
+Schema: `.orchestrator/policy/ecosystem.schema.json`.
+
+**Idempotency:** If the file already exists and the JSON contents are identical
+to the proposed write, the file is skipped. If the file exists with different
+contents, it is overwritten (re-run semantics).
+
+---
+
+## Step 5: Report
+
+The wizard prints what it wrote and instructs the user to review before committing:
+
+```
+Ecosystem-Health Wizard complete.
+Written: .orchestrator/policy/ecosystem.json, CLAUDE.md
+Skipped (already present): (none)
+
+Review changes with: git status && git diff
+```
+
+No auto-commit. The user stages and commits manually (or via the session coordinator).
+
+---
+
+## Idempotent Re-Run
+
+The wizard is safe to re-run:
+
+1. If `.orchestrator/policy/ecosystem.json` exists with identical contents → **skipped**.
+2. If `ecosystem-health:` key already exists in Session Config → **skipped**.
+3. If both are present and identical → both skipped, wizard exits 0 with "Nothing to do."
+
+To update configuration: remove `ecosystem-health:` from Session Config and
+delete `.orchestrator/policy/ecosystem.json`, then re-run.
+
+---
+
+## Error Handling
+
+| Condition | Behaviour |
+|---|---|
+| `repoRoot` not provided | Exits with error: `repoRoot is required` |
+| No `CLAUDE.md` or `AGENTS.md` found | Policy file is still written; Session Config skipped with warning |
+| Malformed endpoint entry (missing pipe) | Entry skipped with a warning; remaining entries are processed |
+| Validation failure | No files written; errors reported; exit code 1 |
+| File write failure | `errors[]` entry added; partial success reported |

package/skills/eval/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: eval
+user-invocable: true
+tags: [eval, measurement, quality, meta, standard]
+model: sonnet
+model-preference: sonnet
+model-preference-codex: gpt-5.4-mini
+model-preference-cursor: claude-sonnet-4-6
+args-schema:
+  - flag: --session
+    description: "session_id to evaluate (default: last completed session via the resolution cascade)"
+  - flag: --no-write
+    description: "Evaluate + report without appending to the eval journal (.orchestrator/metrics/eval.jsonl)"
+  - flag: --verify
+    description: "Re-evaluate a stored run-id and diff per-dimension for scoring drift (exit 1 on drift)"
+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-v1 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.
+---
+
+> **Platform Note:** State files use the platform's native directory: `.claude/` (Claude Code), `.codex/` (Codex CLI), or `.cursor/` (Cursor IDE). Shared metrics + the eval journal live in `.orchestrator/metrics/`. See `skills/_shared/platform-tools.md`.
+
+# Eval Skill — Session-Process Evaluation (aiat-llm-eval/1.0)
+
+On-demand, honest measurement of ONE completed orchestrator session against the
+pre-registered **rubric-v1** check set. The deterministic engine
+(`scripts/eval-session.mjs` → `scripts/lib/eval/engine.mjs`) reads only local
+metrics files (`sessions.jsonl` + `events.jsonl`), scores the five deterministic
+dimensions, appends a `session-eval` record to the journal, and optionally
+renders an HTML report. An opt-in LLM judge overlays two advisory dimensions.
+
+The standard this skill implements is [`docs/eval/aiat-llm-eval-v1.md`](../../docs/eval/aiat-llm-eval-v1.md);
+the frozen, content-hashed check set is [`skills/eval/rubric-v1.md`](./rubric-v1.md).
+
+## Posture Contract (load-bearing — read before executing)
+
+- **No global score, by construction.** The record has no overall/total/mean
+  field, and this skill never derives one. Report per-dimension verdicts only.
+- **Never guess.** Missing source data yields `cannot-determine` (a first-class,
+  non-error verdict) with an honest reason — never a fabricated `pass`/`fail`.
+  Do NOT "fill in" a missing KPI or infer a gate result the events do not show.
+- **Deterministic before judge.** The five deterministic dimensions are complete
+  on their own. The judge (Phase 3) is opt-in, ADVISORY, and `uncalibrated` in
+  v1 — never blend a judge verdict into the deterministic tally.
+- **Journal is SSOT; the report is a derived view.** The append-only
+  `.orchestrator/metrics/eval.jsonl` is authoritative. The HTML report is
+  rebuildable from any stored record and is never authoritative over the journal.
+- **`--verify` is the reproducibility proof.** Re-scoring stored source data
+  reproduces the stored dimensions byte-for-byte (exit 0) or reports drift
+  (exit 1). This proves the SCORING replays — NOT that the model is deterministic.
+- **Self-evaluation is labelled as such.** The orchestrator scoring its own
+  session is a self-evaluation, not an independent audit.
+
+---
+
+## Phase 0: Bootstrap Gate
+
+Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is
+CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before
+proceeding. If the gate is OPEN, continue to Phase 1.
+
+<HARD-GATE>
+Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to
+`skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints.
+</HARD-GATE>
+
+---
+
+## Phase 1: Config & Argument Loading
+
+### 1.1 Read Session Config
+
+Read and parse Session Config per `skills/_shared/config-reading.md`. Extract the
+`eval` block (`scripts/lib/config.mjs` returns it as `config.eval`, parsed by
+`scripts/lib/config/eval.mjs`):
+
+```
+enabled:  boolean  (default false)
+mode:     'warn' | 'off'            (default 'warn')
+judge:    'off' | 'haiku' | 'sonnet' (default 'off')
+report:   'html' | 'none'           (default 'html')
+handle:   string | null             (default null)
+```
+
+**On-demand `/eval` runs regardless of `eval.enabled`.** The `enabled` flag gates
+the AUTOMATIC session-end eval phase only — it does NOT gate this command (same
+posture as `/reconcile` vs `reconcile.enabled`). `mode: off` is honoured as a
+kill-switch only for the automatic phase; on-demand invocation still runs. If
+`eval.judge` is `off`, skip Phase 3 entirely.
+
+> **Parser gotcha:** the `eval:` key-line itself MUST NOT carry an inline comment
+> (strict `/^eval:\s*$/`); a trailing `# comment` on that exact line makes the
+> parser skip the whole block and silently apply ALL defaults. Sub-key lines
+> tolerate inline comments.
+
+### 1.2 Parse Arguments
+
+Inspect `$ARGUMENTS`:
+
+- `--session <id>` → pass through to `--session`.
+- `--no-write` → evaluate without appending to the journal (dry-run).
+- `--verify <run-id>` → **verification mode**: skip Phases 2–4, run the CLI
+  `--verify` path (see Phase 6), report MATCH/DRIFT, done.
+
+### 1.3 Capture the Model Id (honest provenance)
+
+The record's `model.source` records HOW the model id was captured, precisely
+because self-report is unreliable:
+
+- If `$ANTHROPIC_MODEL` is set in the environment, the engine reads it
+  automatically with `source: env` — **env wins over the flag** (precedence
+  `env > flag`). Do not pass `--model-id` in that case; let the engine resolve it.
+- Otherwise the coordinator passes its own self-reported model id:
+  `--model-id <self-reported-model-id> --model-source self-report`.
+
+---
+
+## Phase 2: Deterministic Run
+
+Run the deterministic engine via its CLI. Default target is the last completed
+session (resolution cascade); `--session` overrides.
+
+```bash
+node scripts/eval-session.mjs [--session <id>] --json \
+  [--model-id <self-reported-id> --model-source self-report] \
+  [--no-write]
+```
+
+- **Do NOT pass `--metrics-dir`** for a real run — the engine defaults to the
+  live `.orchestrator/metrics`, the session being evaluated.
+- The CLI captures the eval `timestamp` (the one sanctioned clock read) and hands
+  it to the engine as a parameter, so the scoring path stays clock-free and
+  `--verify`-reproducible.
+- Exit codes: `0` success · `1` user error (session not found) · `2` system error.
+  On exit `1` (e.g. "no completed session found"), surface the message and stop —
+  do not retry with fabricated inputs.
+
+Parse the emitted JSON record. It carries `dimensions[]` (5 deterministic
+entries), `kpis{}`, `provenance.rubric_sha256` (non-null once `rubric-v1.md`
+exists), `model`, `harness`, and `run_id`. Unless `--no-write` was passed, the
+record is already appended to `.orchestrator/metrics/eval.jsonl` by the CLI.
+
+**Contamination check:** if the human-render/summary reports a peer-overlapped
+window, note it — `verification-evidence` and `gate-health` will read
+`cannot-determine` for that reason (attribution is unsafe), which is correct, not
+a defect.
+
+---
+
+## Phase 3: Judge Overlay (ONLY when `eval.judge != off`)
+
+The judge runs **coordinator-side** — `AskUserQuestion` and the `Agent` tool are
+not available inside a dispatched subagent, so the judge is dispatched from the
+coordinator thread using the read-only agent `session-orchestrator:eval-judge`
+(model = `eval.judge`). Reference the API; do not reimplement scoring here:
+
+```javascript
+import { runEvalJudge, mergeJudgeDimensions } from '$PLUGIN_ROOT/scripts/lib/eval/judge.mjs';
+import { appendEvalRecord } from '$PLUGIN_ROOT/scripts/lib/eval/sink.mjs';
+
+// dispatchAgent = the coordinator's Agent-tool dispatch closure targeting
+// subagent_type 'session-orchestrator:eval-judge'.
+const { status, dimensions } = await runEvalJudge({
+  dispatchAgent,
+  record,                       // the deterministic record from Phase 2
+  model: EVAL_JUDGE_MODEL,      // eval.judge ('haiku' | 'sonnet')
+  budget: JUDGE_BUDGET_TOKENS,  // optional
+});
+
+// mergeJudgeDimensions appends the advisory judge dimensions to the record.
+const merged = mergeJudgeDimensions(record, dimensions);
+
+// The COORDINATOR appends the enriched record (subagents never write the journal).
+appendEvalRecord(merged, { path: '.orchestrator/metrics/eval.jsonl' });
+```
+
+- Every judge dimension arrives `advisory: true` + `calibration_status:
+  "uncalibrated"` (the schema firewall rejects any other shape). Keep them
+  visibly separated from the deterministic five in the summary.
+- If `runEvalJudge` returns a non-ok `status` (e.g. dispatch failed), keep the
+  deterministic record as-is and note the judge was unavailable — the
+  deterministic evaluation is complete without it.
+- When `--no-write` was passed in Phase 2, do NOT append the merged record either.
+
+> The judge merge re-writes the record with the SAME `run_id`/`timestamp`, so a
+> later `--verify <run-id>` re-scores the deterministic dimensions from source
+> and diffs them; judge dimensions are advisory and excluded from the drift diff.
+
+---
+
+## Phase 4: Report (ONLY when `eval.report == html`)
+
+Render the derived HTML view from the record:
+
+```javascript
+import { writeEvalReport } from '$PLUGIN_ROOT/scripts/lib/eval/report.mjs';
+
+const res = writeEvalReport(record, { generatedAt: new Date().toISOString() });
+// res.ok === true → res.path === .orchestrator/eval/reports/<run_id>.html
+```
+
+- Output path: `.orchestrator/eval/reports/<run_id>.html` (gitignored — a derived
+  view, rebuildable from the journal).
+- `writeEvalReport` NEVER throws; on `res.ok === false` surface the WARN reason
+  and continue (the journal record is unaffected — the report is derived).
+- **Name the report path in the chat** so the operator can open it.
+- When `eval.report == none`, skip this phase.
+
+---
+
+## Phase 5: Chat Summary
+
+Emit a compact, honest per-dimension summary. Status lines only — no global score.
+
+```
+## /eval — <session_id>  (self-evaluation, aiat-llm-eval/1.0 · rubric-v1 · n=1, no CI)
+
+Deterministic:
+  verification-evidence   PASS   <one-line evidence>
+  plan-fidelity           PASS   completion_rate=1.0 (score)
+  gate-health             PASS   <one-line evidence>
+  process-safety          PASS   <one-line evidence + guard-emission disclosure>
+  efficiency-kpis         N/A    (reported: duration=…s waves=… agents=… tok_in=… tok_out=… carryover=…)
+
+Judge (advisory, uncalibrated)  [only when eval.judge != off]:
+  instruction-adherence   <verdict>   advisory
+  report-quality          <verdict>   advisory
+
+cannot-determine: <k> of 5 deterministic dimensions (<reasons>)
+Report:  .orchestrator/eval/reports/<run_id>.html
+Journal: .orchestrator/metrics/eval.jsonl  (appended: <yes|--no-write>)
+Re-verify: node scripts/eval-session.mjs --verify <run_id>
+```
+
+Always report the `cannot-determine` share explicitly — a high abstention count
+is an honest signal about missing telemetry, not a failure to hide. Always print
+the `--verify` command as the reproducibility handle.
+
+---
+
+## Phase 6: Verification Mode (`--verify <run-id>`)
+
+When Phase 1.2 detected `--verify`, run ONLY:
+
+```bash
+node scripts/eval-session.mjs --verify <run-id> --json
+```
+
+- Exit `0` + `{ match: true }` → the stored record re-scores identically across
+  all deterministic dimensions. Report MATCH with the dimension count.
+- Exit `1` + `{ match: false, diffs }` → scoring drift. Report the per-dimension
+  diff (`id.field: stored=… fresh=…`). Drift means the source data or the engine
+  changed since the record was written — investigate, do not overwrite.
+- `--verify` reproduces the stored model + timestamp verbatim (no env override),
+  so a MATCH is a real reproducibility proof of the scoring, not of model output.
+
+---
+
+## Cross-Platform (Codex CLI / Cursor / Pi) — FA4
+
+The deterministic core is pure Node CLIs (`scripts/eval-session.mjs`) plus Node
+library modules (`report.mjs`, `sink.mjs`) — they run identically on every
+platform. Only the judge phase needs harness-specific tooling.
+
+- **Codex CLI / Cursor / Pi:** the `Agent` tool (and `AskUserQuestion`) are
+  unavailable, so **Phase 3 (judge) is SKIPPED with a one-line note**
+  ("judge phase skipped: requires the Agent tool, unavailable on `<platform>`").
+  Phases 2, 4, 5, 6 run unchanged — they are Node-only. See
+  `skills/_shared/platform-tools.md` § Agent Dispatch Pattern.
+- **`harness.platform`** on the record is resolved from `$SO_PLATFORM`
+  (falls back to `claude-code`) inside the engine — no skill action needed.
+- The deterministic five dimensions + the HTML report + `--verify` are fully
+  available on all platforms; the judge overlay is a Claude-Code-only enrichment
+  in v1.
+
+---
+
+## Anti-Patterns
+
+- **DO NOT** derive, print, or imply a global/overall/aggregate score — the record
+  forbids one by construction and so does every report.
+- **DO NOT** guess or "fill in" missing data — a missing gate result, KPI, or
+  completion_rate is `cannot-determine`/`null`, never a fabricated pass or `0`.
+- **DO NOT** present the judge's advisory verdict as a measurement — it is
+  `uncalibrated` in v1 and must stay visibly separated from the deterministic
+  tally.
+- **DO NOT** treat the HTML report as authoritative — the journal is the SSOT; the
+  report is a rebuildable derived view.
+- **DO NOT** skip `--verify` when reproducibility is in question — it is the
+  executable proof, and its MATCH/DRIFT exit code is the source of truth.
+- **DO NOT** pass `--metrics-dir` for a real run — that points the engine at
+  fixture data instead of the live session metrics.
+- **DO NOT** call `runReconcile`-style writes from a subagent — the coordinator
+  owns every `eval.jsonl` append (PSA-007).