@event4u/agent-config 2.16.0 → 2.17.0

package/docs/contracts/write-engine.md

@@ -0,0 +1,142 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
+# Write-engine contract (v1)
+
+> **Status:** beta — shared procedural contract consumed by
+> `/ghostwriter:write`, `/post-as:ghostwriter` (alias), and
+> `/post-as:me`. Locked alongside the ghostwriter cluster roadmap.
+
+The **write engine** is the deterministic procedure that produces a
+copyable markdown draft in a captured voice. It deliberately has no
+implementation file — the engine is a sequence of steps the host
+agent follows verbatim. The same steps are referenced by every
+consumer command; the **only** axis of variation is:
+
+1. **Style source** — which file the engine reads to load the voice.
+2. **Disclosure footer** — appended when the style source is *external*
+   (a ghostwriter profile), omitted when the style source is *self*
+   (`.agent-user.md`).
+
+## Style sources
+
+| Consumer command | Style source | Footer |
+|---|---|---|
+| `/ghostwriter:write` | `agents/ghostwriter/<slug>.md` (selected) | **Mandatory** |
+| `/post-as:ghostwriter` | Same as above (thin alias) | **Mandatory** |
+| `/post-as:me` | `.agent-user.md` (project root) | **Omitted** — user is the author |
+
+No other style source is permitted in v1. Consuming `personas/*.md`
+voices is explicitly out of scope — personas are review lenses, not
+author voices.
+
+## Procedure (followed verbatim by every consumer)
+
+### 1. Resolve the style source
+
+Each consumer command resolves a single style source before invoking
+the engine. The engine receives a fully populated style object with:
+
+- `identity.name` (for the footer when applicable)
+- `style.fingerprint.*` (sentence length, register, opener / closer
+  patterns, hashtag / emoji rules, paragraph cadence)
+- `style.free_form_notes` (or `voice_sample` for `/post-as:me`)
+- `taboos` (ghostwriter only — empty list for `/post-as:me`)
+
+Missing style source → consumer command aborts with a pointer at the
+appropriate setup command (`/ghostwriter:fetch` or `/agents user init`).
+
+### 2. Collect the topic + modifiers
+
+One question per turn, in this order:
+
+1. **Topic** — required. Plain prose, no quoting.
+2. **Tone** — optional. Enum: `formal | casual | neutral`. Default
+   inherits `style.fingerprint.vocab_register` mapped per the table
+   below.
+3. **Length** — optional. Integer word count. Default: see the
+   per-channel defaults table.
+4. **Channel** — optional. Enum: `linkedin-post | tweet | blog | freeform`.
+   Default: `freeform`.
+5. **Audience** — optional. Free-form one-line descriptor.
+
+Modifiers may be supplied via flags (`--tone=casual --length=200
+--channel=linkedin-post --audience="early-stage founders"`) to skip
+the interactive interview. `--as=<slug>` selects the ghostwriter
+non-interactively for `/ghostwriter:write` and the alias.
+
+#### Per-channel defaults
+
+| Channel | Length default | Cadence guidance |
+|---|---|---|
+| `tweet` | 50 words | One paragraph, no lists. |
+| `linkedin-post` | 180 words | 2–4 short paragraphs. Hashtags only if `style.fingerprint.hashtag_rules` allows. |
+| `blog` | 600 words | Inherits `style.fingerprint.paragraph_cadence`. |
+| `freeform` | 250 words | Inherits `style.fingerprint.paragraph_cadence`. |
+
+#### Vocab-register → tone mapping (default inheritance)
+
+| `vocab_register` | Default `tone` |
+|---|---|
+| `casual` / `conversational` | `casual` |
+| `professional` / `literary` | `neutral` |
+| `academic` | `formal` |
+
+### 3. Apply negative-constraint pass (ghostwriter only)
+
+Before drafting, the engine surfaces the loaded `taboos` list and
+explicitly excludes those moves from the draft (no political
+endorsements, no profanity, no hashtag-driven posts, etc.). For
+`/post-as:me`, the negative-constraint pass is skipped (the user does
+not pre-declare taboos in v1).
+
+### 4. Draft
+
+Emit the body as a single fenced markdown block. The body MUST:
+
+- Match `style.fingerprint.sentence_length_avg` within ±25%.
+- Honour `style.fingerprint.opener_patterns` for the first sentence.
+- Honour `style.fingerprint.closer_patterns` for the last sentence.
+- Respect `style.fingerprint.hashtag_rules` and `emoji_rules`.
+- Stay within ±15% of the requested length.
+
+### 5. Append the disclosure footer (ghostwriter only)
+
+For ghostwriter consumers, append on its own line, separated by a
+blank line:
+
+```
+Written in the style of <identity.name>, not by them.
+```
+
+The footer is appended **by the command's output template** as a
+literal string — it is not generated by the model and has no opt-out
+flag. For `/post-as:me` the footer is omitted entirely (the user is
+the author).
+
+### 6. Print the draft
+
+Print the fenced markdown block. No commit, no save, no file write.
+The user copies the output manually. The engine performs no side
+effects on disk.
+
+## Rules
+
+- **No `--no-disclosure` flag.** For any ghostwriter consumer, the
+  footer is mandatory and deterministic. `task lint-skills` greps the
+  ghostwriter command sources for the literal string `no-disclosure`
+  and fails CI on a hit.
+- **No multi-voice draft in v1.** One style source per invocation;
+  blending voices is deferred.
+- **No file writes.** The engine prints; the user copies. Saving the
+  output to `agents/` or anywhere else is a future feature.
+
+## See also
+
+- [`ghostwriter-schema`](ghostwriter-schema.md) — the source schema
+  for `/ghostwriter:write`.
+- [`agent-user-schema`](agent-user-schema.md) — the source schema
+  for `/post-as:me`.
+- [`command-clusters`](command-clusters.md) — cluster registration.

package/docs/getting-started-by-role.md

@@ -0,0 +1,89 @@
+# Getting started — by role
+
+> Pick the entry that matches what you do day-to-day. Each section names the three skills you will reach for first and shows whether MCP (no terminal) or CLI (terminal) is the simpler install path for that role.
+
+`agent-config` ships ~210 skills, ~67 rules, and ~124 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
+
+> **Eval-gated messaging note.** Until `task bench --corpus non-dev` reports `selection_accuracy >= 0.60` (step-12 Phase 1 exit), this page is documentation, not marketing. The skills listed below are the candidates the corpus tests against; their description quality is what the eval validates. See [`agents/roadmaps/step-12-universal-os-reframe.md`](../agents/roadmaps/step-12-universal-os-reframe.md).
+
+---
+
+## Creator (writer, marketer, indie content shop)
+
+**You want this if:** you draft blog posts, marketing emails, launch copy, or release announcements and want a writing assistant that holds a defined brand voice across surfaces. You need brand-voice discipline more than code-quality enforcement. You will spend most of your time in Claude Desktop / ChatGPT, not in a terminal.
+
+- [`voice-and-tone-design`](../.agent-src/skills/voice-and-tone-design/SKILL.md) — define and audit brand voice (voice attributes, tone-by-context matrix).
+- [`messaging-architecture`](../.agent-src/skills/messaging-architecture/SKILL.md) — primary message + supporting proofs + audience-by-message matrix.
+- [`editorial-calendar`](../.agent-src/skills/editorial-calendar/SKILL.md) — evergreen vs campaign vs reactive cadence across channels.
+
+**Install path:** **MCP recommended.** Claude Desktop is the lowest-friction entry; no terminal required. See [`docs/mcp.md`](mcp.md). CLI install works too if you already use a code editor.
+
+---
+
+## Founder (early-stage operator wearing every hat)
+
+**You want this if:** you switch between investor pitch, hiring decision, product spec, and unit-economics modeling in the same week. You need cross-domain skills that respect your time budget, not depth-first specialists. Decisions need to be defensible to a board.
+
+- [`runway-cognition`](../.agent-src/skills/runway-cognition/SKILL.md) — cash runway, burn shape, fundraise triggers, cut-vs-grow.
+- [`unit-economics-modeling`](../.agent-src/skills/unit-economics-modeling/SKILL.md) — CAC, LTV, payback, contribution margin per customer.
+- [`fundraising-narrative`](../.agent-src/skills/fundraising-narrative/SKILL.md) — why-now / why-us / why-this framing, market-size reasoning.
+
+**Install path:** **MCP for advisory work, CLI when you touch code.** Claude Desktop covers strategy / finance / narrative; CLI is needed only when you sit in the repo with the dev team.
+
+---
+
+## Developer (the original audience)
+
+**You want this if:** you write code daily — Laravel, Symfony, Next.js, Node, or stack-agnostic — and want testing / quality / git / CI guardrails baked into the agent's behavior. You will use commands like `/work`, `/commit`, `/create-pr`, `/quality-fix` constantly.
+
+- [`laravel`](../.agent-src/skills/laravel/SKILL.md) — Laravel-flavored PHP (Eloquent, Artisan, FormRequests, jobs, policies). See [`docs/getting-started-laravel.md`](getting-started-laravel.md) for the deep dive.
+- [`nextjs-patterns`](../.agent-src/skills/nextjs-patterns/SKILL.md) — App Router, Server Components, Server Actions, caching.
+- [`quality-tools`](../.agent-src/skills/quality-tools/SKILL.md) — PHPStan, Rector, ECS error triage and fix loop.
+
+**Install path:** **CLI.** Run `npx @event4u/agent-config init --tools=claude-code,cursor` in the project root. MCP works too but loses git / file-system tooling that the IDE-integrated path gives you.
+
+---
+
+## Consultant (advisory, freelance, fractional)
+
+**You want this if:** you sell discovery, positioning, competitive analysis, or roadmap audits. Output is briefs and slide content for a client, not code. You need defensible methodology behind every deliverable.
+
+- [`discovery-interview`](../.agent-src/skills/discovery-interview/SKILL.md) — switch-event JTBD guides, bias audit, falsifiable hypothesis.
+- [`competitive-moat-analysis`](../.agent-src/skills/competitive-moat-analysis/SKILL.md) — moat reasoning, where-to-play / where-not-to-play.
+- [`stakeholder-tradeoff`](../.agent-src/skills/stakeholder-tradeoff/SKILL.md) — per-lens framing, trade-off matrix with cost per choice.
+
+**Install path:** **MCP recommended.** Most consulting work is doc + slide drafting; the terminal adds friction without payback. Switch to CLI only if you also write code for the client.
+
+---
+
+## Go-To-Market (sales, marketing ops, RevOps)
+
+**You want this if:** you own pipeline shape, forecast accuracy, launch sequencing, or post-launch comms. You need deal-level rigor (MEDDIC, exit criteria) and narrative skills (release comms, messaging) in the same agent.
+
+- [`pipeline-strategy`](../.agent-src/skills/pipeline-strategy/SKILL.md) — stage exit criteria, per-cell conversion, leak diagnosis.
+- [`deal-qualification-meddic`](../.agent-src/skills/deal-qualification-meddic/SKILL.md) — MEDDIC slots with evidence, inversion test, disqualification heuristic.
+- [`release-comms`](../.agent-src/skills/release-comms/SKILL.md) — value-not-feature framing, audience-segmented surfaces.
+
+**Install path:** **MCP recommended.** GTM artifacts are documents, decks, and Notion pages; Claude Desktop is the natural home.
+
+---
+
+## Finance / Ops (CFO, controller, ops lead, founder-finance)
+
+**You want this if:** you build forecasts, model scenarios, and review data-handling for compliance. You need the agent to keep accounting / regulatory framing straight, not invent numbers.
+
+- [`forecasting`](../.agent-src/skills/forecasting/SKILL.md) — top-down vs bottom-up shape, confidence bands, retro-loop.
+- [`scenario-modeling`](../.agent-src/skills/scenario-modeling/SKILL.md) — base / upside / downside, three-statement modeling, sensitivity.
+- [`privacy-review`](../.agent-src/skills/privacy-review/SKILL.md) — GDPR / CCPA / HIPAA fit, cross-border transfer, breach-impact triage.
+
+**Install path:** **MCP recommended.** Finance / ops workflows are spreadsheet- and document-heavy; the CLI buys nothing here unless you also export models into a code repo.
+
+---
+
+## What is the same regardless of role
+
+A short universal-skills allowlist (`git`, `refine-ticket`, `proofread`, `threat-model`, etc.) loads in every profile. The list will live at `docs/contracts/universal-skills.md` once step-12 Phase 3 lands; until then the package loads all skills and the host agent's semantic search picks what the prompt needs.
+
+## What this page does not promise
+
+This page lists **candidate** skill / role pairings. Whether each skill's `description:` is sharp enough for the agent to retrieve it without manual hint is exactly what `tests/eval/corpus-non-dev.yaml` tests. If a prompt in your role above falls flat, that is a skill-description bug — file an issue or open a PR with a sharper description, do not work around it by naming the skill manually.

package/docs/getting-started-laravel.md

@@ -0,0 +1,72 @@
+# Getting started — Laravel
+
+> Laravel is the deepest reference stack in the package today. This page collects the Laravel-specific guidance previously embedded in the root README. The relocation is part of step-12 Phase 2; the root README continues to surface Laravel under the dev role until the Phase 6 identity rewrite lands.
+
+## Why Laravel is the reference stack
+
+Laravel ships with the broadest, battle-tested skill coverage in the package — Pest, PHPStan, Rector, Eloquent, Livewire / Flux, Horizon, Pulse, Reverb, Pennant. That coverage exists because the package was originally extracted from a Laravel monorepo (Galawork). Symfony and Next.js are the second tier (`symfony-workflow`, `nextjs-patterns`); other stacks ship as they are battle-tested, not second-class.
+
+## Laravel-flavored skills
+
+| Skill | What it covers |
+|---|---|
+| [`laravel`](../.agent-src/skills/laravel/SKILL.md) | Eloquent, Artisan controllers, FormRequests, jobs, events, policies, providers |
+| [`eloquent`](../.agent-src/skills/eloquent/SKILL.md) | Models, relationships, scopes, query patterns |
+| [`artisan-commands`](../.agent-src/skills/artisan-commands/SKILL.md) | Console command structure, signatures, safe execution |
+| [`jobs-events`](../.agent-src/skills/jobs-events/SKILL.md) | Queued workflows, listeners, retry / failure handling |
+| [`laravel-validation`](../.agent-src/skills/laravel-validation/SKILL.md) | Form Requests, rules, custom rule objects |
+| [`laravel-middleware`](../.agent-src/skills/laravel-middleware/SKILL.md) | Request / response filtering, groups, priority |
+| [`laravel-notifications`](../.agent-src/skills/laravel-notifications/SKILL.md) | Mail, Slack, database, custom channels |
+| [`laravel-mail`](../.agent-src/skills/laravel-mail/SKILL.md) | Mailables, Markdown templates, queued sending |
+| [`laravel-scheduling`](../.agent-src/skills/laravel-scheduling/SKILL.md) | Cron expressions, overlap prevention, maintenance mode |
+| [`laravel-horizon`](../.agent-src/skills/laravel-horizon/SKILL.md) | Worker supervision, job metrics, balancing strategies |
+| [`laravel-pulse`](../.agent-src/skills/laravel-pulse/SKILL.md) | Real-time dashboard, custom recorders, performance insights |
+| [`laravel-reverb`](../.agent-src/skills/laravel-reverb/SKILL.md) | First-party WebSocket server, Pusher protocol compatibility |
+| [`laravel-pennant`](../.agent-src/skills/laravel-pennant/SKILL.md) | Feature flags, gradual rollouts, A/B testing |
+
+## Quality pipeline
+
+The Laravel quality pipeline runs PHPStan + Rector + ECS, with Pest as the test runner:
+
+- [`quality-tools`](../.agent-src/skills/quality-tools/SKILL.md) — PHPStan output triage, Rector apply, ECS fix.
+- [`pest-testing`](../.agent-src/skills/pest-testing/SKILL.md) — Pest test authoring patterns.
+- [`/quality-fix`](../.agent-src/commands/quality-fix.md) — runs the full pipeline and fixes reported errors.
+
+## Docker and dev environment
+
+- [`docker`](../.agent-src/skills/docker/SKILL.md) — Dockerfile, compose, dual-container (fast + Xdebug) setup.
+- [`php-debugging`](../.agent-src/skills/php-debugging/SKILL.md) — Xdebug breakpoints, dual-container, header-based routing.
+- [`traefik`](../.agent-src/skills/traefik/SKILL.md) — local reverse proxy, real domains on 127.0.0.1, mkcert HTTPS.
+
+## Multi-tenancy and database
+
+- [`multi-tenancy`](../.agent-src/skills/multi-tenancy/SKILL.md) — customer DB switching, FQDN routing, tenant isolation.
+- [`database`](../.agent-src/skills/database/SKILL.md) — MariaDB / MySQL tuning, indexing, multi-connection patterns.
+- [`sql-writing`](../.agent-src/skills/sql-writing/SKILL.md) — raw SQL, parameterization, raw migrations.
+
+## Project analysis
+
+- [`project-analysis-laravel`](../.agent-src/skills/project-analysis-laravel/SKILL.md) — boot flow, request lifecycle, container usage, async systems, Laravel-specific failure patterns.
+
+## Install for a Laravel project
+
+```bash
+cd path/to/your/laravel/app
+npx @event4u/agent-config init --tools=claude-code,cursor
+```
+
+The installer detects `composer.json` + `artisan` + the Laravel framework dependency, enables stack-aware skills, and writes `.agent-settings.yml` with sensible defaults. The first `/onboard` run captures your name, preferred IDE, and cost profile.
+
+## Other PHP stacks
+
+| Stack | Coverage |
+|---|---|
+| **Symfony** | [`symfony-workflow`](../.agent-src/skills/symfony-workflow/SKILL.md) — DI, Doctrine, Messenger, voters, Twig; [`project-analysis-symfony`](../.agent-src/skills/project-analysis-symfony/SKILL.md) |
+| **Zend / Laminas** | [`project-analysis-zend-laminas`](../.agent-src/skills/project-analysis-zend-laminas/SKILL.md) + shared PHP coder / quality skills |
+| **Framework-free PHP** | [`php-coder`](../.agent-src/skills/php-coder/SKILL.md) — modern idioms, SOLID refactors, type hints without framework lock-in |
+
+## See also
+
+- [`docs/getting-started-by-role.md`](getting-started-by-role.md) — pick the entry that matches your day-to-day.
+- [`docs/getting-started.md`](getting-started.md) — generic three-step quickstart.
+- [`docs/installation.md`](installation.md) — detailed install variants (npx, curl, global npm).

package/docs/getting-started.md

@@ -106,7 +106,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 67 rules. No configuration needed.
+This is enforced automatically by 79 rules. No configuration needed.
 
 ---
 
@@ -146,7 +146,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 115 active commands](../.agent-src/commands/)
+→ [Browse all 124 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/safety.md

@@ -0,0 +1,30 @@
+# Data governance & domain safety
+
+`agent-config` ships **12 domain-safety rules** (`.agent-src.uncompressed/rules/domain-safety-*.md`) that act as a per-domain output floor — PII redaction, disclaimer requirements, and retention guidance. Rules fire automatically via the router when their triggers match.
+
+## Surface → rule(s) → floor
+
+| Surface | Rule(s) | Floor |
+|---|---|---|
+| Support / CRM drafts | `domain-safety-pii-support` · `domain-safety-retention-support` | Redact customer names, emails, phones, account IDs to placeholders before output |
+| Finance / invoicing | `domain-safety-pii-finance` · `domain-safety-retention-finance` | Redact counterparty PII and bank identifiers; flag retention under audit hold |
+| Recruiting | `domain-safety-pii-recruiting` | Redact candidate PII from notes, scorecards, rejection emails |
+| Marketing testimonials | `domain-safety-pii-marketing` | Require consent record before customer-identifying copy ships |
+| Legal · financial · medical · consulting drafts | `domain-safety-disclaimer-*` | "Not legal/financial/medical advice" disclaimers; refuse diagnostic / dosage / specific tax positions |
+| Logs · exports | `domain-safety-logging-pii-floor` · `domain-safety-export-redact` | No raw PII in logs or exports; allowlist-driven structured fields only |
+
+## How the floor is enforced
+
+- Each rule declares `applies_to_user_types:` in frontmatter — rules load only when the matching user-type is active (forward-compatible with the user-types axis shipping in `step-9-user-types-axis`).
+- Each rule routes to `skill:privacy-review` as the baseline deeper-regime check (GDPR · CCPA · HIPAA).
+- The set is opt-in by domain, never overrides higher Iron Laws (`non-destructive-by-default`, `commit-policy`, `scope-control`).
+
+## Related skills
+
+- [`privacy-review`](../.agent-src.uncompressed/skills/privacy-review/SKILL.md) — end-to-end data-flow review for a regulatory regime (GDPR / CCPA / HIPAA).
+- [`data-handling-judgment`](../.agent-src.uncompressed/skills/data-handling-judgment/SKILL.md) — classification, retention, cross-border transfer, DSR workflow.
+
+## See also
+
+- [`non-destructive-by-default`](../.augment/rules/non-destructive-by-default.md) — Hard Floor that overrides every domain-safety carve-out.
+- [`security-sensitive-stop`](../.augment/rules/security-sensitive-stop.md) — threat-model before touching auth / billing / tenant boundaries / uploads.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.16.0",
+    "version": "2.17.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/bench_runner.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Bench runner for the eval corpora — step-4 measurement-and-benchmark Phase 1.
+
+Deterministic, no-API skill-selection baseline. For each prompt in a
+corpus YAML, ranks the 210 skills in `.agent-src.uncompressed/skills/`
+by keyword overlap between the prompt text and each skill's
+`description` frontmatter field. Reports selection accuracy as
+`top-K contains >= 1 expected_skill`.
+
+This is a baseline retrieval — not the production router. The
+production router uses semantic embeddings; this runner pins a
+reproducible floor so accuracy regressions in skill descriptions are
+catchable in CI.
+
+Usage:
+    python3 scripts/bench_runner.py --corpus non-dev
+    python3 scripts/bench_runner.py --corpus non-dev --top-k 3 --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Iterable
+
+try:
+    import yaml
+except ImportError:
+    sys.stderr.write("error: PyYAML required (pip install pyyaml)\n")
+    sys.exit(2)
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILLS_DIR = REPO_ROOT / ".agent-src.uncompressed" / "skills"
+CORPUS_DIR = REPO_ROOT / "tests" / "eval"
+
+STOPWORDS = frozenset({
+    "a", "an", "and", "are", "as", "at", "be", "by", "for", "from",
+    "has", "have", "in", "into", "is", "it", "its", "of", "on", "or",
+    "that", "the", "this", "to", "via", "with", "your", "you", "use",
+    "when", "what", "which", "who", "how", "why", "be", "do", "i",
+    "we", "they", "them", "their", "our", "ours", "but", "not", "no",
+    "yes", "all", "any", "some", "more", "less", "than", "then",
+})
+
+
+def tokenize(text: str) -> set[str]:
+    tokens = re.findall(r"[a-z][a-z0-9\-]+", text.lower())
+    return {t for t in tokens if t not in STOPWORDS and len(t) > 2}
+
+
+def load_skill_descriptions() -> dict[str, str]:
+    """Return {skill_name: description_text} for every skill on disk."""
+    skills: dict[str, str] = {}
+    for skill_dir in sorted(SKILLS_DIR.iterdir()):
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.is_file():
+            continue
+        text = skill_md.read_text(encoding="utf-8")
+        m = re.search(r"^---\s*\n(.*?)\n---\s*\n", text, re.DOTALL)
+        if not m:
+            continue
+        try:
+            fm = yaml.safe_load(m.group(1)) or {}
+        except yaml.YAMLError:
+            continue
+        desc = fm.get("description", "")
+        name = fm.get("name") or skill_dir.name
+        if desc:
+            skills[name] = f"{name} {desc}"
+    return skills
+
+
+def rank_skills(prompt: str, skills: dict[str, str], top_k: int) -> list[str]:
+    """Rank skills by keyword overlap with the prompt; return top-K names."""
+    prompt_tokens = tokenize(prompt)
+    if not prompt_tokens:
+        return []
+    scores: list[tuple[float, str]] = []
+    for name, desc in skills.items():
+        desc_tokens = tokenize(desc)
+        if not desc_tokens:
+            continue
+        overlap = prompt_tokens & desc_tokens
+        if not overlap:
+            continue
+        # Jaccard with a small IDF-shaped boost for rare matches.
+        union = prompt_tokens | desc_tokens
+        score = len(overlap) / len(union)
+        scores.append((score, name))
+    scores.sort(reverse=True)
+    return [name for _, name in scores[:top_k]]
+
+
+def run_corpus(corpus_path: Path, top_k: int) -> dict:
+    corpus = yaml.safe_load(corpus_path.read_text(encoding="utf-8"))
+    skills = load_skill_descriptions()
+    results = []
+    hits = 0
+    for p in corpus["prompts"]:
+        ranked = rank_skills(p["prompt"], skills, top_k)
+        expected = set(p.get("expected_skills", []))
+        hit = bool(expected & set(ranked))
+        if hit:
+            hits += 1
+        results.append({
+            "id": p["id"],
+            "category": p.get("category", ""),
+            "expected_skills": sorted(expected),
+            "top_k_ranked": ranked,
+            "hit": hit,
+        })
+    n = len(results)
+    accuracy = hits / n if n else 0.0
+    return {
+        "corpus_id": corpus["corpus_id"],
+        "target": corpus.get("selection_accuracy_target", 0.60),
+        "top_k": top_k,
+        "prompts_total": n,
+        "prompts_hit": hits,
+        "selection_accuracy": round(accuracy, 4),
+        "passed": accuracy >= corpus.get("selection_accuracy_target", 0.60),
+        "per_prompt": results,
+    }
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--corpus", default="non-dev", help="corpus id (non-dev | dev)")
+    ap.add_argument("--top-k", type=int, default=3, help="top-K window for hit-check")
+    ap.add_argument("--json", action="store_true", help="emit JSON only")
+    args = ap.parse_args(list(argv) if argv is not None else None)
+
+    corpus_path = CORPUS_DIR / f"corpus-{args.corpus}.yaml"
+    if not corpus_path.is_file():
+        sys.stderr.write(f"error: corpus not found: {corpus_path}\n")
+        return 2
+
+    summary = run_corpus(corpus_path, args.top_k)
+
+    if args.json:
+        print(json.dumps(summary, indent=2))
+    else:
+        print(f"corpus: {summary['corpus_id']}  target={summary['target']}  top-k={summary['top_k']}")
+        print(f"prompts: {summary['prompts_hit']} / {summary['prompts_total']} hit")
+        print(f"selection_accuracy: {summary['selection_accuracy']:.2%}")
+        print(f"verdict: {'PASS' if summary['passed'] else 'FAIL'}")
+        for r in summary["per_prompt"]:
+            mark = "✓" if r["hit"] else "✗"
+            print(f"  {mark} {r['id']:14s} expected={r['expected_skills']} got={r['top_k_ranked'][:3]}")
+
+    return 0 if summary["passed"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_role_doc_links.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Verify every skill link in role-based docs resolves to a real file.
+
+Part of step-12 Phase 2. Runs in `task ci` to catch link rot when a
+skill is renamed or removed but the role docs still reference it.
+
+Scans `docs/getting-started-by-role.md` and `docs/getting-started-laravel.md`
+for markdown links of the form `../.agent-src/skills/<name>/SKILL.md`
+(relative to docs/) and checks that the target file exists on disk.
+
+Exit codes:
+  0 — every link resolves
+  1 — at least one broken link; prints the offending file:line:url tuples
+  2 — usage error (one of the role doc files missing)
+
+Usage:
+  python3 scripts/check_role_doc_links.py
+  python3 scripts/check_role_doc_links.py --quiet
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+DOCS_DIR = ROOT / "docs"
+
+# (display-path, on-disk path, link-anchor) — anchor is the relative
+# prefix that identifies a skill link from inside docs/.
+ROLE_DOCS = [
+    DOCS_DIR / "getting-started-by-role.md",
+    DOCS_DIR / "getting-started-laravel.md",
+]
+
+# Markdown link: [label](path). We only check the (path) part. The
+# regex tolerates trailing #anchor fragments and ignores absolute URLs.
+LINK_RE = re.compile(r"\]\(([^)\s]+)\)")
+
+# Anchors we know how to resolve. Each tuple is (prefix, base_dir).
+ANCHORS: list[tuple[str, Path]] = [
+    ("../.agent-src/skills/", ROOT / ".agent-src" / "skills"),
+    ("../.agent-src/commands/", ROOT / ".agent-src" / "commands"),
+    ("../.agent-src/rules/", ROOT / ".agent-src" / "rules"),
+    ("../agents/", ROOT / "agents"),
+    ("contracts/", DOCS_DIR / "contracts"),
+    ("guidelines/", DOCS_DIR / "guidelines"),
+]
+
+
+def resolve(url: str, doc_path: Path) -> Path | None:
+    """Return the on-disk target path for a relative link, or None if external."""
+    if url.startswith(("http://", "https://", "mailto:")):
+        return None
+    bare = url.split("#", 1)[0]
+    if not bare:
+        return None
+    # Relative to the doc's own directory.
+    target = (doc_path.parent / bare).resolve()
+    return target
+
+
+def scan(doc_path: Path) -> list[tuple[int, str]]:
+    """Return list of (line_no, url) tuples for every non-external link."""
+    if not doc_path.is_file():
+        print(f"error: missing role doc: {doc_path}", file=sys.stderr)
+        sys.exit(2)
+    links: list[tuple[int, str]] = []
+    for i, line in enumerate(doc_path.read_text(encoding="utf-8").splitlines(), 1):
+        for m in LINK_RE.finditer(line):
+            url = m.group(1)
+            if url.startswith(("http://", "https://", "mailto:")):
+                continue
+            links.append((i, url))
+    return links
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--quiet", action="store_true", help="Suppress success summary.")
+    args = p.parse_args()
+
+    failures: list[tuple[Path, int, str]] = []
+    checked = 0
+
+    for doc in ROLE_DOCS:
+        for line_no, url in scan(doc):
+            target = resolve(url, doc)
+            if target is None:
+                continue
+            checked += 1
+            if not target.exists():
+                failures.append((doc, line_no, url))
+
+    if failures:
+        print("Broken links in role docs:", file=sys.stderr)
+        for doc, line_no, url in failures:
+            rel = doc.relative_to(ROOT)
+            print(f"  {rel}:{line_no}  -> {url}", file=sys.stderr)
+        print(f"\n{len(failures)} broken / {checked} checked", file=sys.stderr)
+        return 1
+
+    if not args.quiet:
+        print(f"check_role_doc_links: {checked} links OK across {len(ROLE_DOCS)} files")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/compress.py

@@ -77,6 +77,11 @@ def _tool_active(tool_id: str) -> bool:
 # Files to copy as-is even if .md (not compressed by agent)
 COPY_AS_IS = {"README.md"}
 
+# Directories (relative to SOURCE_DIR) whose .md content is data, not prose,
+# and must be copied verbatim. Ghostwriter fixtures carry voice_samples that
+# would be destroyed by caveman compression.
+COPY_AS_IS_DIRS = frozenset({"ghostwriter"})
+
 
 def _read_augment_rules_use_symlinks() -> bool:
     """Read augment.rules_use_symlinks from .agent-settings.yml.
@@ -235,6 +240,12 @@ def should_compress(filepath: Path) -> bool:
         return False
     if filepath.name in COPY_AS_IS:
         return False
+    try:
+        rel_parts = filepath.relative_to(SOURCE_DIR).parts
+    except ValueError:
+        rel_parts = filepath.parts
+    if rel_parts and rel_parts[0] in COPY_AS_IS_DIRS:
+        return False
     return True