@event4u/agent-config 1.39.0 → 1.40.0

package/CHANGELOG.md

@@ -318,6 +318,48 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [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>
 
 ---
@@ -122,8 +122,8 @@ Experimental — A0-cloud contract lives at `docs/contracts/mcp-cloud-scope.md`
 > 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.
+> `docs/contracts/mcp-cloud-scope.md` (internal reference only per
+> `STABILITY.md`) for the execution-safety boundary.
 
 ### Optional: persistent agent memory
 
@@ -378,7 +378,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 +403,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 **405 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 (105)
 
 | 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 |

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

package/docs/contracts/file-ownership-matrix.json

@@ -435,6 +435,12 @@
       "load_context": [],
       "load_context_eager": []
     },
+    ".agent-src.uncompressed/commands/orchestrate.md": {
+      "kind": "command",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
     ".agent-src.uncompressed/commands/override.md": {
       "kind": "command",
       "rule_type": null,
@@ -3495,6 +3501,20 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/commands/orchestrate.md",
+      "target": ".agent-src.uncompressed/commands/orchestrate.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/orchestrate.md",
+      "target": ".agent-src.uncompressed/skills/subagent-orchestration/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/commands/override.md",
       "target": ".agent-src.uncompressed/commands/override.md",