Fix review nits: valid workflow JS, screenshot paths, doc accuracy

- Wrap both .claude/workflows/*.js procedural bodies in an exported
  async run() so they pass `node --check` (top-level return/await were
  illegal in the ES modules); schema/meta consts stay module-level.
- Clarify Behat screenshot locations in ci-log-analyzer / review-app-triage:
  Behat writes to features/, CI moves them to web/screenshots/ on the review URL.
- CLAUDE.md: correct the profiling-extensions row (xdebug toggles
  on/off/status; blackfire/newrelic only enable).
- observability.md: mark Tier 2 OTel files as not-yet-present (land with PR #466).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NG6zFnH8rBuEykvqFBeC8X

Author: claude

.claude/agents/ci-log-analyzer.md

@@ -17,7 +17,9 @@ Sources you can read:
 Method:
 1. Identify the failing **stage/job** and its underlying `make` target.
 2. Find the **first** error (not the cascade after it). For Behat, read the JUnit failure message and
-   the matching screenshot name under `web/screenshots/`.
+   the matching screenshot: Behat writes PNGs to `features/` (FailAid `screenshot.directory` in
+   `behat.default.yml`); in CI the `test:behat` job moves them to `web/screenshots/` and serves them on
+   the review URL.
 3. Correlate with recent changes (`git log --oneline -15`, `git diff` against last green) to point at a
    suspect file/commit.
 4. Note environment-specific causes: SAPI mismatch (Unit vs FrankenPHP), DB engine, basic-auth on the

.claude/skills/review-app-triage/SKILL.md

@@ -19,8 +19,9 @@ project's own validation targets — see [docs/ci-pipeline.md](../../../docs/ci-
    [ci-pipeline.md](../../../docs/ci-pipeline.md#job--make-target--script-map). The likely culprits:
    - `build:*` red → install failed: re-run `make all_ci` (or `make all` locally) and read the first
      error; usually composer resolution or `drush si`.
-   - `test:behat` red → read the **JUnit** artifact (`junit/*.xml`) and the screenshots under
-     `web/screenshots/`. Reproduce locally with `make behat`.
+   - `test:behat` red → read the **JUnit** artifact (`junit/*.xml`) and the screenshots (Behat writes
+     them to `features/`; in CI they are moved to `web/screenshots/` and served on the review URL).
+     Reproduce locally with `make behat`.
    - `test:cinsp` / `test:upgradestatus` / `test:statusreport` / `test:watchdog` red → run the same
      target locally (`make cinsp`, `make upgradestatusval`, …); each prints the offending file/config/log.
    - `test:lighthouse` red → a category dropped below the `lighthouserc.yml` threshold; read

.claude/workflows/drupal-upgrade.workflow.js

@@ -39,24 +39,26 @@ const VERDICT = {
   },
 }
 
-// --- Gate: is D11 unblocked? ---
-phase('Gate')
-const gate = await agent(
-  `Determine whether a Drupal 11 upgrade is currently unblocked for the skilld-docker-container repo.
+// The harness invokes this with the workflow context (phase/agent/log/budget helpers).
+export async function run({ phase, agent, log, budget }) {
+  // --- Gate: is D11 unblocked? ---
+  phase('Gate')
+  const gate = await agent(
+    `Determine whether a Drupal 11 upgrade is currently unblocked for the skilld-docker-container repo.
 Run \`composer show skilldlabs/druxxy --all\` (the default install profile) and check whether any
 release allows drupal/core ^11. Also skim composer.json require/require-dev for other obvious D11
 blockers. Return blocked=true if druxxy (or core) cannot resolve on ^11, with a one-line reason and,
 if blocked, a workaround (e.g. temporarily set PROFILE_NAME=standard on the throwaway branch).`,
-  { phase: 'Gate', schema: GATE },
-)
-if (gate?.blocked) {
-  log(`D11 gate BLOCKED: ${gate.reason}. Proceeding on the throwaway branch with workaround: ${gate.workaround || 'PROFILE_NAME=standard'}.`)
-}
+    { phase: 'Gate', schema: GATE },
+  )
+  if (gate?.blocked) {
+    log(`D11 gate BLOCKED: ${gate.reason}. Proceeding on the throwaway branch with workaround: ${gate.workaround || 'PROFILE_NAME=standard'}.`)
+  }
 
-// --- Apply the transitional changes in an isolated worktree ---
-phase('Apply')
-const apply = await agent(
-  `In an isolated git worktree, apply the TRANSITIONAL Drupal 11 changes from docs/upgrading.md:
+  // --- Apply the transitional changes in an isolated worktree ---
+  phase('Apply')
+  const apply = await agent(
+    `In an isolated git worktree, apply the TRANSITIONAL Drupal 11 changes from docs/upgrading.md:
 1. composer.json: set drupal/core-composer-scaffold and drupal/core-vendor-hardening to "^10.3.1 || ^11";
    bump skilldlabs/druxxy to a D11-capable release IF ${gate?.blocked ? 'one exists (it may not — if blocked, leave druxxy and instead set PROFILE_NAME=standard in .env.default for validation only)' : 'available'}.
 2. Remove drupal/ckeditor, drupal/color, drupal/seven. git grep for stragglers; switch admin theme to claro.
@@ -65,37 +67,38 @@ const apply = await agent(
 4. Re-verify the drupal/default_content patch still applies; drop it if upstreamed.
 5. Run \`composer update --with-all-dependencies\` (via the php container) and report whether it resolved.
 Make minimal, reviewable edits. Return composerResolved, a summary, the removed modules, and any open problems.`,
-  { phase: 'Apply', schema: APPLY, isolation: 'worktree' },
-)
-log(`Apply: ${apply?.summary || 'no result'}`)
+    { phase: 'Apply', schema: APPLY, isolation: 'worktree' },
+  )
+  log(`Apply: ${apply?.summary || 'no result'}`)
 
-// --- Validate and iterate to ready ---
-phase('Validate')
-let verdict = null
-const MAX_ITERS = budget.total ? 6 : 3
-for (let i = 1; i <= MAX_ITERS; i++) {
-  verdict = await agent(
-    `Validate Drupal upgrade-readiness of the current worktree. Run \`make upgradestatusval\` (authority),
+  // --- Validate and iterate to ready ---
+  phase('Validate')
+  let verdict = null
+  const MAX_ITERS = budget.total ? 6 : 3
+  for (let i = 1; i <= MAX_ITERS; i++) {
+    verdict = await agent(
+      `Validate Drupal upgrade-readiness of the current worktree. Run \`make upgradestatusval\` (authority),
 \`make drupalrectorval\`, and \`make cinsp\`. Report ready=true only if upgrade_status prints no FILE:
 lines. List remaining blockers (custom-code deprecations, by file) and which are rector-auto-fixable.`,
-    { phase: 'Validate', label: `validate#${i}`, schema: VERDICT, agentType: 'upgrade-validator' },
-  )
-  if (verdict?.ready) { log(`Ready after ${i} iteration(s).`); break }
-  if (!verdict?.blockers?.length) { log('No blockers reported but not marked ready — stopping to avoid a loop.'); break }
-  log(`Iteration ${i}: ${verdict.blockers.length} blocker(s). Attempting fixes.`)
-  await agent(
-    `Fix these Drupal 11 deprecations in custom code only (web/modules/custom, web/themes/custom):
+      { phase: 'Validate', label: `validate#${i}`, schema: VERDICT, agentType: 'upgrade-validator' },
+    )
+    if (verdict?.ready) { log(`Ready after ${i} iteration(s).`); break }
+    if (!verdict?.blockers?.length) { log('No blockers reported but not marked ready — stopping to avoid a loop.'); break }
+    log(`Iteration ${i}: ${verdict.blockers.length} blocker(s). Attempting fixes.`)
+    await agent(
+      `Fix these Drupal 11 deprecations in custom code only (web/modules/custom, web/themes/custom):
 ${verdict.blockers.map((b, n) => `${n + 1}. ${b}`).join('\n')}
 Prefer \`vendor/bin/rector process web/modules/custom web/themes/custom\` for the auto-fixable ones,
 then hand-edit the rest. Do not touch contrib/core. Keep edits minimal.`,
-    { phase: 'Validate', label: `fix#${i}`, isolation: 'worktree' },
-  )
-}
+      { phase: 'Validate', label: `fix#${i}`, isolation: 'worktree' },
+    )
+  }
 
-return {
-  gate,
-  apply,
-  finalVerdict: verdict,
-  done: !!verdict?.ready,
-  note: 'Definition of done is a green D11 review app — open an MR and run build:review + the test:* jobs.',
+  return {
+    gate,
+    apply,
+    finalVerdict: verdict,
+    done: !!verdict?.ready,
+    note: 'Definition of done is a green D11 review app — open an MR and run build:review + the test:* jobs.',
+  }
 }

.claude/workflows/newrelic-bump.workflow.js

@@ -26,22 +26,24 @@ const RESULT = {
   },
 }
 
-phase('Find')
-const latest = await agent(
-  `Find the latest NewRelic PHP agent release version. Read the current pin from
+// The harness invokes this with the workflow context (phase/agent/log helpers).
+export async function run({ phase, agent, log }) {
+  phase('Find')
+  const latest = await agent(
+    `Find the latest NewRelic PHP agent release version. Read the current pin from
 scripts/makefile/newrelic.sh (the NEW_RELIC_AGENT_VERSION default). Determine the newest available
 release version and its release-notes URL. Return version, releaseUrl, and current.`,
-  { phase: 'Find', schema: LATEST },
-)
-log(`NewRelic agent: current ${latest?.current || '?'} → latest ${latest?.version || '?'}`)
+    { phase: 'Find', schema: LATEST },
+  )
+  log(`NewRelic agent: current ${latest?.current || '?'} → latest ${latest?.version || '?'}`)
 
-if (latest && latest.version && latest.version === latest.current) {
-  return { bumped: false, summary: `Already at the latest agent version (${latest.version}).` }
-}
+  if (latest && latest.version && latest.version === latest.current) {
+    return { bumped: false, summary: `Already at the latest agent version (${latest.version}).` }
+  }
 
-phase('Bump')
-const result = await agent(
-  `Bump the NewRelic PHP agent to ${latest?.version}.
+  phase('Bump')
+  const result = await agent(
+    `Bump the NewRelic PHP agent to ${latest?.version}.
 1. Edit the version string in scripts/makefile/newrelic.sh (and any matching version in .env.default or
    docker config if present). Make a minimal diff.
 2. Run \`composer validate\`. If a stack is up, run \`make newrelic reload\` and confirm the agent loads
@@ -50,7 +52,8 @@ const result = await agent(
 3. Prepare a commit message in the repo's existing convention: "NR: <release-notes-url>"
    (see \`git log --oneline | grep '^... NR:'\`). Do NOT commit unless asked.
 Return bumped, a summary, and the proposed commitMessage.`,
-  { phase: 'Bump', schema: RESULT, agentType: 'dep-bumper' },
-)
+    { phase: 'Bump', schema: RESULT, agentType: 'dep-bumper' },
+  )
 
-return { ...result, from: latest?.current, to: latest?.version, releaseUrl: latest?.releaseUrl }
+  return { ...result, from: latest?.current, to: latest?.version, releaseUrl: latest?.releaseUrl }
+}

CLAUDE.md

@@ -40,7 +40,7 @@ and `make xdebug on` forward extra tokens to the wrapped command.
 | `make front` / `make lint` / `make storybook` | Theme build / lint+fix / Storybook (need `THEME_NAME`) |
 | `make tests` | Run the full validation + test suite (see below) |
 | `make behat` | Run Behat browser tests |
-| `make xdebug on\|off\|status`, `make blackfire`, `make newrelic` | Toggle profiling/debug PHP extensions |
+| `make xdebug on\|off\|status` / `make blackfire` / `make newrelic` | Profiling/debug PHP extensions — `xdebug` toggles on/off/status; `blackfire` and `newrelic` enable only (`newrelic` needs `NEW_RELIC_LICENSE_KEY`) |
 
 ### Tests & validations
 

docs/observability.md

@@ -28,9 +28,10 @@ Unit's status/health route as a liveness probe in the override file's `php` serv
 ## Tier 2 — Traces (opt-in OpenTelemetry)
 
 Distributed tracing is prototyped in **PR #466** (`otel` branch). Rather than reinvent it, the plan is
-to **rebase and finish that PR**, then gate it behind a flag. What it wires up:
+to **rebase and finish that PR**, then gate it behind a flag. What it wires up (none of these files/
+settings exist on this branch yet — they land with PR #466):
 
-| Piece | Where |
+| Piece | Where (added by PR #466) |
 | --- | --- |
 | Tempo (trace store) + Grafana (UI) services | `docker/docker-compose.override.yml.default` |
 | Tempo config | `docker/tempo.yml` |