@event4u/agent-config 1.38.0 → 1.40.0

package/.agent-src/skills/subagent-orchestration/SKILL.md

@@ -240,6 +240,15 @@ prefer the cheaper one (`do-and-judge` < `do-and-judge-two-stage` <
 `do-in-steps` < `do-in-parallel` < `do-competitively` <
 `judge-with-debate` < `do-in-worktrees`).
 
+**Mode 6 (`do-in-worktrees`) is gated by `worktrees.mode`** from
+`.agent-settings.yml` (default: `ask`). Resolve before picking:
+
+| `worktrees.mode` | Mode 6 |
+|---|---|
+| `ask` | Eligible. `using-git-worktrees` will run the per-creation permission ask. |
+| `on` | Eligible. Per-creation ask suppressed. |
+| `off` | **Not eligible.** Fall back to mode 3 (`do-in-steps`) — same step-by-step chain, in-place on the current branch. Unless the user **explicitly asked this turn** for a worktree chain, in which case proceed with mode 6 and acknowledge the override per [`using-git-worktrees § Pre-flight`](../using-git-worktrees/SKILL.md). |
+
 ### 4. Dispatch
 
 Hand off to the matching command:

package/.agent-src/skills/using-git-worktrees/SKILL.md

@@ -44,6 +44,31 @@ work and makes it impossible to tell what you broke.
 
 ## Procedure
 
+### 0. Pre-flight — read `worktrees.mode`
+
+Before anything else, read `worktrees.mode` from `.agent-settings.yml`
+(default: `ask`). The setting is a **mechanical layer on top of**
+`scope-control`'s permission gate — it narrows, never widens.
+
+| `worktrees.mode` | Behaviour |
+|---|---|
+| `ask` | Status quo. Continue to step 1; `scope-control` permission gate applies for every worktree creation. |
+| `on` | Standing permission. Skip the per-creation permission ask; continue to step 1. Iron-Law gates (ignore-check, clean baseline) still apply. |
+| `off` | No autonomous worktree creation. **Refuse** unless the user explicitly asked **this turn** for a worktree ("do this in a worktree", "use mode 6", "spawn a worktree for X"). |
+
+**Off, no explicit request** → stop. Tell the user the setting is `off`,
+suggest the in-place alternative (`subagent-orchestration` mode 3
+`do-in-steps`, or just stay on the current branch). Do not re-ask on
+the same task.
+
+**Off, with explicit request this turn** → acknowledge once
+("`worktrees.mode` is `off`; running this on your explicit request
+for this task") and continue to step 1. The override is for this one
+task — it does not flip the setting.
+
+The setting only suppresses **unprompted** usage. The tool stays
+available when the user wants it.
+
 ### 1. Inspect current state
 
 Before creating anything, check existing conventions — do not assume:

package/.agent-src/templates/agent-settings.md

@@ -230,6 +230,14 @@ subagents:
   # Set to 1 to serialize. Hard cap enforced by runtime.
   max_parallel: 3
 
+# --- Git worktrees ---
+worktrees:
+  # off | on | ask  (default: ask)
+  # off = no autonomous worktree creation (explicit user request overrides)
+  # on  = standing permission (skill skips the per-creation ask)
+  # ask = status quo — skill asks before creating
+  mode: ask
+
 # --- Role modes (see guidelines/agent-infra/role-contracts.md) ---
 roles:
   # Role the agent defaults to at the start of a session.
@@ -442,6 +450,7 @@ the canonical narrative lives in
 | `subagents.implementer_model` | model alias or empty | _(empty)_ | Model for implementer subagents. Empty = same tier as session model. See [subagent-configuration](../contexts/subagent-configuration.md). |
 | `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
 | `subagents.max_parallel` | integer | `3` | Maximum parallel subagent invocations. `1` serializes. |
+| `worktrees.mode` | `off`, `on`, `ask` | `ask` | Controls autonomous `git worktree` usage. `off` = skill refuses unless the user explicitly asks for a worktree that turn (then it runs); `subagent-orchestration` mode 6 falls back to mode 3. `on` = standing permission (skill skips the per-creation ask; ignore-check and clean-baseline gates still apply). `ask` = status quo — `scope-control` permission gate runs every time. |
 | `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. See [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md). |
 | `roles.active_role` | same as `default_role` | _(empty)_ | Role currently active; set by `/mode <name>`, cleared by `/mode none`. Enables the `role-mode-adherence` rule. |
 | `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast. Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md). |

package/.agent-src/templates/agents/agent-project-settings.example.yml

@@ -6,14 +6,21 @@
 #
 # Precedence (lowest → highest):
 #   1. Package defaults (shipped by event4u/agent-config)
-#   2. This file (.agent-project-settings.yml) — team defaults
-#   3. .agent-settings.yml — developer overrides (gitignored)
+#   2. ~/.config/agent-config/agent-settings.yml — user-global DX-comfort
+#      defaults (whitelist: name, ide, cost_profile, personal.bot_icon,
+#      personal.autonomy, caveman.speak_scope). Created on opt-in via
+#      /onboard; project-local files always win.
+#   3. This file (.agent-project-settings.yml) — team defaults
+#   4. .agent-settings.yml — developer overrides (gitignored)
 #
 # Any key marked `locked: true` in this file CANNOT be overridden by
 # .agent-settings.yml. Use sparingly — locked keys reduce developer
 # autonomy. Reserve for compliance or correctness concerns (e.g.
 # forcing a test framework, pinning a coding style).
 #
+# Full precedence model + user-global whitelist contract:
+#   docs/guidelines/agent-infra/layered-settings.md
+#
 # Copy this file to `.agent-project-settings.yml` (drop the `.example`)
 # and commit it.
 

package/.agent-src/templates/scripts/work_engine/_lib/__init__.py

@@ -0,0 +1,7 @@
+"""Internal helpers shared across work_engine submodules.
+
+Currently houses :mod:`agent_settings` — the byte-identical mirror of
+``scripts/_lib/agent_settings.py`` from the agent-config package. The
+parity test in ``tests/test_template_agent_settings_parity.py`` guards
+the two files against drift.
+"""

package/.agent-src/templates/scripts/work_engine/_lib/agent_settings.py

@@ -0,0 +1,168 @@
+"""Centralized loader for ``.agent-settings.yml`` with user-global fallback.
+
+Phase 1 of road-to-portable-dev-preferences. Single source of truth for
+how scripts read agent settings — replaces ~15 ad-hoc loaders in P3.
+
+Resolution order (project wins, user-global fills gaps for whitelisted
+keys only):
+
+  1. Project ``./.agent-settings.yml``                  (full file, all keys)
+  2. ``~/.config/agent-config/agent-settings.yml``      (whitelist only)
+  3. Built-in defaults                                  (currently empty)
+
+Whitelisted keys (``MERGEABLE_KEYS``) are exact dotted paths. A
+non-whitelisted key in the user-global file is silently ignored — the
+``verbose=True`` flag surfaces ignored paths via ``logging.info`` for
+debugging.
+
+Contract — pure, read-only, tolerant:
+
+* Lazy PyYAML import; no yaml installed → defaults returned.
+* Missing project file → user-global + defaults.
+* Missing user-global file → project + defaults.
+* Both missing → defaults.
+* Malformed YAML / unreadable file → defaults, logged at WARNING.
+* No file is ever created or written by this module.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_PROJECT_FILE = ".agent-settings.yml"
+DEFAULT_USER_GLOBAL_FILE = (
+    Path.home() / ".config" / "agent-config" / "agent-settings.yml"
+)
+
+#: Exact dotted paths allowed to cascade from user-global into the merged
+#: settings. Anything not listed here is silently ignored when present in
+#: the user-global file. Adding a key requires an ADR — see
+#: ``agents/roadmaps/road-to-portable-dev-preferences.md``.
+MERGEABLE_KEYS: tuple[str, ...] = (
+    "name",
+    "ide",
+    "cost_profile",
+    "personal.bot_icon",
+    "personal.autonomy",
+    "caveman.speak_scope",
+)
+
+_DEFAULTS: dict[str, Any] = {}
+
+
+def load_agent_settings(
+    project_path: Path | str | None = None,
+    user_global_path: Path | str | None = None,
+    verbose: bool = False,
+) -> dict[str, Any]:
+    """Return the merged settings dict.
+
+    ``project_path`` defaults to ``./.agent-settings.yml`` (CWD-relative).
+    ``user_global_path`` defaults to
+    ``~/.config/agent-config/agent-settings.yml``. Both arguments accept
+    ``Path`` or ``str``. Pass ``verbose=True`` to log keys present in
+    user-global that are not on the whitelist.
+    """
+    project = _read_yaml(
+        Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE),
+    ) or {}
+    user_global_raw = _read_yaml(
+        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE,
+    ) or {}
+
+    user_global_filtered, ignored = _filter_whitelist(
+        user_global_raw, MERGEABLE_KEYS,
+    )
+    if verbose and ignored:
+        logger.info(
+            "agent_settings: ignored non-whitelisted user-global keys: %s",
+            sorted(ignored),
+        )
+
+    merged: dict[str, Any] = _deep_copy_defaults(_DEFAULTS)
+    _deep_merge(merged, user_global_filtered)
+    _deep_merge(merged, project)
+    return merged
+
+
+def _read_yaml(path: Path) -> dict[str, Any] | None:
+    """Best-effort YAML read; never raises. Returns ``None`` on any failure."""
+    if not path.is_file():
+        return None
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        return None
+    try:
+        with path.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+    except (OSError, yaml.YAMLError):
+        logger.warning("agent_settings: unreadable or malformed YAML at %s", path)
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _filter_whitelist(
+    raw: dict[str, Any], allowed: tuple[str, ...],
+) -> tuple[dict[str, Any], list[str]]:
+    """Return ``(filtered_dict, ignored_paths)`` from a user-global blob."""
+    filtered: dict[str, Any] = {}
+    for dotted in allowed:
+        value = _get_dotted(raw, dotted)
+        if value is not None:
+            _set_dotted(filtered, dotted, value)
+    ignored = [p for p in _leaf_paths(raw) if p not in allowed]
+    return filtered, ignored
+
+
+def _get_dotted(data: dict[str, Any], dotted: str) -> Any:
+    cursor: Any = data
+    for part in dotted.split("."):
+        if not isinstance(cursor, dict) or part not in cursor:
+            return None
+        cursor = cursor[part]
+    return cursor
+
+
+def _set_dotted(target: dict[str, Any], dotted: str, value: Any) -> None:
+    parts = dotted.split(".")
+    cursor = target
+    for part in parts[:-1]:
+        nxt = cursor.setdefault(part, {})
+        if not isinstance(nxt, dict):
+            nxt = {}
+            cursor[part] = nxt
+        cursor = nxt
+    cursor[parts[-1]] = value
+
+
+def _leaf_paths(data: dict[str, Any], prefix: str = "") -> list[str]:
+    paths: list[str] = []
+    for key, value in data.items():
+        path = f"{prefix}.{key}" if prefix else key
+        if isinstance(value, dict) and value:
+            paths.extend(_leaf_paths(value, path))
+        else:
+            paths.append(path)
+    return paths
+
+
+def _deep_merge(dst: dict[str, Any], src: dict[str, Any]) -> None:
+    """Merge ``src`` into ``dst`` in-place; nested dicts are merged recursively."""
+    for key, value in src.items():
+        if (
+            isinstance(value, dict)
+            and isinstance(dst.get(key), dict)
+        ):
+            _deep_merge(dst[key], value)
+        else:
+            dst[key] = value
+
+
+def _deep_copy_defaults(src: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    _deep_merge(out, src)
+    return out

package/.agent-src/templates/scripts/work_engine/hooks/settings.py

@@ -13,6 +13,12 @@ settings.py``):
 * Chat-history hooks gate on **two** switches: ``hooks.chat_history.
   enabled`` AND the global ``chat_history.enabled``. Either off → no
   chat-history hook registers.
+
+Per road-to-portable-dev-preferences P3, the YAML read goes through
+:func:`work_engine._lib.agent_settings.load_agent_settings`, which
+cascades the whitelisted ``cost_profile`` (and other DX-comfort keys)
+from ``~/.config/agent-config/agent-settings.yml`` when the project
+file omits them. Project values always win.
 """
 from __future__ import annotations
 
@@ -20,6 +26,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
+from work_engine._lib.agent_settings import load_agent_settings
+
 DEFAULT_SETTINGS_FILE = ".agent-settings.yml"
 DEFAULT_CHAT_HISTORY_SCRIPT = "scripts/chat_history.py"
 
@@ -52,36 +60,27 @@ _DEFAULT = HookSettings()
 
 def load_hook_settings(
     settings_path: Path | str | None = None,
+    user_global_path: Path | str | None = None,
 ) -> HookSettings:
     """Return :class:`HookSettings` hydrated from ``.agent-settings.yml``.
 
     ``settings_path`` defaults to ``./.agent-settings.yml`` relative to
     the current working directory — same convention as chat-history.
+    ``user_global_path`` defaults to
+    ``~/.config/agent-config/agent-settings.yml`` and only cascades the
+    whitelisted DX-comfort keys (currently ``cost_profile``) when the
+    project file omits them. See road-to-portable-dev-preferences P3.
     """
     path = Path(settings_path) if settings_path else Path(DEFAULT_SETTINGS_FILE)
-    raw = _read_yaml(path)
-    if raw is None:
+    raw = load_agent_settings(
+        project_path=path,
+        user_global_path=user_global_path,
+    )
+    if not raw:
         return _DEFAULT
     return _settings_from_raw(raw)
 
 
-def _read_yaml(path: Path) -> dict[str, Any] | None:
-    if not path.is_file():
-        return None
-    try:
-        import yaml  # type: ignore[import-untyped]
-    except ImportError:
-        return None
-    try:
-        with path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except (OSError, yaml.YAMLError):
-        return None
-    if not isinstance(data, dict):
-        return None
-    return data
-
-
 def _settings_from_raw(data: dict[str, Any]) -> HookSettings:
     hooks = data.get("hooks")
     if not isinstance(hooks, dict):

package/.agent-src/templates/scripts/work_engine/orchestration.py

@@ -0,0 +1,168 @@
+"""State machine stub for the ``/orchestrate`` command.
+
+Reads a pipeline file conforming to
+``docs/contracts/orchestration-dsl-v1.md`` and produces an ordered
+sequence of step descriptors the agent dispatches one at a time.
+The runtime itself is **not** in Python — each step is executed by the
+agent via skill / command / persona / subagent dispatch. This module
+holds the deterministic bookkeeping:
+
+- load + interpolate
+- step iteration with success / failure / when-guard tracking
+- output-map resolution at the end
+
+Design constraints (R1 carve-outs from
+``road-to-distribution-and-adoption.md``):
+
+- No external dependencies. YAML loading reuses the dispatcher's
+  loader so the runtime sees what the linter sees.
+- No side effects. The state machine never edits files, runs commands,
+  or emits hooks of its own. Audit emission is the caller's job.
+- Forward-ref free. ``steps[].with`` references can only reach
+  earlier steps; this is enforced both by the linter and at runtime.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterator
+
+_INTERP_RE = re.compile(
+    r"\$\{\{\s*(inputs|steps)\.([a-z0-9_-]+)(?:\.output)?\s*\}\}"
+)
+
+
+@dataclass
+class StepResult:
+    """One step's record after dispatch."""
+    step_id: str
+    kind: str
+    ref: str
+    success: bool = False
+    output: str = ""
+    error: str | None = None
+
+
+@dataclass
+class PipelineState:
+    """Bookkeeping for a single ``/orchestrate`` run."""
+    name: str
+    inputs: dict[str, str]
+    results: dict[str, StepResult] = field(default_factory=dict)
+    halted: bool = False
+    halt_reason: str | None = None
+
+
+def _load_pipeline(path: Path) -> dict[str, Any]:
+    """Reuse the linter's loader so the runtime accepts the same shape.
+
+    Walks parents to find a directory containing ``scripts/hooks/``
+    so the loader is reachable both when this module runs from the
+    consumer projection (``.agent-src/templates/scripts/work_engine/``)
+    and from the source-of-truth tree
+    (``.agent-src.uncompressed/templates/scripts/work_engine/``).
+    """
+    import sys
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        candidate = parent / "scripts" / "hooks" / "dispatch_hook.py"
+        if candidate.is_file():
+            sys.path.insert(0, str(parent / "scripts"))
+            break
+    from hooks.dispatch_hook import _load_yaml  # noqa: E402
+    doc = _load_yaml(path)
+    if not isinstance(doc, dict):
+        raise ValueError(f"{path}: top-level must be a mapping")
+    return doc
+
+
+def _interpolate(value: Any, state: PipelineState) -> Any:
+    """Substitute ``${{ inputs.X }}`` / ``${{ steps.Y.output }}`` in a
+    nested value. Unknown references raise — the linter should have
+    caught them, but the runtime double-checks."""
+    if isinstance(value, str):
+        def replace(match: re.Match[str]) -> str:
+            ns, ident = match.group(1), match.group(2)
+            if ns == "inputs":
+                if ident not in state.inputs:
+                    raise KeyError(f"unknown input '{ident}'")
+                return state.inputs[ident]
+            if ident not in state.results:
+                raise KeyError(f"unknown step '{ident}'")
+            return state.results[ident].output
+        return _INTERP_RE.sub(replace, value)
+    if isinstance(value, dict):
+        return {k: _interpolate(v, state) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_interpolate(v, state) for v in value]
+    return value
+
+
+def _when_passes(when: str | None, state: PipelineState) -> bool:
+    """Evaluate the limited ``when`` mini-language. Supports
+    ``steps.X.success`` / ``steps.X.failure`` and equality on a
+    single ``${{ steps.X.output }}`` template against a literal."""
+    if not when:
+        return True
+    when = when.strip()
+    m = re.fullmatch(r"steps\.([a-z0-9_-]+)\.(success|failure)", when)
+    if m:
+        sid, kind = m.group(1), m.group(2)
+        if sid not in state.results:
+            return False
+        return state.results[sid].success if kind == "success" else not state.results[sid].success
+    m = re.fullmatch(r'\$\{\{\s*steps\.([a-z0-9_-]+)\.output\s*\}\}\s*==\s*"([^"]*)"', when)
+    if m:
+        sid, literal = m.group(1), m.group(2)
+        return state.results.get(sid, StepResult(sid, "", "")).output == literal
+    raise ValueError(f"unsupported when expression: {when!r}")
+
+
+def iter_steps(path: Path, inputs: dict[str, str]) -> Iterator[dict[str, Any]]:
+    """Yield interpolated step descriptors in order.
+
+    Caller dispatches each descriptor via skill / command / persona /
+    subagent and feeds the result back via :func:`record_result`.
+    """
+    doc = _load_pipeline(path)
+    merged_inputs = {
+        inp["id"]: inputs.get(inp["id"], inp.get("default", ""))
+        for inp in (doc.get("inputs") or [])
+        if isinstance(inp, dict) and isinstance(inp.get("id"), str)
+    }
+    state = PipelineState(name=doc.get("name", ""), inputs=merged_inputs)
+    for step in doc.get("steps") or []:
+        if state.halted:
+            break
+        if not _when_passes(step.get("when"), state):
+            continue
+        yield {
+            "id": step["id"],
+            "kind": step["kind"],
+            "ref": step["ref"],
+            "with": _interpolate(step.get("with") or {}, state),
+            "_state": state,
+        }
+
+
+def record_result(descriptor: dict[str, Any], *, success: bool, output: str = "", error: str | None = None) -> None:
+    """Caller hands the descriptor + outcome back so subsequent steps
+    can see ``${{ steps.<id>.output }}``."""
+    state: PipelineState = descriptor["_state"]
+    state.results[descriptor["id"]] = StepResult(
+        step_id=descriptor["id"], kind=descriptor["kind"], ref=descriptor["ref"],
+        success=success, output=output, error=error,
+    )
+    if not success:
+        state.halted = True
+        state.halt_reason = f"step {descriptor['id']} failed"
+
+
+def resolve_outputs(path: Path, state: PipelineState) -> dict[str, str]:
+    """Resolve the pipeline's ``outputs:`` map against the captured
+    step outputs. Returns an empty map if the pipeline declares no
+    outputs."""
+    doc = _load_pipeline(path)
+    raw = doc.get("outputs") or {}
+    return {k: _interpolate(v, state) for k, v in raw.items()}

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.38.0"
+    "version": "1.40.0"
   },
   "plugins": [
     {
@@ -184,6 +184,7 @@
         "./.claude/skills/optimize-prompt",
         "./.claude/skills/optimize-rtk",
         "./.claude/skills/optimize-skills",
+        "./.claude/skills/orchestrate",
         "./.claude/skills/override",
         "./.claude/skills/override-create",
         "./.claude/skills/override-manage",
@@ -262,6 +263,7 @@
         "./.claude/skills/subagent-orchestration",
         "./.claude/skills/sync-agent-settings",
         "./.claude/skills/sync-gitignore",
+        "./.claude/skills/sync-gitignore-fix",
         "./.claude/skills/systematic-debugging",
         "./.claude/skills/tailwind-engineer",
         "./.claude/skills/tech-debt-tracker",

package/AGENTS.md

@@ -16,12 +16,12 @@ task ci                # full pipeline — green before PR
 
 ## Pointers
 
-- **Package self-orientation** — identity, four-wing cognition map, repo layout, tech stack, key-rules table, telemetry, command-suggester: [`docs/contracts/package-self-orientation.md`](docs/contracts/package-self-orientation.md).
-- **Kernel + Router** — 9 always-loaded Iron-Law rules, tier-1 / tier-2 routing, cost profiles, per-rule char caps enforced by `task lint-rule-budget`: [`kernel-membership`](docs/contracts/kernel-membership.md) + [`rule-router`](docs/contracts/rule-router.md).
+- **Package self-orientation** (beta) — identity, four-wing cognition map, repo layout, tech stack, key-rules table, telemetry, command-suggester: [`docs/contracts/package-self-orientation.md`](docs/contracts/package-self-orientation.md).
+- **Kernel + Router** (beta) — 9 always-loaded Iron-Law rules, tier-1 / tier-2 routing, cost profiles, per-rule char caps enforced by `task lint-rule-budget`: [`kernel-membership`](docs/contracts/kernel-membership.md) + [`rule-router`](docs/contracts/rule-router.md).
 - **Multi-tool projection** — Augment, Claude Code, Cursor, Cline, Windsurf, Gemini CLI, Claude.ai bundle pipeline that ships from `.agent-src/` to consumer surfaces: [`docs/architecture.md`](docs/architecture.md#cloud-bundle-pipeline).
 - **Editing this repo** — Iron-Law rules (portability, source-of-truth, skill-quality) and the Thin-Root contract (caps · pointer-ratio · triage block) governing AGENTS.md: [`augment-portability`](.agent-src/rules/augment-portability.md), [`augment-source-of-truth`](.agent-src/rules/augment-source-of-truth.md), [`skill-quality`](.agent-src/rules/skill-quality.md), [`agents-md-thin-root`](.agent-src/skills/agents-md-thin-root/SKILL.md).
-- **Consumer story + architecture deep-dive** — what the package does for installers and how it ships: [`README.md`](README.md), [`docs/architecture.md`](docs/architecture.md).
-- **Personas** — 11 review-lens cast (6 core · 5 specialist), `personas:` vs `/mode` axes, citation map, override pattern: [`docs/personas.md`](docs/personas.md), schema [`docs/contracts/persona-schema.md`](docs/contracts/persona-schema.md).
+- **Consumer story + architecture deep-dive** — install story + ship pipeline: [`README.md`](README.md), [`docs/architecture.md`](docs/architecture.md).
+- **Personas** — 11 review-lens cast (6 core · 5 specialist), `personas:` vs `/mode` axes, citation map, override pattern: [`docs/personas.md`](docs/personas.md), schema [`docs/contracts/persona-schema.md`](docs/contracts/persona-schema.md) (beta).
 
 ## Emergency triage — read this when nothing else is reachable
 

package/CHANGELOG.md

@@ -318,6 +318,82 @@ 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
+
+* **onboard,docs:** wire user-global DX defaults into onboarding + docs ([761a969](https://github.com/event4u-app/agent-config/commit/761a96979c42b880d83f72ccd2ac2d752ae47f0b))
+* **settings:** add centralized agent-settings loader ([d5699be](https://github.com/event4u-app/agent-config/commit/d5699bee9ebb47dd2f1d78716e1ff84a7139b5da))
+
+### Bug Fixes
+
+* **ci:** grant contents:write to deploy-mcp-worker for release comment ([fb5c895](https://github.com/event4u-app/agent-config/commit/fb5c89537daef55e5dde12bfe85cc703bfa181ed))
+
+### Documentation
+
+* **roadmap:** add road-to-simplicity-and-everywhere (highest prio) ([417a8fa](https://github.com/event4u-app/agent-config/commit/417a8fa9b7059dac783d3bc9423c64a994a9421a))
+* **roadmap:** add road-to-mcp-full-coverage (Discovery-First) ([fabf897](https://github.com/event4u-app/agent-config/commit/fabf89761322a437b39178366e45f68efbdd7924))
+* **mcp-cloud:** clarify Lite-vs-Full scope at endpoint surface ([97c4684](https://github.com/event4u-app/agent-config/commit/97c4684d07be4fe49c248a1ee0a60cd36b82e071))
+* **stability:** align public surface with stability markers ([d9afe4a](https://github.com/event4u-app/agent-config/commit/d9afe4ad67aad80e2bb12b1c707189f3ee8f47c2))
+* **mcp:** clarify .agent-settings.yml vs. MCP client config ([27a77b2](https://github.com/event4u-app/agent-config/commit/27a77b2459cad1faff12cd8a237e59091ec687de))
+* **mcp:** add per-client setup guide for hosted Remote MCP ([179da38](https://github.com/event4u-app/agent-config/commit/179da38631ea9693a94f259fb1edd2746b89425d))
+
+### Refactoring
+
+* **work-engine:** centralize agent-settings loading in shared _lib ([3c548bb](https://github.com/event4u-app/agent-config/commit/3c548bb72d3c2022362050a4c88ebe412bf7a897))
+
+### Chores
+
+* **compress:** regenerate commands/onboard.md after onboard,docs source edit ([e676915](https://github.com/event4u-app/agent-config/commit/e67691564405f05fba033f29b0df696e25788dd0))
+
+### Other
+
+* add portable-dev-preferences (3 phases, refined via AI council) ([7468a4c](https://github.com/event4u-app/agent-config/commit/7468a4cd2d352d6bfcd7797a8dd8b6ed8ec8f27a))
+
+Tests: 2699 (+20 since 1.38.0)
+
 ## [1.38.0](https://github.com/event4u-app/agent-config/compare/1.37.0...1.38.0) (2026-05-11)
 
 ### Features