@aegis-scan/skills 0.2.1 → 0.4.0

package/skills/foundation/aegis-native/aegis-customer-build/references/phase-6-mid-audit.md

@@ -0,0 +1,200 @@
+# Phase 6 Reference — Mid-Audit (AEGIS-Scan + Anwalt Spot-Check + Repair Loop)
+
+Phase 6 is MANDATORY. It catches regressions early — before Phase 7 has to find them in a fully-built artifact (which is more expensive to repair). **Time budget:** 20-30 min, plus repair iterations if any gates are red.
+
+**Subagent dispatch:** optional. If used, dispatch one Auditor-subagent (model: opus) to run the audits in parallel with Phase 5's tail-end integrations.
+
+---
+
+## Mid-Audit Scope
+
+Phase 6 runs a SUBSET of the final-verify gates — the cheap ones that catch most regressions:
+
+| Gate | Mid-audit threshold | Final-verify threshold |
+|---|---|---|
+| build | exit 0 | exit 0 |
+| tsc | 0 errors | 0 errors |
+| lint | 0 errors | 0 errors |
+| tests | 100% pass | 100% pass |
+| aegis-scan | score ≥ 900 | score ≥ 950 |
+| brutaler-anwalt (HUNT mode, topic-scoped) | 0 KRITISCH | 0 KRITISCH, ≤ 2 HOCH |
+| Lighthouse | _(skipped — too slow for mid)_ | mobile ≥ 75, desktop ≥ 90 |
+| skillforge-validate | _(N/A unless skills touched)_ | 16/17+ per touched skill |
+| briefing-coverage | _(skipped — pages still being filled)_ | 100% |
+
+**Rationale:** the cheap gates (build/tsc/lint/tests/aegis-scan + scoped anwalt) catch ≥ 80% of regressions. Lighthouse + briefing-coverage are deferred to Phase 7 because they require a fully-built artifact.
+
+---
+
+## AEGIS-Scan Invocation Pattern
+
+Mid-audit AEGIS-scan runs against the local dev-build:
+
+```bash
+# Build first (or run dev-server)
+cd customers/<slug>
+pnpm run build
+pnpm run start &        # or: pnpm dev
+SERVER_PID=$!
+
+# Wait for server-ready (max 30s)
+until curl -sf http://localhost:3000 > /dev/null; do sleep 1; done
+
+# Run scan
+npx -y @aegis-scan/cli scan http://localhost:3000 \
+  --output ./audits/mid-audit-aegis.json \
+  --format json
+
+kill $SERVER_PID
+```
+
+Parse the JSON:
+
+```ts
+const result = JSON.parse(readFileSync('./audits/mid-audit-aegis.json'));
+if (result.score < 900 || result.grade === 'F') {
+  // RED — repair-attempt loop
+}
+```
+
+---
+
+## Brutaler-Anwalt HUNT-Mode Pattern
+
+Mid-audit anwalt run is SCOPED — focuses on the most regression-prone topics, not the full 8-layer audit:
+
+```
+Invoke: compliance/aegis-native/brutaler-anwalt skill in HUNT mode
+Topics: impressum + cookie + dse (the bug-prone surface)
+Target: http://localhost:3000
+Output: customers/<slug>/audits/mid-audit-anwalt.md
+Format: 4-section (Schadens-Diagnose / Findings / Anwalts-Anhang / Abmahn-Simulation)
+```
+
+**Skill-invocation pattern** (Claude Code):
+
+```
+Skill: compliance/aegis-native/brutaler-anwalt
+Args: --mode=hunt --topics=impressum,cookie,dse --target=http://localhost:3000
+```
+
+Or via CLI:
+
+```bash
+npx -y @aegis-scan/skills run compliance/brutaler-anwalt \
+  --mode=hunt \
+  --topics=impressum,cookie,dse \
+  --target=http://localhost:3000 \
+  --output=./audits/mid-audit-anwalt.md
+```
+
+---
+
+## Repair-Attempt Loop
+
+If any gate is red, enter repair-attempt loop:
+
+```
+attempts=0
+while [ $attempts -lt 3 ]; do
+  attempts=$((attempts+1))
+  
+  # Identify failing gates
+  failing=$(jq -r '.gates_failed[]' .aegis/state.json)
+  
+  # For each failing gate:
+  for gate in $failing; do
+    case $gate in
+      tsc)         repair_tsc_errors    ;;
+      lint)        repair_lint_errors   ;;
+      tests)       repair_test_failures ;;
+      aegis-scan)  repair_aegis_findings ;;
+      anwalt)      repair_anwalt_findings ;;
+    esac
+  done
+  
+  # Re-run mid-audit
+  re_run_mid_audit
+  
+  # Check if all gates green now
+  if all_gates_green; then
+    break
+  fi
+done
+
+if [ $attempts -ge 3 ] && ! all_gates_green; then
+  echo "Mid-audit INCOMPLETE after 3 repair-attempts"
+  echo "Open: $(jq -r '.gates_failed[]' .aegis/state.json)"
+  # escalate to Phase 7 with explicit INCOMPLETE-Status
+fi
+```
+
+**Repair-action mapping:**
+
+| Failing gate | Common cause | Repair-action |
+|---|---|---|
+| tsc | Missing prop type, undefined import | Find file, add type annotation |
+| lint | Unused var, missing dep | Auto-fix via `pnpm run lint --fix` |
+| tests | New code lacks test, broken existing test | Either write missing test or fix code |
+| aegis-scan: T1 (DNS) | Missing DNSSEC / CAA | Operator-action (DNS-level) — report as DEFER |
+| aegis-scan: T1 (HTTP-headers) | Missing CSP / HSTS / X-Frame | Add to next.config.js or middleware |
+| aegis-scan: T2 (HTML) | Missing alt-text / heading-hierarchy | Edit page.tsx |
+| aegis-scan: T3 (Impressum) | Footer-link missing / 404 | Fix footer-link |
+| anwalt KRITISCH (Impressum) | DDG §5 fields missing | Add to /impressum page |
+| anwalt KRITISCH (Cookie) | Pre-consent tracker | Move tracker behind cookie-banner |
+| anwalt KRITISCH (DSE) | Missing Art. 13 fields | Update /datenschutz page |
+
+---
+
+## State.json Update per Repair-Attempt
+
+```json
+{
+  "phase": 6,
+  "status": "in-repair",
+  "attempts": 2,
+  "max_attempts": 3,
+  "mid_audit_score": 887,
+  "mid_audit_grade": "B+",
+  "gates_failed": ["aegis-scan:t1-headers", "anwalt:cookie-banner-pre-checked"],
+  "repairs_applied": [
+    {"gate": "tsc:missing-import", "fix": "add 'import { Hero }' in app/page.tsx", "result": "passed"},
+    {"gate": "anwalt:impressum-missing-vat-id", "fix": "added VAT-ID to footer", "result": "passed"}
+  ],
+  "next_action": "repair-attempt-3"
+}
+```
+
+---
+
+## Phase 6 Completion Criteria
+
+Mid-audit is complete when EITHER:
+
+- All mid-audit gates green (proceed to Phase 7)
+- 3 repair-attempts exhausted with red gates remaining (proceed to Phase 7 with INCOMPLETE-Status flagged)
+
+NEVER proceed to Phase 7 without writing the mid-audit checkpoint:
+
+```json
+{
+  "phase": 6,
+  "status": "complete-green" | "complete-incomplete",
+  "mid_audit_score": <N>,
+  "mid_audit_grade": "<G>",
+  "anwalt_findings": {"kritisch": <N>, "hoch": <N>, "mittel": <N>},
+  "open_after_repair": [<list>]
+}
+```
+
+---
+
+## Anti-Patterns specific to Phase 6
+
+- ❌ Skipping mid-audit "to save time" — Phase 6 catches > 80% of regressions cheaper than Phase 7 would.
+- ❌ Running full 9-gate sweep in mid-audit — too slow; mid-audit is a subset.
+- ❌ Looping repair-attempts beyond 3 — diminishing returns; escalate to Phase 7 with INCOMPLETE.
+- ❌ Marking phase 6 complete without writing the checkpoint — next agent (or Phase 7 itself) loses context.
+- ❌ Repairing only the first failing gate and re-running — repair all failing gates per attempt, then re-run once.
+- ❌ Inferring repair-actions from chat-context — read the gate-output (JSON for aegis-scan, MD for anwalt), don't guess.
+- ❌ Ignoring brutaler-anwalt HOCH findings as "not blocking mid-audit" — track in checkpoint; final pass must address them.

package/skills/foundation/aegis-native/aegis-customer-build/references/phase-7-final-verify.md

@@ -0,0 +1,258 @@
+# Phase 7 Reference — Final-Verify (9-Gate Loop + Briefing-Coverage + Status-Report)
+
+Phase 7 is the final pass. All 9 quality-gates run. Briefing-coverage check. Lighthouse mobile + desktop. Final brutaler-anwalt full-pass. Status-report DONE or INCOMPLETE. **Time budget:** 30-45 min plus repair-iterations if needed.
+
+---
+
+## The 9 Gates (full-final mode)
+
+Per `aegis-quality-gates` skill, the canonical sequence:
+
+| # | Gate | Threshold | When red, action |
+|---|---|---|---|
+| 1 | build | exit 0 | Fix compile error, re-run |
+| 2 | tsc | 0 errors | Fix type error, re-run |
+| 3 | lint | 0 errors | Auto-fix or manual fix |
+| 4 | tests | 100% pass | Fix test or fix code |
+| 5 | aegis-scan | score ≥ 950, grade S/FORTRESS | Identify failing tier, repair, re-scan |
+| 6 | brutaler-anwalt full-pass | 0 KRITISCH, ≤ 2 HOCH | Fix legal-finding, re-run |
+| 7 | lighthouse | Mobile ≥ 75, Desktop ≥ 90, A11y/SEO/BP = 100 | Optimize, re-run |
+| 8 | skillforge-validate | 16/17+ per touched skill | Fix skill-structure, re-validate |
+| 9 | briefing-coverage | 100% pages exist | Build missing page, re-check |
+
+Each gate writes a structured result to `.aegis/verify-report.json`. The post-build status-report reads from this JSON.
+
+---
+
+## Gate 9: Briefing-Coverage Check
+
+The most foundation-specific gate. Verifies every page in the briefing exists in the artifact.
+
+```ts
+// scripts/check-briefing-coverage.ts
+import { readFileSync, existsSync } from 'node:fs';
+
+const briefing = JSON.parse(readFileSync('.aegis/briefing-parsed.json', 'utf-8'));
+const expectedPages = briefing.pages;
+const missing: string[] = [];
+const incomplete: string[] = [];
+
+for (const page of expectedPages) {
+  const filePath = page.slug === 'home' 
+    ? 'app/page.tsx' 
+    : `app/${page.slug}/page.tsx`;
+  
+  if (!existsSync(filePath)) {
+    missing.push(`${page.slug}: file not found at ${filePath}`);
+    continue;
+  }
+  
+  const content = readFileSync(filePath, 'utf-8');
+  
+  // Verify metadata exported
+  if (!content.includes('export const metadata') && !content.includes('export async function generateMetadata')) {
+    incomplete.push(`${page.slug}: missing metadata export`);
+  }
+  
+  // Verify each section in briefing.sections[] is present
+  for (const section of page.sections) {
+    if (!sectionPresent(content, section)) {
+      incomplete.push(`${page.slug}: section "${section}" not found in JSX`);
+    }
+  }
+}
+
+if (missing.length || incomplete.length) {
+  console.error('Briefing-coverage RED:', { missing, incomplete });
+  process.exit(1);
+}
+console.log(`Briefing-coverage OK: ${expectedPages.length}/${expectedPages.length} pages`);
+```
+
+`sectionPresent` is a heuristic: looks for component-name-match or comment-marker. Customize per project's library naming.
+
+---
+
+## Lighthouse Invocation (Mobile + Desktop)
+
+```bash
+# Build production
+cd customers/<slug>
+pnpm run build
+pnpm run start &
+SERVER_PID=$!
+until curl -sf http://localhost:3000 > /dev/null; do sleep 1; done
+
+# Mobile
+npx -y @lhci/cli@latest collect \
+  --url=http://localhost:3000 \
+  --settings.preset=mobile \
+  --output-path=./audits/lhci-mobile.json
+
+# Desktop
+npx -y @lhci/cli@latest collect \
+  --url=http://localhost:3000 \
+  --settings.preset=desktop \
+  --output-path=./audits/lhci-desktop.json
+
+kill $SERVER_PID
+
+# Parse
+node scripts/parse-lhci.mjs ./audits/lhci-mobile.json ./audits/lhci-desktop.json
+```
+
+`parse-lhci.mjs`:
+
+```js
+import { readFileSync } from 'node:fs';
+
+const mobile = JSON.parse(readFileSync(process.argv[2]));
+const desktop = JSON.parse(readFileSync(process.argv[3]));
+
+const m = mobile.lhr.categories;
+const d = desktop.lhr.categories;
+
+const result = {
+  mobile: {
+    performance: Math.round(m.performance.score * 100),
+    accessibility: Math.round(m.accessibility.score * 100),
+    seo: Math.round(m.seo.score * 100),
+    bestPractices: Math.round(m['best-practices'].score * 100),
+  },
+  desktop: {
+    performance: Math.round(d.performance.score * 100),
+    accessibility: Math.round(d.accessibility.score * 100),
+    seo: Math.round(d.seo.score * 100),
+    bestPractices: Math.round(d['best-practices'].score * 100),
+  },
+};
+
+const fails: string[] = [];
+if (result.mobile.performance < 75) fails.push(`mobile.performance ${result.mobile.performance} < 75`);
+if (result.desktop.performance < 90) fails.push(`desktop.performance ${result.desktop.performance} < 90`);
+if (result.mobile.accessibility < 100) fails.push(`mobile.a11y ${result.mobile.accessibility} < 100`);
+// ... etc
+
+console.log(JSON.stringify(result, null, 2));
+if (fails.length) {
+  console.error('Lighthouse RED:', fails);
+  process.exit(1);
+}
+```
+
+---
+
+## Final Brutaler-Anwalt Full-Pass
+
+Unlike Phase 6's HUNT-mode (topic-scoped), Phase 7 runs the FULL 8-layer audit:
+
+```bash
+npx -y @aegis-scan/skills run compliance/brutaler-anwalt \
+  --mode=full \
+  --target=http://localhost:3000 \
+  --output=./audits/final-anwalt.md \
+  --format=4-section
+```
+
+Output is the canonical 4-section format:
+
+1. **Schadens-Diagnose** — top-level summary with €-range estimate.
+2. **Findings-Tabelle** — detailed per-finding (severity, layer, evidence, fix-suggestion).
+3. **Anwalts-Anhang** — legal citations (Art. paragraph + court-decision references).
+4. **Abmahn-Simulation** — likelihood × industry × visibility = probable cost.
+
+**Final-pass thresholds:**
+
+- 0 KRITISCH (any KRITISCH = INCOMPLETE-Status)
+- ≤ 2 HOCH (each HOCH explicitly listed in status-report)
+- MITTEL + LOW: tracked but non-blocking
+
+If KRITISCH found: enter repair-attempt-loop (max 3) for KRITISCH-only. HOCH/MITTEL are post-launch-tasks.
+
+---
+
+## .aegis/verify-report.json Schema
+
+```json
+{
+  "timestamp": "2026-04-28T14:00:00Z",
+  "project_slug": "test-customer-001",
+  "status": "DONE" | "INCOMPLETE",
+  "gates": {
+    "build": {"pass": true, "duration_ms": 8421},
+    "tsc": {"pass": true, "errors": 0},
+    "lint": {"pass": true, "errors": 0},
+    "tests": {"pass": true, "passed": 145, "total": 145},
+    "aegis_scan": {"pass": true, "score": 994, "grade": "S", "bracket": "FORTRESS"},
+    "anwalt": {"pass": true, "kritisch": 0, "hoch": 1, "report": "audits/final-anwalt.md"},
+    "lighthouse": {
+      "pass": true,
+      "mobile": {"performance": 82, "accessibility": 100, "seo": 100, "best_practices": 100},
+      "desktop": {"performance": 95, "accessibility": 100, "seo": 100, "best_practices": 100}
+    },
+    "skillforge_validate": {"pass": true, "skills_validated": []},
+    "briefing_coverage": {"pass": true, "expected": 13, "actual": 13, "missing": []}
+  },
+  "open_items": []
+}
+```
+
+If `status: INCOMPLETE`, `open_items` lists every failing gate-item with severity.
+
+---
+
+## Status-Report Format (post-build)
+
+The customer-build SKILL.md's Process specifies the canonical text. Phase 7 generates it from `.aegis/verify-report.json`:
+
+**DONE template:**
+
+```
+Bin fertig, Chef.
+- Site unter customers/<slug>/
+- AEGIS Score: <score>/<grade>/<bracket>
+- Lighthouse: Mobile <m_perf>/Desktop <d_perf> (A11y/SEO/BP all <100|99>)
+- brutaler-anwalt: <kritisch> KRITISCH, <hoch> HOCH
+- Briefing-Coverage: <built>/<expected> pages (<pct>%)
+- Audit-Report: customers/<slug>/audits/final.md
+- Bereit für deploy.
+```
+
+**INCOMPLETE template:**
+
+```
+BUILD INCOMPLETE — folgende Items offen:
+- [ ] aegis-scan score 928 < 950 (target). Failing tier: T1-DNS-NO-DNSSEC.
+- [ ] anwalt KRITISCH 1: Impressum fehlt VAT-ID (line 47 of /impressum/page.tsx)
+- [ ] briefing-coverage 12/13 — fehlt: page "blog/karriere" (briefing line 412)
+- [ ] lighthouse mobile.performance 67 < 75. Hauptursache: LCP > 4s.
+Repair-attempt-Count: 3/3 erschöpft.
+Empfehlung: Operator-Eingriff für T1-DNS (DNS-level), VAT-ID-Eintrag, blog/karriere-page-Build, LCP-Optimierung.
+```
+
+Always exact, with concrete file/line/page references.
+
+---
+
+## Phase 7 Completion Criteria
+
+- [ ] All 9 gates ran (no skipping)
+- [ ] `.aegis/verify-report.json` written
+- [ ] Audit-report `audits/final.md` consolidated (combines AEGIS-scan + anwalt + lighthouse outputs)
+- [ ] Status-report printed to operator (DONE or INCOMPLETE template)
+- [ ] If DONE: state.json `status: DONE` set
+- [ ] If INCOMPLETE: state.json `status: INCOMPLETE`, `open_items[]` populated
+- [ ] Operator-actionable (operator can copy-paste status-report into deploy-tracker)
+
+---
+
+## Anti-Patterns specific to Phase 7
+
+- ❌ Reporting "DONE" with score < 950 (never round up)
+- ❌ Skipping any gate in final-verify (mid-audit subsetting was Phase 6)
+- ❌ Mocking Lighthouse run because "the dev-server isn't started" — start it, run real Lighthouse
+- ❌ Reporting briefing-coverage as 100% when one page is a stub (e.g., 50 chars of copy) — coverage requires meta + sections + content
+- ❌ Hiding HOCH findings in the status-report — every HOCH gets listed
+- ❌ Auto-deploying after DONE status without operator-confirm — deploy is an operator-action
+- ❌ Repair-attempt-loop running > 3 iterations on the same gate — escalate to INCOMPLETE
+- ❌ Skipping `.aegis/verify-report.json` — downstream tooling depends on it

package/skills/foundation/aegis-native/aegis-handover-writer/SKILL.md

@@ -0,0 +1,128 @@
+<!-- aegis-local: AEGIS-native skill, MIT-licensed; writes the structured session-end handover, captures progress + open items + skill-changes + recommendations, then updates the HANDOVER-LATEST.md symlink so the next agent starts with full context. Pattern ported from a private reference-implementation; this is the public OSS variant. -->
+---
+name: aegis-handover-writer
+description: Writes the session-end handover. Captures completed-work, quality-gate metrics, files changed, skill changes, open items 1/2/3, fallstricke, next steps, recommendations. Updates HANDOVER-LATEST.md symlink. Trigger keywords - handover, session-ende, fertig, übergabe, recap, abschluss.
+model: sonnet
+license: MIT
+metadata:
+  required_tools: "file-ops,shell-ops"
+  required_audit_passes: "0"
+  enforced_quality_gates: "0"
+  pre_done_audit: "false"
+---
+
+# aegis-handover-writer — Session-End Handover
+
+Writes a structured handover-file at `.claude/handover/HANDOVER-YYYY-MM-DD-<topic>.md` and updates `HANDOVER-LATEST.md` symlink. Continuous updates supported during long sessions (overwrite-or-append based on whether `HANDOVER-LATEST.md` already exists for today).
+
+---
+
+## HARD-CONSTRAINT — Handover-Completeness
+
+The handover-file MUST include all 8 sections listed under `## Verification / Success Criteria`. Skipping a section breaks the next agent's bootstrap. If a section legitimately has nothing to report (e.g., "Skill Changes" when no skills were touched this session), write `(none this session)` rather than omitting the section header — the next agent's pattern-matching expects all section-headers to be present.
+
+References + cross-links to the foundation spec (`seitengold/docs/2026-04-28-aegis-agent-foundation-design.md`) belong in `## Recommendations` if they affect the operator's next decisions, not buried in `## Status`.
+
+---
+
+## Mission
+
+Eliminate the "next agent starts blind" failure mode at session-boundaries. The handover-file IS the bootstrap-input for whoever opens the next session — Claude Code, Codex, or human operator. Quality of handover directly determines quality of next-session start.
+
+Plus: enable **continuous-handover** during long autonomous builds. Write incremental updates to `HANDOVER-LATEST.md` after each major phase, not just at session-end. If a long-running build crashes mid-Phase-3, the resume-agent finds the partial handover documenting Phase-1+2 already done.
+
+---
+
+## Triggers
+
+### Slash-commands
+
+- `/handover` — write session-end handover
+- `/übergabe` — alias
+- `/session-ende` — alias
+- `/recap` — alias
+
+### Auto-trigger keywords
+
+- handover, übergabe, session-ende, fertig, recap, abschluss, weitermachen-vorbereitung
+- Plus: when the orchestrator detects a phase-completion event in a long-running build
+
+### Continuous-update trigger
+
+When invoked with `--continuous` (or a CLI-invocation from another skill), updates `HANDOVER-LATEST.md` in-place rather than writing a new dated file. Used by `aegis-customer-build` after each of its 7 phases.
+
+---
+
+## Process
+
+### Phase 1: Determine handover-filename
+
+For session-end (default): `HANDOVER-YYYY-MM-DD-<topic-slug>.md` based on date + 1-3-word session-topic. The topic is inferred from the last user-request or extracted from `.aegis/state.json` `current_phase`.
+
+For continuous-update: write to `HANDOVER-LATEST.md` directly (which is itself a symlink to today's dated file) and append rather than overwrite.
+
+### Phase 2: Gather inputs
+
+Read these in order:
+- `git log --oneline -20` — recent commits with SHAs
+- `.aegis/state.json` — current state, last completed phase, project-skills
+- `git status --short` — unstaged changes, anything still in flight
+- `git diff main..HEAD --name-only` — files changed this branch
+- For Skill Changes: scan `~/.claude/skills/` and `<repo>/.claude/skills/` for files modified since the last handover
+
+### Phase 3: Write the handover-file
+
+Use the template under `## Verification / Success Criteria` below. Each section MUST be present (write `(none this session)` if empty).
+
+### Phase 4: Update symlink
+
+```bash
+cd .claude/handover/
+ln -sf HANDOVER-YYYY-MM-DD-<topic>.md HANDOVER-LATEST.md
+```
+
+Verify: `readlink HANDOVER-LATEST.md` returns the right target.
+
+### Phase 5: Commit (optional)
+
+If the orchestrator asked for a `--commit` flag: `git add .claude/handover/ && git commit -m "docs(handover): YYYY-MM-DD-<topic>"`. Otherwise leave the file uncommitted — operator commits at their discretion.
+
+---
+
+## Verification / Success Criteria
+
+The handover-file MUST contain these 8 sections, in order:
+
+- [ ] `## Status` — bullet-list of what was completed this session, with concrete file-paths + commit-SHAs (e.g., `b837c6d release(skills): bump to 0.3.0`)
+- [ ] `## Metrics` — quality-gate results (build / tsc / lint / tests / aegis-scan / brutaler-anwalt / lighthouse / skillforge-validate / briefing-coverage)
+- [ ] `## Files Changed` — list of new + modified files (`git diff main..HEAD --name-only`)
+- [ ] `## Skill Changes` — any SKILL.md edits, new skills, frontmatter updates, references added — even minor changes get tracked here
+- [ ] `## Open (Pri 1/2/3)` — what's left, prioritized: P1 = blocker for next session, P2 = should-do-soon, P3 = nice-to-have
+- [ ] `## Known Fallstricke` — gotchas to remember (e.g., "the SkillForge validator rejects top-level frontmatter fields outside the allowlist; use metadata: nesting")
+- [ ] `## Next Steps` — concrete actions for the next session, ordered by sequence (e.g., "1. Run `pnpm test`. 2. If green, push the branch. 3. Open PR.")
+- [ ] `## Recommendations` — what the operator should do (deploy, review, npm-publish, etc.) — actions that need human-judgment
+
+Plus the symlink check:
+- [ ] `readlink .claude/handover/HANDOVER-LATEST.md` returns the new file (not a stale earlier handover)
+
+---
+
+## Anti-Patterns
+
+- ❌ Vague status ("worked on stuff") — must be concrete with file-paths + commit-SHAs
+- ❌ Missing skill-changes section — even minor frontmatter edits must be tracked (next agent needs to know)
+- ❌ Skipping symlink update — next session won't find the latest handover
+- ❌ Mixing P1 and P3 items in the same list — prioritize, don't dump
+- ❌ "We'll fix this later" without a Pri-line — every deferred item belongs in Open (Pri X)
+- ❌ Writing the handover BEFORE the current phase is actually complete — handover comes after the work, not as a way to declare it done
+- ❌ Overwriting a continuous-handover with a session-end-handover when both happen on the same day — append + symlink-rotate, don't lose history
+
+---
+
+## Extension Points
+
+- **Per-use-case handover-templates** — drop a custom template into `.claude/handover/templates/<use-case>.md`. The skill detects it via filename-match and uses it instead of the default template. Useful when customer-build sessions need a different shape than compliance-audit sessions.
+- **Domain-specific sections** — extend the 8-section template with extra sections (e.g., `## Security Findings` for compliance-audit, `## Pages Built` for customer-build). Add to the use-case template.
+- **External system updates** — add hooks that, after writing the handover-file, update Linear / Jira / Slack with a summary. Implement as PostToolUse hooks in `.claude/settings.json`, NOT as logic inside this skill.
+- **Continuous-handover-frequency** — for very long builds (4-5h+), the customer-build orchestrator can call this skill with `--continuous` after every phase. Each call appends to `HANDOVER-LATEST.md` rather than rotating to a new dated file.
+- **Per-handover sign-off** — add a `## Operator Sign-off` section template for handovers that require explicit human review before next-session-resume. Useful for production-deploy gates.