@event4u/agent-config 1.39.0 → 1.41.0

package/CHANGELOG.md

@@ -318,6 +318,81 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.41.0](https://github.com/event4u-app/agent-config/compare/1.40.0...1.41.0) (2026-05-12)
+
+### Features
+
+* **mcp/worker:** add optional MCP-Token Bearer auth ([134c6ee](https://github.com/event4u-app/agent-config/commit/134c6ee34ee5fc1f1809f5be72df1ac82ad0cca6))
+* **mcp:** L2+L4 — implement 7 read-only tools + catalog sync ([44a0082](https://github.com/event4u-app/agent-config/commit/44a00827a7e19051e58e2a5866a37e8c6e4fb1a6))
+* **mcp:** K1+K2 — telemetry SQLite store + CLI dashboard ([e53f321](https://github.com/event4u-app/agent-config/commit/e53f321d3d6a7fb5c95a97232898fbda15cd129b))
+* **mcp:** J6 — telemetry healthcheck + consumer discovery notice ([41f02f7](https://github.com/event4u-app/agent-config/commit/41f02f773feb6248ea315e0820d2a81d960b98c9))
+* **mcp:** J1-J4 — discovery catalog + stub envelope + telemetry ([38aff65](https://github.com/event4u-app/agent-config/commit/38aff651138d8c20929cab88ac437f3106ba44c3))
+
+### Documentation
+
+* **mcp:** remove public endpoint, document self-hosting + Bearer auth ([6c5d7b0](https://github.com/event4u-app/agent-config/commit/6c5d7b04231e9e274265e7f0481502455085f748))
+
+### Refactoring
+
+* **scripts:** migrate readers to centralized agent_settings loader ([7849c03](https://github.com/event4u-app/agent-config/commit/7849c03f282cdaf344ac56056d55cb1c63e17eba))
+
+### Tests
+
+* **mcp:** L3 — hermetic shape contracts for 7 RO tools ([0d3edc9](https://github.com/event4u-app/agent-config/commit/0d3edc9fb1f98df80a4eb503a0dd4c868d2f85f2))
+* **mcp:** J5 — acceptance tests for catalog, envelope, telemetry ([806e4bb](https://github.com/event4u-app/agent-config/commit/806e4bb2bdd2292dfb75eddd9b4eff6073f16a00))
+
+### Chores
+
+* **mcp/taskfile:** add mcp:cloud:secret-put task ([dcffef5](https://github.com/event4u-app/agent-config/commit/dcffef5c384bf75261189b035417593418c8c36c))
+* **roadmap:** flip Phase 2 + Phase 3 of road-to-mcp-full-coverage ([2ce23bc](https://github.com/event4u-app/agent-config/commit/2ce23bcaf7482aeb095cc85d106a78ac5c0d2682))
+* **roadmap:** flip Phase 1 of road-to-mcp-full-coverage (J1–J6) ([707f5c0](https://github.com/event4u-app/agent-config/commit/707f5c002f827b2600cfcf6019d3d22166b46fc2))
+* **ci:** regenerate derived artifacts and fix command-count drift ([dd4eeac](https://github.com/event4u-app/agent-config/commit/dd4eeac96094d99bae318b2160a914be46caead9))
+* **roadmaps:** archive road-to-portable-dev-preferences ([77f4cf1](https://github.com/event4u-app/agent-config/commit/77f4cf1825962503891973800450c3ca769e2adc))
+
+Tests: 3173 (+32 since 1.40.0)
+
+## [1.40.0](https://github.com/event4u-app/agent-config/compare/1.39.0...1.40.0) (2026-05-11)
+
+### Features
+
+* **settings:** add worktrees.mode (off/on/ask) to gate autonomous worktree usage ([a07080f](https://github.com/event4u-app/agent-config/commit/a07080f28113dfa2452830b660deb4cb467256ec))
+* **commands:** add /sync-gitignore:fix subcommand for legacy cleanup ([5b058b0](https://github.com/event4u-app/agent-config/commit/5b058b0a8a5b451eac89c4905076e4cc9773e299))
+* **audit:** add pattern-extraction script for audit-log-v1 (roadmap Q2) ([966e472](https://github.com/event4u-app/agent-config/commit/966e47215eb80cfff6e2229b90c6e28b806c7dff))
+* **learning-skill:** wire audit-log-v1 into learning-to-rule-or-skill (roadmap Q3) ([f53d129](https://github.com/event4u-app/agent-config/commit/f53d12947b41334c58952b3a6017962507abbe45))
+* **orchestrate:** add /orchestrate command + state machine (roadmap G2) ([4b39691](https://github.com/event4u-app/agent-config/commit/4b396910c0c7078430aa11958f121d49ddda766c))
+* **contracts:** add orchestration-dsl-v1 + linter (roadmap G1) ([5cb2801](https://github.com/event4u-app/agent-config/commit/5cb2801f14a06d2dabe9f2dc57b7ca424d7e4d4d))
+* **contracts:** add audit-log-v1 schema (roadmap Q1) ([e0849b2](https://github.com/event4u-app/agent-config/commit/e0849b2305949ad5409ff9981970922ec702c68e))
+* **install:** one-liner setup.sh + npm wrapper refinements ([aee688f](https://github.com/event4u-app/agent-config/commit/aee688fcbf9bb18b0253bc7ce96192cc7e5afe2e))
+* **compress:** project Cursor .mdc + Windsurf .md rules + flatten commands ([486bafd](https://github.com/event4u-app/agent-config/commit/486bafd83c1f5224ee61b29b46cc827b21440623))
+* **install:** multi-tool installer + global user-level install ([6113872](https://github.com/event4u-app/agent-config/commit/6113872b146321b784b01a428c5c2abcbad9e08d))
+
+### Bug Fixes
+
+* **ci:** bump README command count and exclude projection dirs from skill-lint ([c5a1493](https://github.com/event4u-app/agent-config/commit/c5a1493d4ef31b2e9af16e0945330cccaa02576c))
+* **clusters:** register /orchestrate as new cluster head ([fb73e58](https://github.com/event4u-app/agent-config/commit/fb73e58c7eb72d53e6ee111a18fe8f5a1f1e053b))
+* **roadmap:** annotate council reference with allowed-marker ([e2997d0](https://github.com/event4u-app/agent-config/commit/e2997d00b5e7dc2625367f87dab3bc611b9cf8e5))
+* **readme:** unlink experimental mcp-cloud-scope contract ([c7ac883](https://github.com/event4u-app/agent-config/commit/c7ac883be116e6f92f2125d5334f38f17b97da27))
+
+### Documentation
+
+* bump command count to 105 for /orchestrate ([df49c6c](https://github.com/event4u-app/agent-config/commit/df49c6c268e08df7567128c97cc267fed9e38694))
+
+### Refactoring
+
+* **roadmap:** apply council shape-fix to distribution roadmap ([4c7f770](https://github.com/event4u-app/agent-config/commit/4c7f770d66b07107164c2eafcc886ddf6bf29aa6))
+* **distribution:** extract marketplace listings to docs/DISTRIBUTION_CHECKLIST.md ([5fc6075](https://github.com/event4u-app/agent-config/commit/5fc607567a96bc5e3d9a38d276ce85f88dae7015))
+* **roadmap:** move S33 (screencasts) to distribution roadmap H5 ([95d27f6](https://github.com/event4u-app/agent-config/commit/95d27f65b577824d9c330478af5c7c7acddfe9f3))
+
+### Chores
+
+* **ownership:** regenerate ownership matrix for new files ([f728343](https://github.com/event4u-app/agent-config/commit/f728343cd4bc9a7340bb19a218d1ccdc6b5bfb9e))
+* **index:** tag orchestrate command with cluster in catalogs ([c4ed9ee](https://github.com/event4u-app/agent-config/commit/c4ed9ee9eaca972bc35549330131c98dd6b05966))
+* **index:** regenerate catalog for /orchestrate command ([c6fe13a](https://github.com/event4u-app/agent-config/commit/c6fe13ae9d83e142154226235bf65d1d2f72cacd))
+* **roadmaps:** regen dashboard after distribution-roadmap shape-fix ([e0ad5b3](https://github.com/event4u-app/agent-config/commit/e0ad5b3554d34a4eaaf747b0955cc16e32f5c8e2))
+* **roadmaps:** archive road-to-simplicity-and-everywhere + regen dashboard ([d2d5c31](https://github.com/event4u-app/agent-config/commit/d2d5c310db1ec8fd3cd44111400b098c4d99c856))
+
+Tests: 3141 (+442 since 1.39.0)
+
 ## [1.39.0](https://github.com/event4u-app/agent-config/compare/1.38.0...1.39.0) (2026-05-11)
 
 ### Features

package/README.md

@@ -7,7 +7,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>174 Skills</strong> · <strong>60 Rules</strong> · <strong>104 Commands</strong> · <strong>69 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>174 Skills</strong> · <strong>60 Rules</strong> · <strong>106 Commands</strong> · <strong>69 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -90,40 +90,66 @@ Install directly in your agent for global, cross-project use:
 → [Full getting started guide](docs/getting-started.md) ·
 [More examples & expected behavior](docs/showcase.md)
 
-### Remote MCP — zero install
+### Self-hosted MCP on Cloudflare — zero local install
 
-Skills, commands, rules, and guidelines are also served as a hosted MCP
-endpoint. No clone, no `task mcp:setup`, no Python venv — point any
-MCP-capable client (Claude Desktop, Cursor, Zed, Continue, hosted agents)
-at:
+Skills, commands, rules, and guidelines can be served as an MCP endpoint
+from your own Cloudflare Worker — no clone, no `task mcp:setup`, no
+Python venv on the consumer machine, just an HTTP URL any MCP client
+(Claude Desktop, Claude Code, Cursor, Zed, Continue, hosted agents)
+talks to.
 
-```
-https://agent-config-mcp.event4u.workers.dev
+The Worker source lives in `workers/mcp/`; deploying it to your own
+Cloudflare account takes ~5 minutes:
+
+```bash
+task mcp:cloud:login         # one-time, opens browser
+task mcp:cloud:setup         # check → r2-create → r2-verify → whoami
+task mcp:cloud:secret-put    # set MCP-Token (Bearer auth, recommended)
+# Then deploy via CI — see operator guide below.
 ```
 
-Verify it's live:
+After deploy your Worker lives at
+`https://agent-config-mcp.<your-account>.workers.dev` (or a custom
+domain you wire in Step 7 of the operator guide). Verify:
 
 ```bash
-curl https://agent-config-mcp.event4u.workers.dev
+curl https://agent-config-mcp.<your-account>.workers.dev
 # → { "ok": true, "name": "agent-config-mcp", "release_key": "v…", … }
 ```
 
-Read-only, identity-stable per release. Per-client setup snippets
-(Claude Desktop, Claude Code, Cursor, Zed, Continue) —
-[`docs/setup/mcp-client-config.md`](docs/setup/mcp-client-config.md).
-URL shapes (latest vs. pinned `/v<X.Y.Z>`) —
-[`docs/setup/mcp-cloud-endpoints.md`](docs/setup/mcp-cloud-endpoints.md).
-Operator setup (account, R2, secrets) — [`docs/setup/mcp-cloud-setup.md`](docs/setup/mcp-cloud-setup.md).
+Per-client setup snippets (Claude Desktop, Claude Code, Cursor, Zed,
+Continue) — [`docs/setup/mcp-client-config.md`](docs/setup/mcp-client-config.md).
+URL shapes (latest vs. pinned `/v<X.Y.Z>`) — [`docs/setup/mcp-cloud-endpoints.md`](docs/setup/mcp-cloud-endpoints.md).
+Full operator walkthrough (account, R2, GitHub secrets, deploy) —
+[`docs/setup/mcp-cloud-setup.md`](docs/setup/mcp-cloud-setup.md).
 Experimental — A0-cloud contract lives at `docs/contracts/mcp-cloud-scope.md` (internal reference only per `STABILITY.md`).
 
-> **Scope — Lite, not Full.** The hosted MCP endpoint serves the
-> read-only governance surface (skills · commands · rules · guidelines
-> · contexts) as MCP prompts and resources. It does **not** execute any
-> of the ~112 Python scripts that ship with the package (linters,
-> audits, `task ci`, work-engine hooks, …). Those require the full
-> local install per [Quickstart](#quickstart). See
-> [`docs/contracts/mcp-cloud-scope.md`](docs/contracts/mcp-cloud-scope.md)
-> for the execution-safety boundary.
+#### Lock your Worker behind a Bearer token
+
+Without auth, any MCP client that knows your `*.workers.dev` URL can
+read the catalog. For private deploys, set the `MCP-Token` secret and
+the Worker will require `Authorization: Bearer <token>` on every POST:
+
+```bash
+task mcp:cloud:secret-put          # wraps `npx wrangler secret put MCP-Token --name agent-config-mcp`
+# wrangler prompts for the value interactively — never passed via argv.
+```
+
+Once the secret is set, every client config block needs the token in
+its headers — see [`docs/setup/mcp-client-config.md`](docs/setup/mcp-client-config.md) § Bearer auth for the
+per-client snippets (Claude Desktop, Claude Code, Cursor, Zed,
+Continue). The `GET /` liveness probe stays open so health checks keep
+working without the token.
+
+> **Scope — Lite, not Full.** The Worker serves the read-only governance
+> surface (skills · commands · rules · guidelines · contexts) as MCP
+> prompts and resources, plus a small set of read-only tools (`memory_lookup`,
+> `chat_history_read`, `list_*`, `read_resource_body`). It does **not**
+> execute any of the ~112 Python scripts that ship with the package
+> (linters, audits, `task ci`, work-engine hooks, …). Those require the
+> full local install per [Quickstart](#quickstart). See
+> `docs/contracts/mcp-cloud-scope.md` (internal reference only per
+> `STABILITY.md`) for the execution-safety boundary.
 
 ### Optional: persistent agent memory
 
@@ -378,7 +404,7 @@ kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-member
 | [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
 | [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
 
-→ [Browse all 104 active commands](.agent-src/commands/)
+→ [Browse all 106 active commands](.agent-src/commands/)
 
 ---
 
@@ -403,7 +429,7 @@ Every developer gets the same behavior. No per-user setup needed.
 native slash-commands)
 
 > **What this means in practice:** Augment Code and Claude Code get the full
-> package (rules + 174 skills + 104 native commands). Cursor, Cline, Windsurf,
+> package (rules + 174 skills + 106 native commands). Cursor, Cline, Windsurf,
 > Gemini CLI, and GitHub Copilot only get the **rules** natively; skills and
 > commands are available to them as documentation the agent can read, not as
 > first-class features.

package/bin/install.php

@@ -12,12 +12,19 @@ declare(strict_types=1);
  * invoke it via `php vendor/bin/install.php` without knowing about bash.
  *
  * Usage:
- *   php vendor/bin/install.php                     # full install
- *   php vendor/bin/install.php --profile=balanced  # pick cost profile
- *   php vendor/bin/install.php --force             # overwrite existing bridges
- *   php vendor/bin/install.php --skip-bridges      # payload only
- *   php vendor/bin/install.php --skip-sync         # bridges only
- *   php vendor/bin/install.php --help              # full option list
+ *   php vendor/bin/install.php                              # full install (every tool)
+ *   php vendor/bin/install.php --profile=balanced           # pick cost profile
+ *   php vendor/bin/install.php --tools=claude-code,cursor   # only those two surfaces
+ *   php vendor/bin/install.php --tools=cursor --yes         # CI-friendly, single tool
+ *   php vendor/bin/install.php --list-tools                 # show valid tool IDs
+ *   php vendor/bin/install.php --force                      # overwrite existing bridges
+ *   php vendor/bin/install.php --skip-bridges               # payload only
+ *   php vendor/bin/install.php --skip-sync                  # bridges only
+ *   php vendor/bin/install.php --help                       # full option list
+ *
+ * Valid --tools IDs (default: all):
+ *   claude-code, claude-desktop, cursor, windsurf, cline,
+ *   gemini-cli, copilot, augment, aider, codex, all
  */
 
 $packageRoot = dirname(__DIR__);

package/config/agent-settings.template.yml

@@ -197,6 +197,27 @@ subagents:
   # Integer, default 3. Set to 1 to serialize. Hard cap enforced by runtime.
   max_parallel: 3
 
+# --- Git worktrees ---
+#
+# Controls how the `using-git-worktrees` skill and `subagent-orchestration`
+# mode 6 (`do-in-worktrees`) behave. Mechanical layer on top of the
+# existing `scope-control` permission gate — narrows, never widens.
+worktrees:
+  # off | on | ask  (default: ask)
+  #
+  # ask = status quo. Skill asks before creating any worktree; mode 6 is
+  #       selectable when the chain shape warrants it. Matches the
+  #       behaviour required by `scope-control` and `autonomous-execution`.
+  # off = no autonomous worktree creation. Skill refuses; mode 6 falls
+  #       back to mode 3 (do-in-steps). Explicit user request in the
+  #       chat ("do this in a worktree", "use mode 6") overrides for
+  #       that single task — the setting suppresses *unprompted* usage,
+  #       not the tool itself.
+  # on  = standing permission. Skill skips the per-creation permission
+  #       ask; mode 6 may be picked without prompting. Iron-Law gates
+  #       (ignore-check, clean baseline) still apply.
+  mode: ask
+
 # --- AI Council (external second-opinion network) ---
 #
 # When enabled, the /council command lets the agent poll independent

package/docs/DISTRIBUTION_CHECKLIST.md

@@ -0,0 +1,169 @@
+# Distribution Checklist
+
+External marketplace, registry, and marketing actions for
+`event4u/agent-config`. **Human-gated work.** Items here cannot be
+executed by an autonomous agent — they require credentials, manual
+web-form submissions, terminal-recording on a maintainer's machine,
+content authoring, or external approval processes. Tracked separately
+from the roadmap dashboard so the agent step counter stays honest.
+
+## Origin
+
+Lifted from archived
+[`agents/roadmaps/archive/road-to-simplicity-and-everywhere.md`](../agents/roadmaps/archive/road-to-simplicity-and-everywhere.md)
+Phase 7 (S34–S38) after a follow-up AI Council review flagged the
+category error of tracking external-action items inside an
+engineering roadmap. See the "Post-merge addendum" in that archive
+for the full lessons-learned.
+
+## Status vocabulary
+
+- **Prepared** — substrate (config file, package source, copy) committed.
+- **Submitted** — handed to the external queue.
+- **In Review** — accepted into review queue, awaiting approval.
+- **Live** — listing public, install path verified end-to-end.
+- **Blocked** — gated on an external dependency; see Notes.
+
+`[ ]`/`[x]` markers are **deliberately not used** here — these items
+are not roadmap steps.
+
+## Items
+
+### Anthropic Claude Code plugin marketplace
+
+- **Status:** Prepared
+- **Owner:** maintainer
+- **Last Reviewed:** 2026-05-12
+- **Substrate:** [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json)
+  committed and current. Slug `event4u/agent-config` is canonical
+  across all listings.
+- **Doc anchor:** [`docs/setup/per-ide/claude-code.md`](setup/per-ide/claude-code.md)
+  § "Plugin marketplace".
+- **Action:** Submit via Anthropic plugin marketplace review queue
+  per current Claude Code plugin docs.
+- **Pre-conditions:** none (substrate ready).
+- **Notes:** Source of truth for naming — Cursor / Smithery listings
+  reference this slug.
+
+### Cursor 2026 marketplace listing
+
+- **Status:** Prepared
+- **Owner:** maintainer
+- **Last Reviewed:** 2026-05-12
+- **Substrate:** [`templates/marketing-copy.yml`](../templates/marketing-copy.yml)
+  is the single source for listing copy across surfaces.
+- **Doc anchor:** [`docs/setup/per-ide/cursor.md`](setup/per-ide/cursor.md)
+  § "Marketplace install".
+- **Action:** Submit to Cursor's 2026 marketplace listing process.
+- **Pre-conditions:** Anthropic listing live (link as primary source
+  to avoid drift).
+- **Notes:** Per "Decisions" in archived roadmap — Anthropic listing
+  is canonical, others reference by stable slug.
+
+### Smithery (MCP server registry)
+
+- **Status:** Blocked
+- **Owner:** maintainer
+- **Last Reviewed:** 2026-05-12
+- **Substrate:** none yet — MCP server itself is not publishable.
+- **Doc anchor:** none yet.
+- **Action:** Submit to Smithery once the MCP server can be installed
+  and exercised end-to-end.
+- **Pre-conditions:** [`road-to-mcp-full-coverage.md`](../agents/roadmaps/road-to-mcp-full-coverage.md)
+  Phase 3 (Selective Implementation) shipped.
+- **Notes:** **Do not submit before the gate.** Premature listing
+  produces a bad first impression and is hard to retract.
+
+### npm: `@event4u/create-agent-config`
+
+- **Status:** Prepared
+- **Owner:** maintainer
+- **Last Reviewed:** 2026-05-12
+- **Substrate:** [`packages/create-agent-config/`](../packages/create-agent-config/)
+  source is ready; the wrapper clones the repo to a temp dir, runs
+  `scripts/install`, then deletes the temp dir.
+- **Doc anchor:** [`docs/installation.md`](installation.md) §
+  "npx one-liner".
+- **Action:** `npm publish --access public` from `packages/create-agent-config/`.
+- **Pre-conditions:** npm registry credentials for the `@event4u`
+  scope.
+- **Notes:** Public scope, MIT-licensed. Verify `npx
+  @event4u/create-agent-config init` in an empty directory before
+  declaring Live.
+
+### GitHub repo topics + tagline
+
+- **Status:** Prepared
+- **Owner:** maintainer
+- **Last Reviewed:** 2026-05-12
+- **Substrate:** Topic list + tagline copy live in
+  [`templates/marketing-copy.yml`](../templates/marketing-copy.yml).
+- **Doc anchor:** none (GitHub-native).
+- **Action:** Apply via `gh repo edit` (or repo Settings → General).
+  Topics: `agent`, `claude-code`, `cursor`, `windsurf`, `cline`,
+  `mcp`, `agents-md`, `skill-files`. Description: one-line tagline
+  matching the marketplace copy.
+- **Pre-conditions:** none.
+- **Notes:** Per `scope-control` rule, repo-settings changes are
+  permission-gated and run by the maintainer.
+
+### Medium / dev.to articles + conference CFP
+
+- **Status:** Blocked
+- **Owner:** unassigned
+- **Last Reviewed:** 2026-05-12
+- **Substrate:** none — copy authored per submission.
+- **Doc anchor:** none yet.
+- **Action:** Owner authors articles (Medium / dev.to), submits CFP
+  to relevant conferences. Cadence aligned to the 1 day/week
+  marketing cap from `road-to-distribution-and-adoption.md` Phase 1.
+- **Pre-conditions:** owner + budget assigned; Phase 1 pre-conditions
+  1–4 from the distribution roadmap met (Thinking A+C ≥80%,
+  post-pr29 1.15.0, `docs/contracts/` policy active).
+- **Notes:** Origin: `road-to-distribution-and-adoption.md` H4 (moved
+  here 2026-05-11 after AI Council convergence on category-error
+  filter: "owner + budget assigned first" is non-agent action). The
+  roadmap step is `[-]` cancelled with a back-reference.
+
+### Screencasts / asciinema casts per primary surface
+
+- **Status:** Blocked
+- **Owner:** unassigned
+- **Last Reviewed:** 2026-05-12
+- **Substrate:** the `## Verification` block in every
+  [`docs/setup/per-ide/<surface>.md`](setup/per-ide/) page is the
+  cast script — agent-shipped, ready to record against.
+- **Doc anchor:** [`docs/setup/per-ide/claude-code.md`](setup/per-ide/claude-code.md),
+  [`docs/setup/per-ide/cursor.md`](setup/per-ide/cursor.md),
+  [`docs/setup/per-ide/windsurf.md`](setup/per-ide/windsurf.md),
+  [`docs/setup/per-ide/claude-desktop.md`](setup/per-ide/claude-desktop.md).
+- **Action:** Record asciinema cast on a real maintainer machine
+  following each surface's Verification block; embed under the
+  surface doc.
+- **Pre-conditions:** all four per-IDE docs landed with stable
+  Verification blocks (shipped via archived
+  `road-to-simplicity-and-everywhere.md`).
+- **Notes:** Origin: `road-to-distribution-and-adoption.md` H5
+  (moved here 2026-05-11 after AI Council convergence — terminal
+  capture on a real machine is non-agent action; substrate was
+  already shipped, the cast itself is the human-gated step). The
+  roadmap step is `[-]` cancelled with a back-reference.
+
+## Review cadence
+
+Refresh `Last Reviewed` each time an item is revisited or its status
+changes. Stale items (`Last Reviewed` older than 90 days while not
+`Live`) should surface in a manual review pass — no automated
+enforcement, this file is deliberately out of the agent's execution
+loop.
+
+## See also
+
+- [`agents/roadmaps/archive/road-to-simplicity-and-everywhere.md`](../agents/roadmaps/archive/road-to-simplicity-and-everywhere.md)
+  — origin (Phase 7, S34–S38) and lessons-learned addendum.
+- [`agents/roadmaps/road-to-distribution-and-adoption.md`](../agents/roadmaps/road-to-distribution-and-adoption.md)
+  § "External distribution (human-gated, not agent-executable)" —
+  sibling roadmap. H4 (Medium / CFP) and H5 (screencasts) are
+  `[-]` cancelled there with back-references to the entries above.
+- [`agents/roadmaps/road-to-mcp-full-coverage.md`](../agents/roadmaps/road-to-mcp-full-coverage.md)
+  Phase 3 — pre-condition for the Smithery item.

package/docs/architecture.md

@@ -98,7 +98,7 @@ fails on any source-side violation, without producing artifacts.
 |---|---|---|
 | **Skills** | 174 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
 | **Rules** | 60 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
-| **Commands** | 104 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
+| **Commands** | 106 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
 | **Guidelines** | 69 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |

package/docs/catalog.md

@@ -1,6 +1,6 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **404 public artefacts** shipped by
+Consumer-facing catalog of all **406 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
@@ -248,7 +248,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 (104)
+## Commands (106)
 
 | kind | name | cluster | description |
 |---|---|---|---|
@@ -324,6 +324,7 @@ are excluded.
 | command | [`optimize:skills`](../.agent-src/commands/optimize/skills.md) | cluster: optimize | Audits skills — measures baseline, finds duplicates/merge candidates, runs linter. Suggest only, never auto-apply. |
 | command | [`optimize-prompt`](../.agent-src/commands/optimize-prompt.md) | cluster: optimize | Optimize a raw prompt for ChatGPT, Claude, Gemini, or another AI via the 4-D methodology — BASIC vs DETAIL auto-detect, one clarifying question per turn, returns the polished prompt. |
 | command | [`optimize`](../.agent-src/commands/optimize.md) | cluster: optimize | Optimize orchestrator — routes to skills, agents-dir, augmentignore, rtk-filters |
+| command | [`orchestrate`](../.agent-src/commands/orchestrate.md) | cluster: orchestrate | Run a YAML pipeline defined under `.agent-config/orchestrations/` — chains personas / skills / commands / sub-agents per the orchestration-dsl-v1 contract |
 | command | [`override:create`](../.agent-src/commands/override/create.md) | cluster: override | Creates a project-level override for a shared skill, rule, or command. |
 | command | [`override:manage`](../.agent-src/commands/override/manage.md) | cluster: override | Reviews, updates, and refactors existing project-level overrides. |
 | command | [`override`](../.agent-src/commands/override.md) | cluster: override | Override orchestrator — routes to create, manage |
@@ -348,7 +349,8 @@ are excluded.
 | command | [`rule-compliance-audit`](../.agent-src/commands/rule-compliance-audit.md) |  | Audit rule trigger quality, simulate activation, detect overlaps, and find never-activating rules |
 | command | [`set-cost-profile`](../.agent-src/commands/set-cost-profile.md) |  | Change the cost_profile in .agent-settings.yml — shows each profile's meaning and applies the selection |
 | command | [`sync-agent-settings`](../.agent-src/commands/sync-agent-settings.md) |  | Sync `.agent-settings.yml` against the current template + profile — adds new sections/keys, preserves user values, shows a diff before writing |
-| command | [`sync-gitignore`](../.agent-src/commands/sync-gitignore.md) |  | Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserves user-added lines, shows a diff before writing |
+| command | [`sync-gitignore:fix`](../.agent-src/commands/sync-gitignore/fix.md) | cluster: sync-gitignore | Scrub legacy pre-`/agents/` patterns from the consumer's .gitignore (inside or outside the managed block) and re-sync the canonical entries |
+| command | [`sync-gitignore`](../.agent-src/commands/sync-gitignore.md) | cluster: sync-gitignore | Sync the `event4u/agent-config` block in the consumer project's .gitignore — adds missing entries, preserves user-added lines, shows a diff before writing |
 | command | [`tests:create`](../.agent-src/commands/tests/create.md) | cluster: tests | Write meaningful tests for the changes in the current branch |
 | command | [`tests:execute`](../.agent-src/commands/tests/execute.md) | cluster: tests | Run PHP tests inside the Docker container |
 | command | [`tests`](../.agent-src/commands/tests.md) | cluster: tests | Tests orchestrator — routes to create, execute |

package/docs/contracts/audit-log-v1.md

@@ -0,0 +1,142 @@
+---
+stability: beta
+---
+
+# Audit-log v1
+
+**Purpose.** Pin the append-only schema that the audit-as-memory
+pipeline writes per `/work` and `/implement-ticket` run, so the
+pattern-extraction script ([`extract_audit_patterns.py`](../../scripts/extract_audit_patterns.py))
+and the `learning-to-rule-or-skill` skill can mine repeated successful
+patterns without re-reading conversation bodies.
+
+**Scope.** Defines the JSONL line shape, file location, redaction
+floor, append-only invariant, and the producer/consumer contract.
+Does **not** define how patterns are scored or how proposals are
+promoted — that is the consumer's responsibility (see Cross-references).
+
+Last refreshed: 2026-05-11.
+
+## Producer / consumer split
+
+| Side | Responsibility | Where |
+|---|---|---|
+| **Producer** | One JSONL line per phase end, derived from the phase's [`decision-trace-v1.md`](decision-trace-v1.md) JSON and the [`memory-visibility-v1.md`](memory-visibility-v1.md) counts. | `work_engine` hook on phase boundary. |
+| **Consumer** | Pattern mining + human review gate. Never edits a written line; corrections are new lines with `type=supersede`. | [`extract_audit_patterns.py`](../../scripts/extract_audit_patterns.py). |
+
+## File location
+
+```
+agents/state/audit/<YYYY-MM>.jsonl
+```
+
+One file per UTC month. Files are append-only — `merge=union` via
+`.gitattributes` (same mechanism as the archived
+`agents/memory/intake/*.jsonl` recipe). Files MAY be gitignored in
+consumer projects; the contract does not require commit.
+
+## Line shape
+
+One JSON object per line, UTF-8, no trailing whitespace:
+
+```json
+{"schema_version":1,"id":"01HXY...","ts":"2026-05-11T12:34:56Z","work_id":"PROJ-123-2026-05-11T12-30-00Z","phase":"verify","outcome":"success","confidence_band":"high","risk_class":"low","memory":{"asks":3,"hits":2},"verify":{"claims":1,"first_try_passes":1},"rules_applied":["verify-before-complete","commit-policy"],"persona":"backend","input_kind":"ticket","type":"phase"}
+```
+
+Single-line. The pretty-printed reference shape:
+
+```json
+{
+  "schema_version": 1,
+  "id": "01HXY7K9...",
+  "ts": "2026-05-11T12:34:56Z",
+  "work_id": "PROJ-123-2026-05-11T12-30-00Z",
+  "phase": "verify",
+  "outcome": "success",
+  "confidence_band": "high",
+  "risk_class": "low",
+  "memory": { "asks": 3, "hits": 2 },
+  "verify": { "claims": 1, "first_try_passes": 1 },
+  "rules_applied": ["verify-before-complete", "commit-policy"],
+  "persona": "backend",
+  "input_kind": "ticket",
+  "type": "phase"
+}
+```
+
+## Field semantics
+
+| Field | Type | Meaning |
+|---|---|---|
+| `schema_version` | int | Always `1` for this contract. Major bump on breaking changes. |
+| `id` | string | ULID or content hash. Stable, deduplicated by the **reader**, never by in-place edit. |
+| `ts` | string | ISO-8601 UTC timestamp of phase end. |
+| `work_id` | string | Matches the `WorkState` directory id from [`decision-trace-v1.md`](decision-trace-v1.md). Allows cross-trace correlation. |
+| `phase` | enum | One of `refine` · `memory` · `analyze` · `plan` · `implement` · `test` · `verify` · `report`. |
+| `outcome` | enum | One of `success` · `blocked` · `skipped` · `error`. Mirrors `Outcome` from `work_engine.directives`. |
+| `confidence_band` | enum | One of `low` · `medium` · `high`. Sourced from decision-trace. |
+| `risk_class` | enum | One of `low` · `medium` · `high`. Inherits max risk from touched files. |
+| `memory.asks` / `memory.hits` | int | Counts only — never ids, never bodies. |
+| `verify.claims` / `verify.first_try_passes` | int | Verify-gate counts. |
+| `rules_applied` | string[] | Stable rule ids whose Iron Law fired this phase. Bounded to ≤ 32; remainder dropped silently. |
+| `persona` | string \| null | Resolved `roles.active_role` from `.agent-settings.yml` at phase start. |
+| `input_kind` | enum | One of `prompt` · `ticket` · `orchestration`. Matches `WorkState.input.kind`. |
+| `type` | enum | One of `phase` · `supersede` · `note`. `supersede` carries an extra `supersedes` field with the prior `id`. |
+
+Unknown trailing fields are forward-compat extensions; readers MUST
+NOT raise on them.
+
+## Privacy floor
+
+Lines MUST NOT contain:
+
+- Conversation **bodies**, summaries, prompts, or quoted snippets.
+- Memory entry bodies, ids, or content. Only **counts** travel here —
+  ids stay in `decision-trace-*.json` per [`memory-visibility-v1.md`](memory-visibility-v1.md).
+- Secrets, tokens, environment values, file contents.
+- Paths outside the package's `agents/state/` and `tests/` allowlist.
+
+The floor is enforced by
+`tests/contracts/test_audit_log_redaction.py` — any new producer-side
+edit that touches this schema adds a fixture there.
+
+## Append-only invariant
+
+- New entries append. Existing lines are **immutable**.
+- A correction is a **new** entry with `type=supersede` and a
+  `supersedes` field carrying the prior `id`. The reader applies the
+  chain.
+- Deletion is forbidden at the producer layer. Operators rotate
+  monthly files; archived months MAY be purged out-of-band by the
+  consumer project's retention policy.
+
+## Cadence
+
+One line per phase end. The producer hook fires on the same
+`post_tool_use` / `stop` boundary that emits the visibility line
+([`memory-visibility-v1.md`](memory-visibility-v1.md) § Cadence).
+
+Cost-profile interaction:
+
+| Cost profile | Line emission |
+|---|---|
+| `lean` | suppress unless `outcome != success` OR `risk_class >= medium` |
+| `standard` | always |
+| `verbose` | always |
+
+## Stability
+
+Beta. Breaking changes between v1 and v2 are allowed in a minor
+release if the change appears in `CHANGELOG.md` under a `### Breaking`
+heading. Consumers MUST gate on `schema_version` and refuse unknown
+majors.
+
+## Cross-references
+
+- Input feed (counts + ids): [`memory-visibility-v1.md`](memory-visibility-v1.md).
+- Per-phase JSON the producer reads: [`decision-trace-v1.md`](decision-trace-v1.md).
+- Pattern-extraction consumer: [`extract_audit_patterns.py`](../../scripts/extract_audit_patterns.py).
+- Skill that consumes promoted patterns:
+  [`learning-to-rule-or-skill`](../../.agent-src.uncompressed/skills/learning-to-rule-or-skill/SKILL.md).
+- Append-only JSONL precedent:
+  [`adr-chat-history-split.md`](adr-chat-history-split.md).

package/docs/contracts/command-clusters.md

@@ -44,6 +44,8 @@ column 1 of this table.
 | `council` | 3 | `default` · `pr` · `design` · `optimize` | `council` (legacy default lens) · `council-pr` · `council-design` · `council-optimize` |
 | `challenge-me` | — | `vision` · `with-docs` | new — Pocock-inspired one-question-at-a-time interview; `vision` is the standard 95%-confidence variant, `with-docs` adds doc/glossary awareness with a session-scoped glossary and load-bearing claim-vs-code verification |
 | `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. |
 
 **Net change:** Phase 1 collapsed 15 atomics → 3 clusters; Phase 2
 collapses 26 atomics → 11 sub-command clusters. Sub-commands use