@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/write-engine.md

@@ -1,182 +0,0 @@
----
-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/reference/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. `--raw`
-skips the step-4b humanize audit for this run (see § 4b).
-
-#### 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.
-
-### 4b. Humanize audit (default-on, `--raw` opts out)
-
-After drafting and before the footer, run the AI-tell audit from the
-[`humanizer`](../../src/skills/humanizer/SKILL.md) skill against the
-draft body:
-
-1. Ask: "What makes this draft read AI-generated?" — audit against the
-   pattern catalog (`src/skills/humanizer/data/patterns.md`), counting
-   clusters, never isolated hits.
-2. Revise the draft to clear the audit findings while preserving the
-   step-4 fingerprint constraints and full coverage.
-3. Where a runtime is available, verify the final body with
-   `npx tsx src/scripts/detect_ai_tells.ts --stdin --fail` under the
-   thresholds from the consumer's `humanizer:` block in
-   `.agent-project-settings.yml` (defaults: hard 0, cluster score 3 per
-   500 words, dash density 2 per 500 words). No runtime → the prose
-   audit in (1) is the pass; do not skip it.
-
-Precedence and scope rules (binding, not judgment calls):
-
-- **Fingerprint wins.** When the profile's captured voice legitimately
-  uses a watched pattern (a figure who genuinely writes in em dashes,
-  `emoji_rules: allowed`, hashtag rules), the step-4 fingerprint
-  constraint is authoritative and the corresponding tell is suppressed
-  for that run.
-- **The disclosure footer (§ 5) is exempt.** It is a literal template
-  string appended after this step — the audit never inspects, rewords,
-  or removes it.
-- **Technical/reference output is excluded.** When the requested
-  artifact is reference or technical documentation, skip step 4b and
-  say so — neutral, plain prose is the correct register there.
-- **`--raw` opts out per run.** The flag skips step 4b entirely (for
-  deliberate neutral-register output); it never touches the footer
-  rules. Default is on for every engine consumer
-  (`humanizer.write_engine: on`).
-
-### 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.
-- **Quote floor applies.** Any draft citing an external source follows
-  [`content-quoting-floor`](../../src/rules/content-quoting-floor.md) —
-  ≤15 words per quote, one quote per source, paraphrase by default.
-
-## 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/cookbook.md

@@ -1,152 +0,0 @@
-# Cookbook — things you can do in a minute
-
-> **Generated** by `scripts/generate_cookbook.py` from `src/flows/cookbook.yaml` + `src/flows/<flow>.yaml` — do NOT hand-edit.
-> Every command and skill below is validated to exist at generation time; a recipe naming a missing command fails the build.
-
-Each recipe is a short command sequence. Run the commands in order; the listed skills are the capabilities they compose.
-
-## Named recipes
-
-### Review a change before it ships
-
-*You have a diff and want a real review, not a rubber-stamp.*
-
-- **Commands:** `/review:changes` → `/judge` → `/fix:quality`
-- **Skills:** `code-review`, `adversarial-review`
-
-### Fix a red CI run
-
-*CI is failing and you want the failure pinpointed and fixed.*
-
-- **Commands:** `/fix:ci`
-- **Skills:** `systematic-debugging`
-
-### Build a feature from a ticket
-
-*You have a ticket and want it refined, estimated, and implemented.*
-
-- **Commands:** `/refine-ticket` → `/estimate-ticket` → `/implement-ticket`
-- **Skills:** `feature-planning`, `test-driven-development`
-
-### Plan a feature before writing code
-
-*The ask is fuzzy and you want a bounded plan first.*
-
-- **Commands:** `/feature:explore` → `/feature:plan`
-- **Skills:** `feature-planning`, `complexity-first-planning`
-
-### Security-audit a surface
-
-*You touched auth / billing / tenancy and want abuse cases first.*
-
-- **Commands:** `/threat-model` → `/judge:solo`
-- **Skills:** `threat-modeling`, `security-audit`
-
-### Open a pull request
-
-*The work is done and you want a clean PR ready for review.*
-
-- **Commands:** `/prepare-for-review` → `/pr:create`
-- **Skills:** `requesting-code-review`, `conventional-commits-writing`
-
-### Research a topic deeply
-
-*You need a multi-source, fact-checked report, not a guess.*
-
-- **Commands:** `/research:deep` → `/research:report`
-- **Skills:** `deep-reading-analyst`
-
-### Investigate and fix a bug
-
-*Something is broken and you want root cause before the patch.*
-
-- **Commands:** `/bug:investigate` → `/bug:fix`
-- **Skills:** `systematic-debugging`, `bug-analyzer`
-
-### Get a second opinion from the AI council
-
-*A design call is genuinely contested and you want independent models.*
-
-- **Commands:** `/council:design` → `/council:debate`
-- **Skills:** `ai-council`
-
-### Process a roadmap autonomously
-
-*You have a roadmap and want it worked end-to-end.*
-
-- **Commands:** `/roadmap:create` → `/roadmap:process-full`
-- **Skills:** `roadmap-management`
-
-### Refactor with a safety net
-
-*You want to restructure code without changing behaviour.*
-
-- **Commands:** `/feature:refactor` → `/review:changes` → `/judge`
-- **Skills:** `code-refactoring`, `test-driven-development`
-
-### Commit in logical chunks
-
-*You have a messy working tree and want clean, scoped commits.*
-
-- **Commands:** `/commit:in-chunks`
-- **Skills:** `conventional-commits-writing`
-
-### Analyze an unfamiliar project
-
-*You just opened a repo and want a fast structural read.*
-
-- **Commands:** `/project:analyze` → `/project:health`
-- **Skills:** `project-analyzer`
-
-### Estimate a ticket
-
-*You need a defensible estimate with the reasoning shown.*
-
-- **Commands:** `/estimate-ticket`
-- **Skills:** `estimate-ticket`
-
-### Run a blame-free post-mortem that teaches the next change
-
-*An incident, near-miss, or risky plan needs analysis that closes the learning loop.*
-
-- **Commands:** `/analyze`
-- **Skills:** `blameless-post-mortem`, `root-cause-frameworks`
-
-### Upgrade a Laravel app one major version
-
-*You want a gated, catalog-driven Laravel major-version upgrade (10→11) on a provisional branch — never auto-PR.*
-
-- **Commands:** `/mission:upgrade`
-- **Skills:** `dependency-upgrade`
-
-## The four work flows
-
-Broader than a single recipe — the end-to-end shapes most work follows.
-
-### Discovery flow
-
-Explore, plan, estimate, refine, and investigate before building. The "what should we build and how" front of the developer journey.
-
-- **Path:** `/feature:explore` → `/feature:plan` → `/estimate-ticket` → `/refine-ticket`
-- **Skills:** `feature-planning`, `estimate-ticket`, `refine-ticket`, `project-analysis-core`, `validate-feature-fit`
-
-### Implementation flow
-
-Build it. The core "make the change" front — drive a prompt, ticket, or feature end-to-end through plan → implement → verify.
-
-- **Path:** `/work` → `/review:changes` → `/fix:quality` → `/commit`
-- **Skills:** `test-driven-development`, `code-review`, `systematic-debugging`, `git-workflow`
-
-### Review flow
-
-Check it. Self-review, judge, fix/quality, and threat-model a change before it ships.
-
-- **Path:** `/review:changes` → `/judge` → `/fix:quality` → `/threat-model`
-- **Skills:** `code-review`, `adversarial-review`, `quality-tools`, `threat-modeling`, `receiving-code-review`
-
-### Delivery flow
-
-Ship it. Commit in logical chunks, open the PR, answer review comments, and prepare the branch for review.
-
-- **Path:** `/commit` → `/pr:create` → `/fix:pr-comments`
-- **Skills:** `conventional-commits-writing`, `git-workflow`, `requesting-code-review`