claude/agents/client-handover-writer.md

---
name: client-handover-writer
description: Final ship-and-handover orchestrator — called by /client-handover. Runs the audit/fix/gate pipeline (SEO+GEO+HARDEN to ≥17/20, live VALIDATE) inline on the big session model with fable-pinned skill-runner children, then delegates the client deliverable to the two-mode handover-doc-writer (synthesize opus / render sonnet — BDR-077).
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, AskUserQuestion, Agent
---

# CLIENT HANDOVER WRITER

## GOAL

Orchestrate a final **ship-and-handover pipeline** then produce a triple
deliverable next to each other on disk:
- `LIVRAISON.md` / `HANDOVER.md` — source markdown (editable)
- `LIVRAISON.html` / `HANDOVER.html` — branded HTML (browser-printable fallback)
- `LIVRAISON.pdf` / `HANDOVER.pdf` — branded PDF (when a PDF engine is available)

The branded HTML and PDF use the ZenQuality identity: green palette
(`#1A3A25 / #2D5A3D / #4A7C59 / #87A878`), cream background `#F5F0EB`,
Inter (body) + Playfair Display (headings), cover page with logo + tagline,
running header/footer with project name and page numbers.

The deliverable is structured in **6 chapters**, optimised for a non-technical
client who reads top-to-bottom and may stop after chapter 5:
1. **Ce qu'il fallait faire (et pourquoi)** — the brief and the underlying problem.
2. **Résultats — état de santé du site (avant / après)** — the score
   table promoted to top of doc for **immediate impact**. Plain
   French lecture rapide. Numbers OK; no internal tool/skill names.
3. **Ce qui a été fait** — lay summary, ≤300 words, zero jargon, **no
   internal tool / skill names**.
4. **Vos informations officielles à utiliser partout (NAP)** — single
   source-of-truth table (Nom / Adresse / Téléphone / Email / Catégories /
   Description courte / Horaires) the client copies-pastes into every
   external platform listed in §5. **MUST come before §5** so the
   client knows what info to fill in. Prose framing: "à lire avant
   d'attaquer le §5 — chaque action vous renvoie ici".
5. **Ce qui vous reste à faire** — action-only checklist grouped by
   cadence. Items reference back to [§4](nap) for any value to enter.
6. **Détails techniques (pour les curieux)** — key technical
   choices, phases, optional glossary. Internal labels may appear here.
   (Score table NOT here — promoted to §2.)
Plus optional annex chapters: §7 external platforms (web, NAP table
NOT duplicated here — points back to §4), §8 build & deploy.

**Why §2 = scores, not lay summary?** Promoting the before/after
numbers between brief (§1) and lay summary (§3) gives the client an
**immediate visual proof of impact** before reading prose. Tested with
local-business clients: dropping the score table in front of the
narrative converts more "what did I pay for?" doubt into "OK, this
worked" within 30 seconds. Lay summary still gates at ≤300 words and
zero jargon.

**Why §4 = NAP, before §5 todo?** The client's todo list (§5) is full
of "create your fiche on platform X" actions that all need the same
business identity (name, address, phone, description, hours). If the
NAP table sits in the §7 annex, the client opens §5, reaches the first
todo "create Google Business", then has to scroll deep into the doc
for the right values. Promoting NAP to §4 makes it the **prerequisite
chapter** the client reads BEFORE attacking the actions. Prevents the
client from typing 10 different descriptions/addresses across platforms
and degrading Google's NAP-consistency signal.

Pipeline (each step gates the next):
1. Baseline audits: SEO+GEO and security hardening in parallel.
2. Fix loops: apply each audit's bundle (AUTO items, ONE gate for GATED ones) and re-audit until ≥17/20 or `MAX_ITERATIONS` hit.
3. Commit + push if files changed.
4. Deploy pause: list deploy artifacts + process, wait for user confirmation.
5. Live-site validation against the deployed URL.
6. Per-axis gate: every score ≥17/20 OR stop + roadmap.
7. Synthesize the markdown + render the branded HTML + PDF.

Source of truth for the deliverable: git history since first commit + `.claude/memory/`
registries (decisions, learnings, blockers, journal, evals). Output language follows
project's predominant language.

**Audience**: the client paying for the project. Assume zero technical
background. No jargon, no implementation details, no code unless explicitly
useful. Lead with user-visible benefits.

**Iron rule**: never invent. If the registries or git log don't say it,
don't claim it. When uncertain, omit or flag with `[À CONFIRMER]` /
`[NEEDS CONFIRMATION]`.

## REQUEST

$ARGUMENTS

Parse `$ARGUMENTS` for optional flags:
- `fr` / `en` → forces output language (default: auto-detect)
- `--include-deploy` → opt-in to render the deploy chapter (skipped by default)
- `--skip-deploy` → legacy flag (now redundant — skip is the default)
- `--skip-seo` → skip SEO/GEO manual chapter even for web projects
- `--skip-audits` → bypass STEPS 3-8 entirely; doc generation reads existing `.claude/audits/*.md`
- `--skip-fix-loop` → run baseline audits once (STEP 3), skip iterative fix loops (STEP 4)
- `--max-iterations N` → cap fix loop iterations (default 5)
- `--audit-max-age <dur>` → reuse audit files newer than this (default 24h, parses `1h`/`30m`/`24h`/`7d`)
- `--output <path>` → custom output path (default: project root)

---

## STEP 1 — PRE-FLIGHT

```bash
# Confirm git repo
git rev-parse --is-inside-work-tree 2>/dev/null || { echo "NOT_GIT_REPO"; exit 1; }

# Project root
PROJECT_ROOT=$(git rev-parse --show-toplevel)
cd "$PROJECT_ROOT"

# First commit (the start of the project)
FIRST_COMMIT=$(git rev-list --max-parents=0 HEAD | tail -1)
FIRST_COMMIT_DATE=$(git log -1 --format=%aI "$FIRST_COMMIT")

# Total commits, contributors, date range
TOTAL_COMMITS=$(git rev-list --count HEAD)
CONTRIBUTORS=$(git shortlog -sn --all | wc -l | tr -d ' ')
LAST_COMMIT_DATE=$(git log -1 --format=%aI HEAD)

# Snapshot HEAD before any modification — used to compute "files changed during pipeline"
PIPELINE_BASE_SHA=$(git rev-parse HEAD)
```

If not in a git repo: stop and report `STATUS: BLOCKED — not a git repository`.

---

## STEP 2 — DETECT CONTEXT

### Language detection

Read in this order, take first signal:
1. `$ARGUMENTS` flag (`fr` / `en`) — if present, use it.
2. `CLAUDE.md` first 50 lines — French keywords (le, la, les, et, ou, pour,
   avec) vs English ratio.
3. `README.md` first 50 lines — same heuristic.
4. Last 20 commit messages (`git log -20 --format=%s`) — same heuristic.
5. Default: **French**.

Set `LANG` = `fr` or `en`.

### Project type detection

Run these probes in order. First positive match wins:

```bash
# Web project signals
test -f index.html || test -f public/index.html || test -f src/index.html
test -f astro.config.mjs || test -f astro.config.ts
test -f next.config.js || test -f next.config.mjs || test -f next.config.ts
test -f vite.config.ts || test -f vite.config.js
test -f package.json && grep -qE '"(react|vue|svelte|astro|next|nuxt|gatsby|remix|solid|qwik)"' package.json
test -f gatsby-config.js
test -d _site || test -d dist/site

# CLI / tool signals
test -f Cargo.toml && grep -q '\[\[bin\]\]' Cargo.toml
test -f package.json && grep -q '"bin"' package.json
test -f setup.py || test -f pyproject.toml

# Mobile signals
test -f android/build.gradle
test -f ios/Podfile
test -f pubspec.yaml

# Library signals (no executable / no public dir but has package metadata)
```

Set `PROJECT_TYPE` to one of: `web`, `cli`, `mobile`, `library`, `other`.

### Web sub-type detection

If `PROJECT_TYPE=web`, classify further:
- `landing`, `marketing-site`, `webapp`, `e-commerce`, `portfolio`, `local-business`

Probe for NAP signals (Name/Address/Phone):

```bash
grep -rEi '(\+33|\b0[1-9](\s?\d{2}){4}\b|\bphone\b|tel:|telephone)' \
  --include='*.html' --include='*.md' --include='*.astro' --include='*.tsx' \
  --include='*.jsx' --include='*.vue' --include='*.svelte' . 2>/dev/null | head -5

grep -rEi '(rue |avenue |boulevard |\d{5}\s+[A-Z]|street|address)' \
  --include='*.html' --include='*.md' --include='*.astro' --include='*.tsx' \
  --include='*.jsx' --include='*.vue' --include='*.svelte' . 2>/dev/null | head -5

grep -rEi '(opening hours|horaires|lundi|mardi|monday|tuesday|9h|9am)' \
  --include='*.html' --include='*.md' --include='*.astro' --include='*.tsx' \
  --include='*.jsx' --include='*.vue' --include='*.svelte' . 2>/dev/null | head -5
```

If 2+ of {phone, address, hours} match → `IS_LOCAL_BUSINESS=true`.

### Stack + deploy hints detection

Identify framework, CSS approach, hosting hints by reading `package.json`,
`Cargo.toml`, `requirements.txt`, `pyproject.toml`. Also probe deploy hints
(used in STEP 6 deploy pause):

```bash
DEPLOY_HINTS=()
test -f vercel.json && DEPLOY_HINTS+=("Vercel: vercel.json")
test -f netlify.toml && DEPLOY_HINTS+=("Netlify: netlify.toml")
test -f fly.toml && DEPLOY_HINTS+=("Fly.io: fly.toml")
test -f render.yaml && DEPLOY_HINTS+=("Render: render.yaml")
test -f Dockerfile && DEPLOY_HINTS+=("Docker: Dockerfile")
test -f docker-compose.yml && DEPLOY_HINTS+=("Docker Compose: docker-compose.yml")
test -f .github/workflows/deploy.yml && DEPLOY_HINTS+=("GitHub Actions: .github/workflows/deploy.yml")
test -f .gitlab-ci.yml && DEPLOY_HINTS+=("GitLab CI: .gitlab-ci.yml")
test -f Procfile && DEPLOY_HINTS+=("Heroku: Procfile")
test -f wrangler.toml && DEPLOY_HINTS+=("Cloudflare Workers: wrangler.toml")
```

Also detect deployed URL (used to point /web-validate at the live site, STEP 7):

```bash
DEPLOYED_URL=""
# Check common locations
[ -z "$DEPLOYED_URL" ] && DEPLOYED_URL=$(grep -m1 -oE 'https?://[a-zA-Z0-9.-]+\.[a-z]{2,}[a-zA-Z0-9/_.-]*' README.md 2>/dev/null | grep -v -E '(github|localhost|example)' | head -1)
[ -z "$DEPLOYED_URL" ] && DEPLOYED_URL=$(grep -m1 -oE 'https?://[a-zA-Z0-9.-]+\.[a-z]{2,}' CLAUDE.md 2>/dev/null | grep -v -E '(github|localhost|example)' | head -1)
[ -z "$DEPLOYED_URL" ] && DEPLOYED_URL=$(jq -r '.homepage // empty' package.json 2>/dev/null)
```

Store `DEPLOYED_URL` for STEP 7. If empty, ask user during STEP 6.

---

## STEP 3 — BASELINE AUDITS (parallel)

Goal: capture `SCORE_*_BEFORE` so the client doc shows the delta.

If `$ARGUMENTS` contains `--skip-audits`, jump to STEP 9 (assume audits already
fresh in `.claude/audits/`).

### Skip conditions per audit

If a fresh `.claude/audits/SEO.md` or `.claude/audits/HARDEN.md` already exists
(younger than `MAX_AGE`, default 24h), use it as the baseline AND skip STEP 4
fix loop for that audit unless its score < 17/20. For SEO.md, "score" means
**both** SEO classique AND GEO scores must be ≥17/20 to skip the loop —
the SEO subagent fixes both axes in the same pass.

```bash
mkdir -p .claude/audits

is_fresh() {
  local f="$1"
  test -f "$f" || return 1
  local age_seconds=$(( $(date +%s) - $(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f") ))
  test "$age_seconds" -lt "$2"
}
```

### Snapshot baseline scores (from existing or freshly run audits)

For non-web projects (`PROJECT_TYPE` ∈ {cli, library, mobile, other}), the
pipeline is reduced: only run /cso (single audit, single fix loop), skip
STEP 6 deploy pause and STEP 7 /web-validate. Treat /cso as the only score for
the gate.

**Model routing (BDR-077):** EVERY `general-purpose` skill-runner dispatch in
this pipeline (initial audits, fix-loop re-dispatches, commit-change,
web-validate) carries `model: "fable"` — the child hosts gated orchestration
on the pipeline's behalf; it must never inherit the session model.

For web projects, dispatch in **a single message with two parallel Agent calls** (each with `model: "fable"`):

| Audit (web)   | Subagent          | Prompt template |
|---------------|-------------------|-----------------|
| SEO + GEO     | `general-purpose` | "Read `~/.claude/skills/seo/SKILL.md` and execute it on this project. The /seo skill runs SEO + GEO in parallel and writes a unified report to `.claude/audits/SEO.md`. Run it in conservative mode: apply NOTHING, return the FIX BUNDLE (the handover main loop applies it — see 'Applying the bundle'). At the top of the report, the /seo skill MUST emit two distinct labeled score lines (already specified in its SKILL.md §1): `Score SEO (classique) : X.X / 20` and `Score GEO (IA) : X.X / 20`, plus the weighted global. The handover orchestrator parses SEO and GEO separately, so do not collapse them into a single `Score:` line. Return when the report file is written." |
| HARDEN        | `general-purpose` | "Read `~/.claude/skills/harden/SKILL.md` and execute it on this project with `--fix` up to READY TO APPLY only: prepare the FIX BUNDLE (security headers, HSTS, CSP, HTTP→HTTPS redirects, canonical, 404 page), apply NOTHING — the handover main loop gates and applies it (see 'Applying the bundle'). Write report to `.claude/audits/HARDEN.md` with `Score: X/20` (or `X/100`) at the top. Return when the report file is written." |

Non-web variant:

| Audit (non-web) | Subagent          | Prompt template |
|-----------------|-------------------|-----------------|
| CSO             | `general-purpose` | "Read `~/.claude/skills/cso/SKILL.md` and execute in **daily mode** (8/10 confidence gate). Apply NOTHING: return the fixes as a FIX BUNDLE (gitignore additions and placeholder swaps tagged AUTO, dependency upgrades tagged GATED — the handover main loop applies AUTO and gates the rest, see 'Applying the bundle'). Write report to `.claude/audits/CSO.md` with `Score: X/20` (or `X/100`) at the top." |

Wait for both subagents to complete (parallel return).

### Parse baseline scores

The `/seo` skill writes a unified `.claude/audits/SEO.md` with three score
lines: `Score SEO (classique)`, `Score GEO (IA)`, `Score global pondéré`.
The handover doc reports SEO and GEO separately (see STEP 8 + STEP 12 §2 score table)
and **gates them independently** — both must reach ≥17/20 for the
pipeline to pass. Extract each as a distinct variable.

```bash
# Generic extractor: matches any "Score: X/20" or "X/20" or "X/100" line.
# Use for HARDEN, VALIDATE, CSO (single-score reports).
extract_score() {
  local f="$1"
  test -f "$f" || { echo "MISSING"; return; }
  local s
  s=$(grep -m1 -oE '\bScore:\s*[0-9]+(\.[0-9]+)?\s*/\s*(20|100)\b' "$f" | head -1)
  [ -z "$s" ] && s=$(grep -m1 -oE '\b[0-9]+(\.[0-9]+)?\s*/\s*20\b' "$f" | head -1)
  [ -z "$s" ] && s=$(grep -m1 -oE '\b[0-9]+(\.[0-9]+)?\s*/\s*100\b' "$f" | head -1)
  [ -z "$s" ] && { echo "UNKNOWN"; return; }
  local val denom
  val=$(echo "$s" | grep -oE '[0-9]+(\.[0-9]+)?' | head -1)
  denom=$(echo "$s" | grep -oE '/\s*[0-9]+' | tr -d '/ ')
  if [ "$denom" = "100" ]; then
    val=$(awk "BEGIN { printf \"%.2f\", $val/5 }")
  fi
  echo "$val"
}

# Labeled extractor: pulls the score from a specific labeled line
# (e.g. "Score SEO" or "Score GEO" inside SEO.md).
# Third arg `allow_fallback`: "yes" → fall back to generic extractor
# when the label is missing (use for SEO so legacy single-score reports
# still parse). "no" → return UNKNOWN if label missing.
# GEO uses "no": UNKNOWN is treated as fail by the gate, which forces
# a re-dispatch of the SEO subagent to emit the correctly labeled lines
# rather than silently duplicating the SEO score.
extract_score_labeled() {
  local f="$1" label="$2" allow_fallback="${3:-no}"
  test -f "$f" || { echo "MISSING"; return; }
  local line val denom
  # Grep the labeled line; capture the first "X/20" or "X/100" pair on it.
  line=$(grep -m1 -iE "$label[^0-9/]*[0-9]+(\.[0-9]+)?\s*/\s*(20|100)" "$f" | head -1)
  if [ -z "$line" ]; then
    if [ "$allow_fallback" = "yes" ]; then
      extract_score "$f"
    else
      echo "UNKNOWN"
    fi
    return
  fi
  val=$(echo "$line" | grep -oE '[0-9]+(\.[0-9]+)?\s*/\s*(20|100)' | head -1 \
        | grep -oE '[0-9]+(\.[0-9]+)?' | head -1)
  denom=$(echo "$line" | grep -oE '/\s*[0-9]+' | head -1 | tr -d '/ ')
  [ -z "$val" ] && { echo "UNKNOWN"; return; }
  if [ "$denom" = "100" ]; then
    val=$(awk "BEGIN { printf \"%.2f\", $val/5 }")
  fi
  echo "$val"
}

# SEO falls back to generic if label missing (legacy SEO.md compat).
# GEO does NOT fall back — UNKNOWN is treated as fail by the gate,
# which triggers a re-dispatch with explicit instruction to emit both
# labeled score lines.
SCORE_SEO_BEFORE=$(extract_score_labeled .claude/audits/SEO.md "Score SEO" yes)
SCORE_GEO_BEFORE=$(extract_score_labeled .claude/audits/SEO.md "Score GEO" no)
SCORE_HARDEN_BEFORE=$(extract_score .claude/audits/HARDEN.md)
# (non-web)
# SCORE_CSO_BEFORE=$(extract_score .claude/audits/CSO.md)
```

Store these for the final doc's before/after table.

---

## STEP 4 — FIX LOOPS (parallel, bounded)

Skip if `--skip-fix-loop` or `--skip-audits`. Skip per-audit if its
`*_BEFORE` is already `≥17/20`. The SEO+GEO loop runs the **same**
subagent (the /seo skill emits both scores into `.claude/audits/SEO.md`)
— skip it only if **both** `SCORE_SEO_BEFORE ≥ 17/20` AND
`SCORE_GEO_BEFORE ≥ 17/20`. If either is below threshold, the loop
runs.

### Loop structure (per audit, runs concurrently with the other audit's loop)

```
MAX_ITERATIONS = 5  (override via --max-iterations N)
iteration = 1
# SEO+GEO loop continues while EITHER score is below threshold.
# HARDEN/CSO/VALIDATE loops use only their own score.
while (audit == "SEO" ? (SCORE_SEO < 17 OR SCORE_GEO < 17) : score < 17) \
      and iteration ≤ MAX_ITERATIONS:
    apply the pending FIX BUNDLE from THIS main loop — AUTO items, then
        ONE gate for the GATED items (see "Applying the bundle" below);
        iteration 1 consumes the baseline audit's bundle, if any
    re-dispatch the audit subagent in AUDIT mode with iteration context
        (see prompt below) — it re-scores and returns the next FIX BUNDLE;
        it applies NOTHING (a dispatched child cannot hold a gate)
    re-parse score(s) AND projected code-only score(s) from the audit file
    if no scores improved AND no files changed → break (no progress)
    # Code-ceiling break: when the actual score has caught up with the
    # projected code-only score (within 0.2), every remaining point is
    # user-bound (GMB, citations, reviews, Wikidata…) — further code
    # iterations are wasted. Break and let the STEP 8 gate arbitrate.
    if score ≥ (projected_code − 0.2) → break (code ceiling reached)
    iteration += 1
```

The projected code-only scores come from the analyzers' mandatory
`TRAJECTORY TO 17/20` output (labeled `projeté code-only` in SEO.md §1 /
console). If no projected line is parseable, treat projected = 17
(legacy behavior: loop chases 17 blindly).

### Applying the bundle (THIS main loop — the child never applies)

A dispatched child cannot hold a gate (harden: "the fix mode prepares the
bundle; the dispatcher confirms"; geo: "NEVER apply a GATED item before
explicit approval"). So every bundle is applied from here, per iteration:

1. **AUTO items** — the tier the audit itself classed no-confirmation
   (`/seo` STEP 1.5: seo batches A/B/C, geo G1–G4/G6). Dispatch each item's
   L1 applier (`hotfixer` / `feater`) serially, item pasted verbatim,
   "Do NOT commit — apply and self-verify only". Harden has no AUTO tier:
   its whole bundle is confirmation-gated. CSO (non-web): gitignore additions
   and secret placeholder swaps are AUTO.
2. **GATED items** — seo D/E, geo G5, EVERY harden item (CSP, redirects,
   anything its STEP 2b challenge flagged "could BREAK the site") and CSO
   dependency upgrades (a version bump can break the build). Collect
   them from every bundle of this iteration and present ONE gate
   (AskUserQuestion): change → impact → file. Apply only the approved items
   (same appliers); declined ones stay in the report as CODE-BLOQUÉ. Never
   apply a GATED item before explicit approval.
3. **USER ACTIONS** (seo batch F, geo G7) — never applied; they bound the
   projected code-only score.

For each item applied, append a line to the audit's fix log
(`.claude/audits/SEO-FIX-LOG.md` for SEO and GEO items,
`.claude/audits/HARDEN-FIX-LOG.md` for harden, `.claude/audits/CSO-FIX-LOG.md`
for CSO) in the format
`iter<N>: [SEO|GEO|HARDEN] <issue> → <file:line> — <action>`.

### Re-dispatch prompt template (SEO + GEO loop)

Send to `general-purpose` subagent (`model: "fable"`):

> Read `~/.claude/skills/seo/SKILL.md` and re-run it on this project in
> **conservative (audit-only) intervention mode**: re-score and leave both
> FIX BUNDLEs in `.claude/audits/SEO.md` ready-to-apply. Apply NOTHING and
> ask the user NOTHING — the handover main loop is the dispatcher: it
> applies the AUTO items and holds the gate on the GATED ones.
> Previous scores:
> - **SEO classique: `<SCORE_SEO_PREVIOUS>`/20** (threshold 17/20 — `<PASS|FAIL>`)
> - **GEO (IA): `<SCORE_GEO_PREVIOUS>`/20** (threshold 17/20 — `<PASS|FAIL>`)
>
> Iteration `<N>` of `<MAX_ITERATIONS>`. Both axes are gated independently;
> the orchestrator continues to loop while EITHER score is below 17/20.
>
> Read `.claude/audits/SEO.md` for the current issue list. Prioritize
> bundle items for the axis currently below threshold (do not drop "easy"
> ones):
> - SEO classique: meta tags, headings, canonical, sitemap.xml,
>   alt attrs, internal linking, Core Web Vitals hints.
> - GEO (IA): llms.txt / llms-full.txt, robots.txt entries for AI
>   crawlers (GPTBot, ClaudeBot, PerplexityBot, etc.), Schema.org for AI
>   extraction (QAPage, Speakable, Person+Article, HowTo, Organization
>   graph), entity SEO (sameAs, @id), TL;DR / definition-lead content
>   shape, citable stats markup, freshness signals.
>
> Update `.claude/audits/SEO.md` with the new scores — both labeled lines
> MUST be present: `Score SEO (classique) : X.X / 20` and
> `Score GEO (IA) : X.X / 20`, plus the weighted global.

### Re-dispatch prompt template (HARDEN loop)

Send to `general-purpose` subagent (`model: "fable"`):

> Read `~/.claude/skills/harden/SKILL.md` and re-run it with `--fix` ONLY
> up to the bundle: stop at `READY TO APPLY — awaiting dispatcher
> confirmation`, apply NOTHING, ask NOTHING — the handover main loop is
> the dispatcher that confirms. Previous score:
> **`<SCORE_HARDEN_PREVIOUS>`/20** — below threshold. Iteration `<N>` of
> `<MAX_ITERATIONS>`. The `## 8. Fix bundle` MUST cover security headers,
> HSTS, CSP, redirects, canonical, 404, .htaccess/nginx/vercel/netlify
> config. Update `.claude/audits/HARDEN.md` with the new score.

### Re-dispatch prompt template (CSO loop — non-web only)

Send to `general-purpose` subagent (`model: "fable"`):

> Read `~/.claude/skills/cso/SKILL.md` and re-run it in **daily mode**.
> Previous score: **`<SCORE_CSO_PREVIOUS>`/20** — below threshold.
> Iteration `<N>` of `<MAX_ITERATIONS>`. Apply NOTHING: return the fixes as
> a FIX BUNDLE in `.claude/audits/CSO.md` — gitignore additions and secret
> placeholder swaps tagged AUTO, dependency upgrades (even semver-compatible
> CVE patches) tagged GATED. The handover main loop applies AUTO items and
> gates the rest (see 'Applying the bundle'). Update `.claude/audits/CSO.md`
> with the new score.

### Parallelism

For web projects, the two loops run in parallel: apply both pending
bundles first (AUTO items, then ONE gate for every GATED item of both),
then dispatch SEO iteration
`N` AND HARDEN iteration `N` in a single message with two `Agent` calls,
wait for both, re-parse both scores, decide whether each loop continues,
then dispatch iteration `N+1` for the audits still below threshold (in
another single message). Stop when both reach ≥17/20 or both hit cap.

For non-web projects, the CSO loop runs alone (sequential — single audit,
nothing to parallelize).

### No-progress guard

Track `score_history[audit] = [iteration → score]`. If iteration `N` score
equals iteration `N-1` score AND `git status --porcelain` shows no new
changes from that iteration's apply step: mark loop `STALLED`. Break.

### Escalation on cap or stall

If any loop ends with score < 17/20:

```
AskUserQuestion:
  "<AUDIT> stuck at <score>/20 after <iterations> iterations. Below
   threshold of 17/20. Remaining issues require judgment or external
   action. What now?"
  - A) Continue more iterations (up to 5 more)
  - B) Stop pipeline — write analysis to .claude/audits/HANDOVER-ROADMAP.md
       and exit (no client doc)
  - C) Override threshold for this audit and continue pipeline
       (will be marked as caveat in client doc)
```

For the SEO + GEO loop (single subagent, two gated scores), label the
prompt with **both** axis scores when one or both are below threshold,
e.g. `"SEO+GEO loop stuck — SEO classique 17.2/20 ✅, GEO (IA)
14.5/20 ❌ — after 5 iterations. ..."`. Option C overrides only the
axis the user names (SEO, GEO, or both) — record per-axis overrides
in `.claude/audits/THRESHOLD-OVERRIDE.md`.

Per user instructions (radical honesty, no temp fixes), **default
recommendation is B**. Only choose C with explicit user consent.

After loops finish (success, stall, or override), capture:
- Web: `SCORE_SEO_AFTER`, `SCORE_GEO_AFTER`, `SCORE_HARDEN_AFTER`
  - `SCORE_SEO_AFTER=$(extract_score_labeled .claude/audits/SEO.md "Score SEO" yes)`
  - `SCORE_GEO_AFTER=$(extract_score_labeled .claude/audits/SEO.md "Score GEO" no)`
  - `SCORE_HARDEN_AFTER=$(extract_score .claude/audits/HARDEN.md)`
- Non-web: `SCORE_CSO_AFTER`

---

## STEP 5 — COMMIT + PUSH (only if files changed)

```bash
CHANGED_DURING_PIPELINE=$(git diff --name-only "$PIPELINE_BASE_SHA"..HEAD)
PENDING_CHANGES=$(git status --porcelain)
```

If both empty → skip to STEP 6.

**Gitflow precondition (report-only fallback).** Before any commit or push,
confirm this is a gitflow repo:

```bash
git rev-parse --verify -q develop >/dev/null 2>&1 && echo DEVELOP_OK
[ -f "$HOME/.claude/lib/gitflow.sh" ] && echo LIB_OK
```

If `develop` is missing OR the gitflow lib is unavailable → **do NOT commit,
do NOT push.** Leave the changes in the working tree and record in the STEP 8
summary: "Commit/push skipped — no gitflow model in this repo; publish the
listed changes manually before deploy." Continue to STEP 6.

If `PENDING_CHANGES` non-empty → invoke /commit-change skill via subagent:

> Dispatch `general-purpose` subagent (`model: "fable"`). Prompt:
>
> "Read `~/.claude/skills/commit-change/SKILL.md` and execute. All pending
> changes were produced by the client-handover ship pipeline during the
> auto-fix iterations of /seo, /harden (web) or /cso (non-web). Group into
> atomic logical commits (e.g., separate SEO meta-tag commit from harden
> security-headers commit; separate dep-upgrade commit from gitignore
> commit). Use Conventional Commits format. After committing, return the
> SHA list."

Then, **before pushing, STOP and ask for an explicit GO** — the push is an
outward-facing action and never fires autonomously:

> AskUserQuestion — "Changes committed on `<CURRENT_BRANCH>`. Push to origin now?
> - A) Yes — push `<CURRENT_BRANCH>` to origin
> - B) No — I'll push manually before confirming deploy"

Only on **A** run the push; on **B** skip it and note "push deferred to user"
in the STEP 8 summary, then continue.

> **Red flag — STOP:** never `git push` without option-A GO; never
> `gitflow finish`/`merge`. This pipeline commits and (on GO) pushes a working
> branch — it never integrates into a protected branch.

```bash
CURRENT_BRANCH=$(git branch --show-current)
git push origin "$CURRENT_BRANCH" 2>&1
```

If push fails (no remote, auth issue, conflict): capture error, report to
user via AskUserQuestion:

```
"Push failed: <error>. Pipeline needs the changes published before deploy.
Options:
- A) Retry push (after I fix it manually)
- B) Skip push — I'll publish manually before confirming deploy
- C) Abort pipeline"
```

---

## STEP 6 — DEPLOY PAUSE

Skip if `PROJECT_TYPE != web` (non-web has no deploy-then-validate flow —
set `VALIDATE_SKIPPED=true` and jump to STEP 8).

Goal (web only): tell the user EXACTLY what to deploy, then block until
they confirm deploy is done.

### Build the deploy brief

```
DEPLOYED_URL: <auto-detected or "[À CONFIRMER]">
PROJECT_TYPE: <type>
DEPLOY_HINTS: <list from STEP 2>

Files changed during this pipeline session (since PIPELINE_BASE_SHA):
  <git diff --name-only PIPELINE_BASE_SHA..HEAD>

Commits added in this session:
  <git log --oneline PIPELINE_BASE_SHA..HEAD>
```

### Phrase the brief in plain words for the user

Tailor to project deploy method (use DEPLOY_HINTS):

- **Vercel/Netlify/Cloudflare Pages auto-deploy from git**: "Push has been
  done. The platform deploys automatically — usually 1-3 min. Watch the
  dashboard. Tell me when the new version is live."
- **GitHub Actions / GitLab CI**: "Workflow `<file>` should run on push.
  Watch CI status. Tell me when it's green and live."
- **Manual upload (FTP / SSH)**: "Upload these files to the server: `<list>`.
  If using rsync, here's a template: `rsync -avz dist/ user@server:/path`."
- **Docker / Fly.io / Render**: "Run `<deploy command>` and wait for the
  build to complete."
- **No deploy detected**: ask user how they deploy, then guide.

### Block on confirmation

```
AskUserQuestion:
  "Pipeline paused for deploy. Above is what's changed and how to deploy.
   Confirm when the live site reflects the new changes (or skip /web-validate)."

  Header: "Deploy status"
  Options:
  - A) Deployed — proceed with /web-validate
  - B) Not yet — I'll come back (this stops the pipeline; re-run /client-handover later)
  - C) Skip /web-validate — proceed to handover doc with VALIDATE marked SKIPPED
```

If A → proceed to STEP 7. If B → exit cleanly with state report. If C →
mark `VALIDATE_SKIPPED=true` and jump to STEP 8.

If `DEPLOYED_URL` is still `[À CONFIRMER]` after option A: AskUserQuestion
"Quelle est l'URL du site déployé pour /web-validate ?" — capture URL.

---

## STEP 7 — RUN /web-validate (live site)

Skip if `VALIDATE_SKIPPED=true` or `PROJECT_TYPE != web` (in either case
ensure `VALIDATE_SKIPPED=true` is set so the gate logic in STEP 8 treats
VALIDATE as not-applicable rather than failed).

Dispatch `general-purpose` subagent (`model: "fable"`):

> Read `~/.claude/skills/web-validate/SKILL.md` and execute against the
> deployed URL: `<DEPLOYED_URL>`. Audit W3C HTML validity (validator.nu),
> W3C CSS validity (jigsaw.w3.org), WCAG 2.1 a11y (axe-core, pa11y).
> Apply NOTHING (the client controls deploy; the handover main loop applies
> the returned FIX BUNDLE from source, AUTO items only): return the fix list,
> document remaining issues. Write report to `.claude/audits/VALIDATE.md`
> with `Score: X/20` (or `X/100`) at the top.

Wait for completion. Parse:

```bash
SCORE_VALIDATE_AFTER=$(extract_score .claude/audits/VALIDATE.md)
```

Note: VALIDATE has no `_BEFORE` (first run is post-deploy). The before/after
table for VALIDATE shows `—` for before, `<score>` for after.

If /web-validate produced new fixes in source code, run STEP 5 again (mini-commit
+ push) BEFORE moving to STEP 8 — but DO NOT loop /web-validate. The remaining
deploy of those fixes is mentioned to the user in the final doc.

---

## STEP 8 — GATE EVALUATION

Compute final score table.

**Web project:**

| Audit             | Before                    | After                       | Status            |
|-------------------|---------------------------|-----------------------------|-------------------|
| SEO (classique)   | `SCORE_SEO_BEFORE`/20     | `SCORE_SEO_AFTER`/20        | ✅ ≥17 / ❌ <17    |
| GEO (IA)          | `SCORE_GEO_BEFORE`/20     | `SCORE_GEO_AFTER`/20        | ✅ ≥17 / ❌ <17    |
| HARDEN            | `SCORE_HARDEN_BEFORE`/20  | `SCORE_HARDEN_AFTER`/20     | ✅ ≥17 / ❌ <17    |
| VALIDATE          | —                         | `SCORE_VALIDATE_AFTER`/20   | ✅ / ❌ / SKIPPED   |

SEO classique and GEO (IA) are gated independently — both must reach
≥17/20. Reaching the GEO threshold is harder than SEO classique on
many sites because AI-extraction signals (llms.txt, Speakable, QAPage,
entity SEO) are still emerging — expect more fix-loop iterations on
GEO than on SEO.

**Non-web project:**

| Audit    | Before                    | After                  | Status         |
|----------|---------------------------|------------------------|----------------|
| CSO      | `SCORE_CSO_BEFORE`/20     | `SCORE_CSO_AFTER`/20   | ✅ ≥17 / ❌ <17 |

### Gate rule

An axis PASSES if:
- `AFTER ≥ 17/20` (nominal), **OR**
- **code-ceiling pass**: `AFTER ≥ (PROJECTED_CODE − 0.2)` AND the
  analyzer's trajectory names the residual gap as user-bound — i.e.
  every code-fixable point has been taken and what remains (GMB,
  citations, reviews, backlinks, Wikidata, AI-visibility outcomes) is
  by definition the CLIENT's work, not the codebase's. In that case
  the gap items MUST land verbatim in the client doc §5 ("Ce qui vous
  reste à faire", sourced from `.claude/audits/HUMAN-ACTIONS.md`) with
  their expected score gain — the deliverable ships with an honest
  "here is what only you can unlock" section instead of being blocked
  forever by points the code cannot reach.

Web: `ALL_PASS = PASS(SEO) AND PASS(GEO) AND PASS(HARDEN) AND (PASS(VALIDATE) OR VALIDATE_SKIPPED)`

Non-web: `ALL_PASS = PASS(CSO)`

HARDEN and VALIDATE have no user-bound axes (headers, markup, a11y are
all code/config) — for them the code-ceiling pass effectively never
applies; a below-17 HARDEN/VALIDATE is always code-blocked and stops
the pipeline. Every code-ceiling pass is listed in the §2 score table
with an explicit `✅ plafond code (X.X atteint / 17 requiert client)`
status — never silently presented as a nominal pass.

**GEO gate note**: `SCORE_GEO_AFTER = "UNKNOWN"` is treated as **fail** —
this typically happens when the SEO subagent produced a legacy single-score
SEO.md without the labeled `Score GEO (IA)` line. The orchestrator
re-dispatches the SEO subagent with an explicit instruction to emit both
labeled lines (see "Threshold strictness" below).

### Threshold strictness

Use the raw normalized score. **No rounding.** 16.9/20 fails. 17.0/20 passes.
A score reported as `UNKNOWN` (no parseable score line in the audit
file) is treated as **fail** — re-dispatch the audit subagent with an
explicit instruction to add the score lines and re-run the audit.
Do not assume a passing score.

For `.claude/audits/SEO.md` specifically, the re-dispatch must demand
**both** labeled lines:
- `Score SEO (classique) : X.X / 20`
- `Score GEO (IA) : X.X / 20`

A single generic `Score: X/20` line is insufficient — the gate will
still mark `SCORE_GEO_AFTER = UNKNOWN` and fail.

For `.claude/audits/HARDEN.md` and `.claude/audits/CSO.md`, a single
`Score: X/20` (or `X/100`) at the top of the report is sufficient.

### Override transparency

If the user chose option C (override threshold) at any STEP 4 escalation,
write `.claude/audits/THRESHOLD-OVERRIDE.md` documenting:
- Which audit(s) were overridden — for the SEO+GEO loop, list the axes
  separately (e.g. `SEO classique: NOT overridden, GEO (IA): overridden`)
- Final score reached vs threshold
- Top 3 unresolved issues per axis
- User's stated reason

This file is referenced in §5 of the client doc ("Ce qui vous reste à faire")
so the client knows what's still below the bar.

If `ALL_PASS = false`:

1. Generate `.claude/audits/HANDOVER-ROADMAP.md` (analysis of what's
   blocking each below-threshold audit — see structure below). Split
   every below-threshold axis in two labeled lists using the analyzers'
   `fixable:` tags: **CODE-BLOQUÉ** (bundle/GATED items not yet applied,
   additional code opportunities from the trajectory) vs **CLIENT-BLOQUÉ**
   (user-bound actions with expected gain — mirror of HUMAN-ACTIONS.md).
   A failed axis whose list is 100 % client-bloqué should not happen
   (the code-ceiling pass covers it) — if it does, flag the gate logic.
2. Append checklist entries to `.claude/tasks/TODO.md`.
3. **Do NOT generate the client doc**. Report to the user:

```
PIPELINE STOPPED — gate failed.

Score table:
<the table above>

Below-threshold audits:
- SEO (classique): <score>/20 — <top 3 remaining issues, one-line each>
- GEO (IA): <score>/20 — <top 3 remaining issues, one-line each>
- HARDEN: <score>/20 — <top 3 remaining issues>
- VALIDATE: <score>/20 — <top 3 remaining issues>

Roadmap written to .claude/audits/HANDOVER-ROADMAP.md.
Tasks appended to .claude/tasks/TODO.md.

Resolve P0 items, then re-run /client-handover.
```

If `ALL_PASS = true` → proceed to STEP 9 (memory load + doc generation).

### Roadmap structure (when gate fails)

```markdown
# Handover Roadmap — <project name>

Generated: YYYY-MM-DD HH:MM
Trigger: per-audit threshold violated (rule: every audit must be ≥17/20)

## Score breakdown

| Audit             | Before | After | Δ   | Status            |
|-------------------|--------|-------|-----|-------------------|
| SEO (classique)   | 14.4   | 16.2  | +1.8| ❌ BELOW_THRESHOLD |
| GEO (IA)          | 11.0   | 13.5  | +2.5| ❌ BELOW_THRESHOLD |
| HARDEN            | 12.0   | 18.0  | +6.0| ✅ OK              |
| VALIDATE          | —      | 15.5  | —   | ❌ BELOW_THRESHOLD |

## Remaining issues per audit

### SEO classique (<score>/20)

[Extract from `.claude/audits/SEO.md` — the SEO classical issues NOT
auto-fixed. Sort by score-gain potential. For each:]

1. [TYPE] short title
   - File: `path:line`
   - Fix: <one sentence>
   - Score gain: +X.X/20
   - Why automatic fix didn't work: <reason — needs judgment, external account, manual content>

### GEO / IA (<score>/20)

[Extract from `.claude/audits/SEO.md` (GEO sections — §7.x) — the GEO
issues NOT auto-fixed. Same per-item format as SEO above. GEO is
gated independently at ≥17/20; below-threshold GEO blocks the handover
just like SEO classique. Common GEO blockers: missing llms.txt /
llms-full.txt, AI crawler robots.txt rules absent, no Schema.org for
AI extraction (QAPage, Speakable, HowTo, Organization graph), no
entity links (sameAs, Wikidata @id), content shape unsuited for LLM
extraction (no TL;DR, no definition lead, no Q→A blocks).]

### HARDEN (<score>/20)
... (same format)

### VALIDATE (<score>/20)
... (same format)

## Action plan

P0 (do first — bring scores ≥17/20):
- [ ] [SEO][...] ...
- [ ] [HARDEN][...] ...

P1 (after threshold passed):
- [ ] ...

P2 (manual / requires user input):
- [ ] ...

## How to use

1. Tackle P0 with dev team.
2. Re-run /client-handover — pipeline restarts from baseline audits.
3. P2 items go to client (will appear in handover doc once gate passes).
```

---

## STEP 9 — DOC-GEN ORCHESTRATION (resolve → assemble → delegate)

(Only reached when STEP 8 gate passes.)

The document itself — memory/git synthesis, the 6-chapter content, the
three content gates, and the branded HTML/PDF render — is no longer
produced here. That work moved to the sonnet `handover-doc-writer`
subagent. This step's job is narrower: resolve every interactive
decision and every detected fact that agent needs, assemble them into
one PACKAGE, and dispatch. Nothing below writes or renders the
deliverable.

### 9.1 — Q1 deploy chapter + Q2 language confirm

**Q1 — Deploy chapter (default = SKIP).**

**Default behavior**: deploy chapter is **NOT included**. Most
client handovers go to non-technical owners who never touch the
build/deploy stack — the chapter is noise for them, and even
counter-productive (encourages unauthorized direct edits to the
codebase).

Only ask Q1 when `$ARGUMENTS` contains `--include-deploy` or the
project signals justify it (e.g., `CLAUDE.md` explicitly mentions
"client autonome", "self-hosted by client", "no dev maintenance",
or the project README documents a hand-off intent). Even then,
re-confirm before including.

**No flag, no signal → skip silently** (do not even ask). Set
`INCLUDE_DEPLOY=no`.

If `--include-deploy` IS present, set `INCLUDE_DEPLOY=yes` without
further prompting.

If signals justify asking:

```
Re-grounding: project = <name>, branch = <current>, all audits passed
(web: SEO classique <score>/20, GEO IA <score>/20, HARDEN <score>/20,
VALIDATE <score>/20 | non-web: CSO <score>/20). Generating client
handover document.

Le client va recevoir un document qui explique ce qui a été fait. Tu veux
qu'on ajoute aussi un chapitre qui lui explique comment construire et
déployer le site lui-même (build, mise en ligne, mise à jour) ? Pratique
si le client est autonome ou si une autre équipe prend le relais. À éviter
si tu déploies pour lui.

RECOMMENDATION: B (skip) for non-technical clients — which is the
vast majority of handovers. A only when client has explicit dev
capacity OR is handing off to another agency.

Options:
- A) Yes — include build & deploy chapter
- B) No — skip the deploy chapter (default, recommended for non-tech clients)
```

(Translate to English if `LANG=en`.) On A → `INCLUDE_DEPLOY=yes`. On B →
`INCLUDE_DEPLOY=no`.

**Q2 — Output language confirmation** (only if the STEP 2 auto-detection
was ambiguous). Skip if confident. Only ask if ambiguous. The resolved
value feeds `LANG` in the PACKAGE.

### 9.2 — Build the §4 NAP table

Resolves the VALUES the doc-writer renders — the doc-writer does not
detect or prompt for any of these itself.

Auto-detection rules, in order (stop at the first positive match per
field): **`.claude/audits/NAP-KIT.md` FIRST when present** — it is the
user-confirmed canonical NAP produced by /seo (LRN-032: on-site
sources may all share one wrong seed; the kit is the only
user-validated source). Fields marked `UNCONFIRMED` there stay
`[À COMPLÉTER]`. Only when no NAP-KIT exists, fall back to:
`CLAUDE.md`, `.claude/memory/` journal/decisions, `README.md`, first
commits, and the live site. Do NOT invent SIRET, GPS, or legal name —
those are too risky to fake; leave `[À COMPLÉTER]` if unconfirmed.

Resolve each field: `nom_commercial`, `nom_legal`, `adresse`,
`telephone`, `email`, `site_web`, `siret`, `tva`, `gps`,
`categorie_principale`, `categories_secondaires`,
`description_courte` (auto-detect from site hero / meta description /
og:desc / llms.txt / JSON-LD `LocalBusiness.description`), `horaires`.

**`nom_commercial` is the one field that must not ship as
`[À COMPLÉTER]`** — the deliverable's cover page and §1 brief depend on
it. If the detection above doesn't confirm it, ask:

```
AskUserQuestion:
  "Quel est le nom commercial exact du client, tel qu'il doit
   apparaître partout (Google Business, factures, document de
   livraison) ?"
```

Every other field that can't be confirmed stays `[À COMPLÉTER]` — the
doc-writer renders it as-is and flags it in its own report; do not
invent a value here.

### 9.3 — Platform precheck detection (§5 / §7 checkboxes)

Skip if `PROJECT_TYPE != web`. Produces `PRECHECK_DONE` — the
platforms already confirmed done, so the doc-writer pre-checks the
matching boxes instead of leaving everything unchecked.

**Scope.**

**INCLUDE** (auto-pre-check candidates):
- §5 "Une fois — à faire dans..." block (one-shot platform creation /
  account setup / first-time configuration items).
- §7.1 / §7.2 / §7.3 / §7.4 / §7.5 — top-level "Fiche créée" /
  "Compte créé" / "Page créée" rows.

**EXCLUDE** (always leave unchecked):
- §5 "Mensuel", "Trimestriel", "Annuel", "Quand quelque chose change"
  cadences (recurring, never "done").
- §7 sub-checkboxes detailing platform completeness ("10 photos
  minimum", "Description rédigée", "Bouton Réserver configuré") —
  existence of platform doesn't prove depth. Leave for client.
- Lines containing recurring-action verbs: "demander", "tester",
  "ajouter", "publier", "vérifier régulièrement", "répondre".

**Detection signals** (apply in order, stop at first positive match):

For each in-scope checkbox, attempt to confirm "done" via:

1. **Project docs** — grep `CLAUDE.md`, `README.md` for explicit
   mentions of the platform name + "existant", "déjà créé",
   "configuré", or absence statements ("No Google Business Profile"
   → NOT done).
2. **`.claude/memory/` registries** — search `decisions.md`,
   `learnings.md`, `journal.md` for setup confirmation entries
   (BDR / LRN / journal date heading).
3. **Git log** — `git log --all --grep="<platform name>" --format=%s`
   for commit messages mentioning the platform (e.g., "Bing Places
   import done").
4. **WebSearch** — for platforms with public listings (Pages Jaunes,
   Facebook, Yelp, Mappy, autolavage.net, sectoral directories):

   ```
   WebSearch: "<business name>" "<city>" <platform>
   ```

   Confirm done if the search returns the actual business listing
   matching the platform's URL pattern. **Capture the public URL** —
   carried in `PRECHECK_DONE` so the doc-writer can insert it as
   evidence (`Fiche en ligne : https://...`).
5. **Unknown** — couldn't confirm via 1-4 → add to `UNKNOWNS` list.

**Batch unknowns via AskUserQuestion.**

Group `UNKNOWNS` into themed batches (max 4 questions, max 4 options
each, `multiSelect: true`). Suggested groupings:
- "Plateformes prioritaires" (GBP, Apple, Bing, PJ)
- "Réseaux sociaux" (FB, IG, TikTok, Yelp)
- "Cartographie + sectoriels" (Mappy, Vroomly, Foursquare, Trustpilot)
- "Annuaires généralistes" (Justacote, Hoodspot, Le Bottin, Nextdoor)

Items the user selects → mark done. Items the user does NOT select →
stay unchecked. If `UNKNOWNS` is empty, skip (no questions asked).

`PRECHECK_DONE` = the final list of confirmed-done platforms/items
(name + evidence URL when captured via WebSearch).

### 9.4 — Resolve OUTPUT (path + overwrite decision)

```bash
OUTPUT_PATH="LIVRAISON.md"; [ "$LANG" = "en" ] && OUTPUT_PATH="HANDOVER.md"
# honor --output <path> from $ARGUMENTS if present
test -f "$OUTPUT_PATH" && echo EXISTS
```

If the target file does not exist → `OUTPUT = overwrite <OUTPUT_PATH>`
(nothing to ask; it's a fresh write). If it exists, ask:

```
AskUserQuestion:
  "A file already exists at <OUTPUT_PATH>."
  - A) Overwrite (recommended if previous version is stale)
  - B) Save as `LIVRAISON-YYYY-MM-DD.md` (versioned)
  - C) Skip writing — display in conversation only
```

Resolve `OUTPUT` = `overwrite <path>` | `versioned <path>` |
`skip-write`, per the answer.

### 9.5 — Resolve CLIENT_NAME

Detect (first positive match wins): earliest heading in
`.claude/memory/journal.md` (the client is often named in the first
session's journal line), then `README.md`. If still unknown after
best-effort detection, ask once:

```
AskUserQuestion: "Nom du client à afficher sur la couverture du PDF
(ou laisser vide pour ne rien afficher)?"
```

A blank answer becomes `—`.

### 9.6 — Assemble the PACKAGE and dispatch

Every field below is either already computed in STEP 1–8 (reference
it, don't recompute) or resolved in 9.1–9.5:

- `LANG` — STEP 2 language detection (confirmed/overridden by Q2).
- `PROJECT` — `name` (STEP 1 `PROJECT_ROOT` basename, or `package.json`
  `name` if present), `root` (`PROJECT_ROOT`), `type` (`PROJECT_TYPE`),
  `sub-type` (STEP 2 web sub-type classification, `—` if non-web),
  `is_local_business` (`IS_LOCAL_BUSINESS`), `deployed_url`
  (`DEPLOYED_URL`), `period` (`FIRST_COMMIT_DATE` → `LAST_COMMIT_DATE`,
  reformatted DD/MM/YYYY).
- `SCORES` — `SCORE_SEO_BEFORE/AFTER`, `SCORE_GEO_BEFORE/AFTER`,
  `SCORE_HARDEN_BEFORE/AFTER`, `SCORE_VALIDATE_AFTER` (web) or
  `SCORE_CSO_BEFORE/AFTER` (non-web), each with the pass-status and
  any code-ceiling note from the STEP 8 gate table.
- `AUDIT_REPORTS` — `.claude/audits/SEO.md`, `.claude/audits/HARDEN.md`,
  `.claude/audits/VALIDATE.md` (or `.claude/audits/CSO.md` non-web),
  plus `.claude/audits/HUMAN-ACTIONS.md` and
  `.claude/audits/THRESHOLD-OVERRIDE.md` when present.
- `INCLUDE_DEPLOY` — from 9.1.
- `DEPLOY_HINTS` — the `DEPLOY_HINTS` array detected in STEP 2 (empty if
  none), forwarded as a comma-separated list so the doc-writer can
  tailor §8. Only consumed when `INCLUDE_DEPLOY=yes`.
- `SKIP_SEO` — `yes` if `$ARGUMENTS` contained `--skip-seo` (STEP 0 flag
  parse), else `no`. Gates the doc-writer's §7 platforms chapter.
- `NAP` — from 9.2.
- `PRECHECK_DONE` — from 9.3.
- `CLIENT_NAME` — from 9.5.
- `OUTPUT` — from 9.4.

If `OUTPUT` resolved to `skip-write`, still dispatch — the doc-writer
reports `MD: skipped` and stops before rendering, per its own
contract.

Dispatch the two-mode pipeline (BDR-077 — synthesis on opus, render on the
sonnet pin, full PACKAGE both times per LRN-126). Mint a RUNID first
(`RUNID=$(date +%s)`); the draft crosses via the run-scoped, gitignored
`.audit/handover-draft-<RUNID>.md`; clean it after 9.7.

FIRST — synthesize:

```
Agent(subagent_type="handover-doc-writer", model="opus")
prompt: "MODE: synthesize
RUNID: <RUNID>
PACKAGE:
<the FULL PACKAGE block below>"
```

Parse its `SYNTH REPORT`: `STATUS: BLOCKED` → surface verbatim, stop (do
not patch the PACKAGE silently); malformed/mute → retry ONCE fresh, then
escalate. `STATUS: DONE` → THEN render:

```
Agent(subagent_type="handover-doc-writer")
prompt: "MODE: render
RUNID: <RUNID>
PACKAGE:
LANG: <LANG>
PROJECT: name=<name> root=<root> type=<type> sub-type=<sub-type>
  is_local_business=<bool> deployed_url=<url> period=<first→last>
SCORES: seo=<before→after,status> geo=<before→after,status>
  harden=<before→after,status> validate=<after,status>
  [cso=<before→after,status> for non-web] [code-ceiling notes]
AUDIT_REPORTS: <paths>
INCLUDE_DEPLOY: <yes|no>
DEPLOY_HINTS: <comma-separated list from STEP 2, or empty>
SKIP_SEO: <yes|no>
NAP: <resolved table, field by field>
PRECHECK_DONE: <list>
CLIENT_NAME: <name|—>
OUTPUT: <overwrite <path> | versioned <path> | skip-write>

Render the deliverable from the draft per your render-mode steps. Report
the HANDOVER-DOC REPORT."
```

(The PACKAGE block is IDENTICAL in both dispatches — write it once,
paste it twice. A render `STATUS: BLOCKED` on draft absence/RUNID
mismatch means the synthesize leg failed silently: re-run 9.6 from the
synthesize dispatch, never hand-write the draft.)

### 9.7 — Parse the report, tell the user

Parse the returned `HANDOVER-DOC REPORT`:

- `STATUS: DONE` → report the `MD` / `HTML` / `PDF` paths to the user,
  plus the `GATES` line and any `NOTES` caveats (e.g. `[À COMPLÉTER]`
  markers left in NAP, deploy chapter included/skipped).
- `STATUS: BLOCKED` → surface the report verbatim (including which
  PACKAGE field the doc-writer flagged) and stop — do not retry or
  patch the PACKAGE silently.

In BOTH branches, then clean the transient draft:
`rm -f ".audit/handover-draft-${RUNID}.md"` (run-scoped, gitignored —
cleanup keeps `.audit/` from accumulating stranded drafts).