@event4u/agent-config 2.16.0 → 2.18.0

package/docs/case-studies/_template.md

@@ -0,0 +1,60 @@
+# Case study — `<short-title>`
+
+> **Step-12 Phase 7 L128–131 template.** Drop a copy into `docs/case-studies/` with filename `<YYYY-MM-DD>-<user-type>-<slug>.md`. Anonymise as needed; metrics must be real.
+
+## Subject
+
+- **User-type:** (consultant | creator | founder | finance | ops | gtm | developer)
+- **Tool host:** (claude-code | cursor | windsurf | copilot | claude.ai web | other)
+- **`agent-config` install:** `npx agent-config init --user-type=<type>`
+- **Anonymised:** yes / no (if yes — describe what was abstracted)
+
+## Workflow before
+
+One paragraph. What was the specific job-to-be-done? How was it solved before `agent-config` (which tool, how many steps, where did it stall)? Include **time-to-output** as a baseline metric.
+
+## Workflow after
+
+One paragraph. Same job, after install. Which **3–5 skills** carried the load? Which **commands** did the user actually invoke? Where did the agent ask vs. act?
+
+## Top-10 skill invocations (proof of non-dev workflow)
+
+Paste output of `task bench --history --top 10` (or the equivalent host log). The closure gate (L130) requires this list to contain **zero** of: `test`, `deploy`, `ci`. If it does, the case study counts as proof of non-dev workflow rather than disguised dev work.
+
+```
+ 1. <skill-name>          (N invocations)
+ 2. ...
+ ...
+10. ...
+```
+
+## Quantified outcomes
+
+| Metric | Before | After | Δ |
+|---|---:|---:|---:|
+| Time-to-output (minutes) | | | |
+| Number of revision passes | | | |
+| Self-reported confidence (1–5) | | | |
+| <domain-specific KPI> | | | |
+
+Example: *"Brief drafting: 90 min → 25 min, 73 % time reduction."*
+
+## What broke
+
+Be specific. The case study is only useful if it lists at least **two real friction points** — skill misfires, rule false-positives, missing user-type tags, confusing description language. These feed back into the corpus + skill descriptions.
+
+1. ...
+2. ...
+
+## Verbatim quote (optional, with consent)
+
+> "...short quote that captures the value the user got, in their voice..."
+
+— `<role>, <anonymised company shape>`
+
+## Provenance & consent
+
+- **Interview / live walkthrough date:** YYYY-MM-DD
+- **Consent for publication:** signed / verbal-recorded / declined-attribution
+- **Author:** maintainer initials
+- **Reviewed by user before merge:** yes / no

package/docs/catalog.md

@@ -1,6 +1,6 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **461 public artefacts** shipped by
+Consumer-facing catalog of all **482 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
@@ -148,7 +148,7 @@ are excluded.
 | skill | [`playwright-testing`](../.agent-src/skills/playwright-testing/SKILL.md) |  | Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns. |
 | skill | [`po-discovery`](../.agent-src/skills/po-discovery/SKILL.md) |  | Use when shaping a fuzzy product ask into a refined backlog item — problem framing, user-story rewrite, AC tightening — even if the user just says 'help me write this ticket'. |
 | skill | [`positioning-strategy`](../.agent-src/skills/positioning-strategy/SKILL.md) |  | Use when locking the market frame — category, segment, alternative, point-of-view — before messaging, launch, or pricing rides on it. Triggers on 'who are we for', 'opposable audit'. |
-| skill | [`privacy-review`](../.agent-src/skills/privacy-review/SKILL.md) |  | Use when reviewing data flows for GDPR / CCPA / HIPAA fit — regulatory-regime delta, consent shape, breach-impact triage. Triggers on 'is this GDPR-safe', 'do we need a DPA'. |
+| skill | [`privacy-review`](../.agent-src/skills/privacy-review/SKILL.md) |  | Use when reviewing data flows, support macros, refund templates for GDPR/CCPA/HIPAA fit — regime, consent, PII redaction (email, order-id), breach triage. Triggers 'is this GDPR-safe', 'PII redact'. |
 | skill | [`project-analysis-core`](../.agent-src/skills/project-analysis-core/SKILL.md) |  | Raw discovery primitives — project discovery, version resolution, docs loading, architecture mapping, execution flow. Called by `universal-project-analysis`. Single-pass scan → `project-analyzer`. |
 | skill | [`project-analysis-hypothesis-driven`](../.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md) |  | Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'. |
 | skill | [`project-analysis-laravel`](../.agent-src/skills/project-analysis-laravel/SKILL.md) |  | Use for deep Laravel project analysis: boot flow, request lifecycle, container usage, Eloquent/data flow, async systems, and Laravel-specific failure patterns. |
@@ -222,7 +222,7 @@ are excluded.
 | skill | [`voice-and-tone-design`](../.agent-src/skills/voice-and-tone-design/SKILL.md) |  | Use when shaping brand voice — voice attributes, tone-by-context matrix, consistency review. Triggers on 'define our voice', 'why does our copy sound different on every surface'. |
 | skill | [`websocket`](../.agent-src/skills/websocket/SKILL.md) |  | Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'. |
 
-## Rules (64)
+## Rules (76)
 
 | kind | name | type | description |
 |---|---|---|---|
@@ -246,6 +246,18 @@ are excluded.
 | rule | [`direct-answers`](../.agent-src/rules/direct-answers.md) | always | Always — direct, unembellished answers. No flattery, no invented facts (verify load-bearing claims, otherwise ask). Emojis only as functional markers. Brevity is the default. |
 | rule | [`docker-commands`](../.agent-src/rules/docker-commands.md) | auto | Running PHP commands inside Docker containers — artisan, composer, phpstan, rector, ecs, phpunit, tests, migrations, and any CLI tool execution |
 | rule | [`domain-adoption-policy`](../.agent-src/rules/domain-adoption-policy.md) | auto | Adopting a new domain track (mobile, ML, blockchain, IoT, gaming) — gates import on demand, ownership, CI fit, Sunset compatibility BEFORE harvest |
+| rule | [`domain-safety-disclaimer-consulting`](../.agent-src/rules/domain-safety-disclaimer-consulting.md) | auto | Drafting strategic recommendations, executive memos, board decks, or consulting deliverables — cite assumptions; flag low-confidence claims |
+| rule | [`domain-safety-disclaimer-financial`](../.agent-src/rules/domain-safety-disclaimer-financial.md) | auto | Drafting investment memos, valuation models, tax positions, or financial-advice-shaped content — require 'not financial advice' disclaimer |
+| rule | [`domain-safety-disclaimer-legal`](../.agent-src/rules/domain-safety-disclaimer-legal.md) | auto | Drafting legal briefs, contract redlines, ToS, privacy policies, or any legal-shaped content — require 'not legal advice' disclaimer in output |
+| rule | [`domain-safety-disclaimer-medical`](../.agent-src/rules/domain-safety-disclaimer-medical.md) | auto | Drafting health, wellness, medical, or therapeutic content — require 'not medical advice' disclaimer; refuse diagnostic or dosage outputs |
+| rule | [`domain-safety-export-redact`](../.agent-src/rules/domain-safety-export-redact.md) | auto | Generating CSV / Excel / API exports, partner data-shares, or analyst handoffs — redact direct identifiers; flag re-identification on quasi-IDs |
+| rule | [`domain-safety-logging-pii-floor`](../.agent-src/rules/domain-safety-logging-pii-floor.md) | auto | Writing logging code, structured logger config, or log lines — refuse to log raw PII; require redaction or a structured-field allowlist |
+| rule | [`domain-safety-pii-finance`](../.agent-src/rules/domain-safety-pii-finance.md) | auto | Drafting invoices, financial reports, AR/AP statements, or finance memos — redact counterparty PII and account/bank identifiers before output |
+| rule | [`domain-safety-pii-marketing`](../.agent-src/rules/domain-safety-pii-marketing.md) | auto | Drafting testimonials, case studies, social proof, or marketing emails referencing real customers — require consent; redact identifiers if absent |
+| rule | [`domain-safety-pii-recruiting`](../.agent-src/rules/domain-safety-pii-recruiting.md) | auto | Drafting candidate notes, interview scorecards, rejection emails, or hiring memos — redact candidate PII before output |
+| rule | [`domain-safety-pii-support`](../.agent-src/rules/domain-safety-pii-support.md) | auto | Generating support macros, ticket responses, or help-desk drafts — redact customer PII before output (names, emails, phones, account IDs, addresses) |
+| rule | [`domain-safety-retention-finance`](../.agent-src/rules/domain-safety-retention-finance.md) | auto | Finance data retention guidance — flag jurisdiction dependence, default to longest applicable retention, never delete records under audit hold |
+| rule | [`domain-safety-retention-support`](../.agent-src/rules/domain-safety-retention-support.md) | auto | Support / CRM data retention guidance — surface DSR-readiness, consent-window expiry, ticket-body retention vs. analytics aggregate retention |
 | rule | [`downstream-changes`](../.agent-src/rules/downstream-changes.md) | auto | After EVERY code edit, find ALL downstream changes needed to existing files, including callers, tests, imports, types, and documentation |
 | rule | [`e2e-testing`](../.agent-src/rules/e2e-testing.md) | auto | Playwright E2E tests — locators, assertions, Page Objects, fixtures, CI, and flaky test prevention |
 | rule | [`external-reference-deep-dive`](../.agent-src/rules/external-reference-deep-dive.md) | auto | User names an external repo, file, URL, or artifact as reference — fetch the actual tree and inspect, never summarize from README or metadata |
@@ -291,7 +303,7 @@ are excluded.
 | rule | [`user-interaction`](../.agent-src/rules/user-interaction.md) | auto | Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators |
 | rule | [`verify-before-complete`](../.agent-src/rules/verify-before-complete.md) | always | Verify before completion — run tests and quality tools before claiming done |
 
-## Commands (115)
+## Commands (124)
 
 | kind | name | cluster | description |
 |---|---|---|---|
@@ -351,6 +363,12 @@ are excluded.
 | command | [`fix:refs`](../.agent-src/commands/fix/refs.md) | cluster: fix | Find and fix broken cross-references in .augment/ and agents/ files |
 | command | [`fix:seeder`](../.agent-src/commands/fix/seeder.md) | cluster: fix | Scan seeder data files for broken foreign key references — find constants used without getReference() and fix them |
 | command | [`fix`](../.agent-src/commands/fix.md) | cluster: fix | Fix orchestrator — routes to ci, references, portability, seeder, pr-comments, pr-bot-comments, pr-developer-comments |
+| command | [`ghostwriter:delete`](../.agent-src/commands/ghostwriter/delete.md) | cluster: ghostwriter | Hard-delete a ghostwriter profile at agents/ghostwriter/<slug>.md after a two-step confirmation. No backup, no soft delete — the file is gone after acceptance. |
+| command | [`ghostwriter:fetch`](../.agent-src/commands/ghostwriter/fetch.md) | cluster: ghostwriter | Build or refresh a public-figure voice profile at agents/ghostwriter/<slug>.md from a URL or bare name; runs the public-figure attestation gate; delegates web-fetch / web-search to the host agent. |
+| command | [`ghostwriter:list`](../.agent-src/commands/ghostwriter/list.md) | cluster: ghostwriter | List captured ghostwriter profiles under agents/ghostwriter/ as a numbered table with confidence, last-fetched, and stale-warning flags. Read-only. |
+| command | [`ghostwriter:show`](../.agent-src/commands/ghostwriter/show.md) | cluster: ghostwriter | Render a single ghostwriter profile in full — identity, style fingerprint, voice samples, taboos, source URLs. Read-only. |
+| command | [`ghostwriter:write`](../.agent-src/commands/ghostwriter/write.md) | cluster: ghostwriter | Draft a markdown post in the voice of a captured public-figure ghostwriter profile; appends the mandatory non-removable disclosure footer. |
+| command | [`ghostwriter`](../.agent-src/commands/ghostwriter.md) | cluster: ghostwriter | Ghostwriter cluster — fetch, write, list, show, and delete public-figure voice profiles (the third voice primitive alongside personas/ and .agent-user.md). |
 | command | [`grill-me`](../.agent-src/commands/grill-me.md) | cluster: challenge-me | Alias for /challenge-me — interactive grill-style interview that sharpens a fuzzy plan/idea into a copyable Markdown pitch |
 | command | [`implement-ticket`](../.agent-src/commands/implement-ticket.md) |  | Drive a ticket end-to-end through refine → memory → analyze → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, block-on-ambiguity, no auto-git. |
 | command | [`jira-ticket`](../.agent-src/commands/jira-ticket.md) |  | Read Jira ticket from branch name, analyze linked Sentry issues, implement feature or fix bug |
@@ -382,6 +400,9 @@ are excluded.
 | command | [`override`](../.agent-src/commands/override.md) | cluster: override | Override orchestrator — routes to create, manage |
 | command | [`package-reset`](../.agent-src/commands/package-reset.md) |  | /package-reset |
 | command | [`package-test`](../.agent-src/commands/package-test.md) |  | /package-test |
+| command | [`post-as:ghostwriter`](../.agent-src/commands/post-as/ghostwriter.md) | cluster: post-as | Thin alias for /ghostwriter:write — drafts a copyable markdown post in a captured public-figure voice with the mandatory non-removable disclosure footer. |
+| command | [`post-as:me`](../.agent-src/commands/post-as/me.md) | cluster: post-as | Draft a copyable markdown post in the maintainer's own voice (style source = .agent-user.md.voice_sample). No disclosure footer — the user is the author. |
+| command | [`post-as`](../.agent-src/commands/post-as.md) | cluster: post-as | Consumer-facing write entry points — :me drafts in the maintainer's own voice from .agent-user.md (no disclosure); :ghostwriter is a thin alias for /ghostwriter:write (mandatory disclosure footer). |
 | command | [`prepare-for-review`](../.agent-src/commands/prepare-for-review.md) |  | Prepare a PR branch for local review — updates main and merges the full branch chain so the branch is up to date |
 | command | [`project-analyze`](../.agent-src/commands/project-analyze.md) |  | Full project analysis — detect stack, inventory modules, audit docs, create missing contexts |
 | command | [`project-health`](../.agent-src/commands/project-health.md) |  | Quick project health check — show status of docs, modules, contexts, and roadmaps without creating anything |

package/docs/contracts/adr-install-user-type-axis.md

@@ -0,0 +1,107 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
+# ADR — Install-time user-type axis
+
+> **Status:** Decided · 2026-05-15
+> **Source:** AI Council session 2026-05-15-step12-closure-run2 (Reviewer-A, Reviewer-B, Reviewer-C) D1 verdict — ACCEPT with amendments: seed all 7 user-types, cap roadmap at ≤5 phases, cap deliverables per phase.
+> **Sibling axis (distinct layer):** the runtime `personas/` ladder. The
+> install-time `user_type` axis filters *which skills load*; personas filter
+> *which voice reviews*. The two compose orthogonally.
+
+## Decision
+
+Install-time skill filtering uses a dedicated axis seeded under
+`user-types/` (package root, not `.agent-src.uncompressed/`). The
+selection lands in the consumer's `.agent-settings.yml` under
+`personal.user_type: <id>` via `agent-config install --user-type=<id>`.
+Runtime skill discovery intersects each skill's
+`recommended_for_user_types` frontmatter against
+`personal.user_type`; unset → "show all skills" (legacy behavior).
+
+The `user-types/` directory holds **seven** YAML configs — `consultant`,
+`creator`, `developer`, `finance`, `founder`, `gtm`, `ops` — matching
+every value already in active use across 32 skills' frontmatter. Adding
+an eighth value requires a new YAML plus a frontmatter audit (Phase 4).
+Schema: [`scripts/schemas/user-type-axis.schema.json`](../../scripts/schemas/user-type-axis.schema.json).
+
+## Why this is distinct from the review-lens axis
+
+Same vocabulary, different layer:
+
+| Axis | Layer | Owner roadmap | Where it bites |
+|---|---|---|---|
+| **Install filter** (this ADR) | onboarding / `.agent-settings.yml` | `step-9-user-types-axis.md` | Which skills surface first at discovery |
+| **Review lens** | runtime / `refine-ticket` | `step-6-user-types-axis.md` | Whose viewpoint a review adopts |
+
+The two never collide because they live in different files and
+different config keys. Install filter narrows *which skills load by
+default*; review lens narrows *whose voice a refine-ticket review
+adopts*. Authors can use both, neither, or one — independently.
+
+The naming overlap is preserved deliberately. Consumers think in terms
+of "I am a consultant" once; both axes consume that fact in their own
+layer. Renaming one would force consumers to learn a second vocabulary
+for the same self-identification.
+
+## Why install-time and not runtime-only
+
+Three options were considered:
+
+1. **Runtime-only filter** — read `personal.user_type` on every
+   session start, no install-time wiring. Rejected: needs the value
+   to exist before any skill loads; bootstrapping into an empty
+   `.agent-settings.yml` is fragile and undocumented.
+2. **Install-time flag, no runtime filter** — `--user-type` writes the
+   key, but skill discovery ignores it. Rejected: the value is dead
+   metadata without the discovery hook (Phase 3). Already the state of
+   the codebase before this roadmap; the whole point of step-9 is to
+   wire it.
+3. **Install-time flag + runtime filter** *(chosen)* — `--user-type`
+   writes the key; the discovery hook intersects frontmatter against
+   it. Legacy "no flag" path is preserved by treating an unset value
+   as "match all". Additive, opt-in, no breaking change.
+
+## Consequences
+
+- `scripts/install.sh`, `scripts/install.py`, `scripts/install` each
+  accept `--user-type=<id>`. Validation against `user-types/*.yml`
+  stems happens in one place (`install.py`) and the bash entry-point
+  delegates. Invalid values fail fast with a non-zero exit.
+- `config/agent-settings.template.yml` keeps a commented
+  `personal.user_type:` stub documenting the seven valid values.
+- The existing `--interactive` flag (legacy `.agent-config.local.json`
+  stub) is preserved for backward compat; the new flag is the
+  first-class path going forward. A future ADR can deprecate the JSON
+  stub once consumers migrate.
+- Frontmatter audit (Phase 4) catches drift: every value used in
+  `recommended_for_user_types` MUST have a corresponding YAML, and
+  every YAML SHOULD be consumed by at least one skill. The audit ships
+  as a CI gate (`task lint-user-type-axis` →
+  [`scripts/audit_user_type_axis.py`](../../scripts/audit_user_type_axis.py)).
+  Initial sweep at Phase 4 close: 7 declared / 7 used / 0 orphans / 0
+  unused — coverage is clean, no rename or backfill needed. Report:
+  [`agents/reports/user-type-axis-audit.md`](../../agents/reports/user-type-axis-audit.md).
+- Adding an 8th value is non-trivial by design — it requires a YAML, a
+  schema-compatible frontmatter rollout, and a roadmap entry. The
+  friction is the feature: a sprawling axis defeats the purpose of
+  filtering.
+
+## Open questions deferred
+
+- Skill-loader hook location is left to Phase 3 — likely
+  `scripts/skill_linter.py`'s discovery pass plus a runtime helper for
+  agent hosts that read the axis directly.
+- Whether to surface a "show outside `<id>` filter" affordance in
+  agent hosts is left to host-side UX, not enforced by this ADR.
+- The `default_skill_priority` field is informational in v1 (no
+  loader consumes it yet). Phase 3 may promote it to a sort key.
+
+## See also
+
+- [`user-types/README.md`](../../user-types/README.md) — schema + seed table
+- [`docs/contracts/universal-skills.md`](universal-skills.md) — always-loaded floor
+- [`docs/contracts/rule-router.md`](rule-router.md) — kernel + router
+  architecture (sibling but orthogonal axis)

package/docs/contracts/agent-user-schema.md

@@ -163,3 +163,4 @@ Copy it to the project root as `.agent-user.md` and edit, or run
 
 - [`language-and-tone`](../../.agent-src/rules/language-and-tone.md) — language-mirroring rule the loader feeds.
 - [`agents-md-thin-root`](../../.agent-src/skills/agents-md-thin-root/SKILL.md) — Thin-Root contract that this file complements (user-state vs project-state).
+- [`ghostwriter-schema`](ghostwriter-schema.md) — sibling voice primitive for **external public-figure** voices (`/ghostwriter:write`, mandatory disclosure footer). `.agent-user.md` covers the maintainer's **own** voice (`/post-as:me`, no footer); the three-primitive model is summarised in [`personas/README.md § See also — sibling voice primitives`](../../.agent-src/personas/README.md).

package/docs/contracts/command-clusters.md

@@ -47,6 +47,8 @@ column 1 of this table.
 | `research` | 2 | `deep` · `report` | preliminary-research scaffolder ported from `Weizhena/Deep-Research-skills` (cluster head emits `outline.yaml` + `fields.yaml` against the `research-schema` contract). `:deep` populates per-item JSON in batches with native web-search + JSON-Schema self-validation (no Python runtime); `:report` renders `report.md` directly + optionally emits a `jq` template for deterministic regeneration. `add-items` / `add-fields` intentionally **not** ported — re-run `/research <topic>` to extend the field framework. |
 | `orchestrate` | — | _(none yet — cluster head only)_ | new — runtime executor for YAML pipelines under `.agent-config/orchestrations/` per the [`orchestration-dsl-v1`](orchestration-dsl-v1.md) contract; chains personas / skills / commands / sub-agents deterministically. Single cluster head; sub-commands deferred until a second verb is needed. |
 | `sync-gitignore` | — | `fix` | new sub-command 2026-05-11 — cluster head retains the existing append-only sync as its default flow; `:fix` adds `--cleanup-legacy` semantics, scrubbing pre-`/agents/` runtime patterns wherever they appear in the consumer's `.gitignore` (inside or outside the managed block) and re-syncing the canonical entries. |
+| `ghostwriter` | — | `fetch` · `write` · `list` · `show` · `delete` | new cluster 2026-05-15 — third voice primitive for AI-assisted writing in the public voice of a public figure. Hybrid storage: real-person profiles live consumer-side under `agents/ghostwriter/<slug>.md` (gitignored by default); package source ships only `fictional: true` fixtures. Zero network code in the package — `:fetch` delegates web-fetch / web-search to the host agent. Mandatory disclosure footer on every `:write` output (no opt-out). Schema: [`ghostwriter-schema`](ghostwriter-schema.md). |
+| `post-as` | — | `me` · `ghostwriter` | new cluster 2026-05-15 — consumer-facing write entry points. `:me` reads `.agent-user.md.voice_sample` and drafts in the maintainer's own voice (no disclosure footer — the user is the author); `:ghostwriter` is a thin alias for `/ghostwriter:write` with the mandatory disclosure footer. Both share the procedural [`write-engine`](write-engine.md) contract — style source and footer are the only axes of variation. |
 
 **Net change:** Phase 1 collapsed 15 atomics → 3 clusters; Phase 2
 collapses 26 atomics → 11 sub-command clusters. Sub-commands use