@event4u/agent-config 1.17.0 → 1.19.0

package/.agent-src/templates/scripts/work_engine/scoring/memory_visibility.py

@@ -0,0 +1,125 @@
+"""Producer-side helpers for the memory-visibility line.
+
+Implements the v1 line shape from
+``docs/contracts/memory-visibility-v1.md``:
+
+    🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>]
+
+The semantics matched to the work-engine model:
+
+* The ``memory`` step retrieves across the four allowed memory types
+  (``MEMORY_TYPES`` in ``directives.backend.memory``). Each type is
+  one ``ask`` from the visibility-line perspective.
+* ``hits`` counts distinct types that returned at least one entry.
+* ``ids`` is the deduped list of returned entry ids preserving the
+  retrieval order encoded in ``state.memory``.
+
+Privacy floor: this module never emits entry bodies, summaries,
+``path``/``source`` fields, or anything beyond ``id`` and ``type``.
+The privacy regression test (``tests/contracts/test_memory_
+visibility_redaction.py``) keeps this guarantee enforced.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+ICON = "\U0001F9E0"  # 🧠
+DEFAULT_MAX_INLINE_IDS = 5
+DEFAULT_ASKED_TYPES = (
+    "domain-invariants",
+    "architecture-decisions",
+    "incident-learnings",
+    "historical-patterns",
+)
+
+
+def summarise_visibility(
+    memory: Any,
+    *,
+    asked_types: Iterable[str] = DEFAULT_ASKED_TYPES,
+) -> dict[str, Any]:
+    """Reduce ``state.memory`` into the visibility-line slice.
+
+    ``memory`` is the list of hit dicts produced by
+    ``directives.backend.memory``. Returns ``{"asks", "hits", "ids"}``
+    with privacy-safe values only.
+    """
+    asked = tuple(asked_types)
+    if not memory or not isinstance(memory, list):
+        return {"asks": 0, "hits": 0, "ids": []}
+    asks = len(asked)
+    seen_types: set[str] = set()
+    ids: list[str] = []
+    seen_ids: set[str] = set()
+    for entry in memory:
+        if not isinstance(entry, dict):
+            continue
+        type_value = entry.get("type")
+        if isinstance(type_value, str):
+            seen_types.add(type_value)
+        entry_id = entry.get("id") or entry.get("rule_id")
+        if not isinstance(entry_id, (str, int)):
+            continue
+        sid = str(entry_id)
+        if sid in seen_ids:
+            continue
+        seen_ids.add(sid)
+        ids.append(sid)
+    hits = len(seen_types) if seen_types else (1 if ids else 0)
+    return {"asks": asks, "hits": hits, "ids": ids}
+
+
+def format_line(
+    summary: dict[str, Any],
+    *,
+    max_inline_ids: int = DEFAULT_MAX_INLINE_IDS,
+) -> str | None:
+    """Render the visibility line; return ``None`` when ``asks == 0``.
+
+    Cap inline ids at ``max_inline_ids`` and append ``…+N`` when the
+    list is longer. Returning ``None`` enforces the contract clause
+    "If ``asks == 0``, the engine MUST suppress the line entirely".
+    """
+    asks = int(summary.get("asks", 0) or 0)
+    if asks <= 0:
+        return None
+    hits = int(summary.get("hits", 0) or 0)
+    raw_ids = summary.get("ids") or []
+    ids = [str(i) for i in raw_ids if isinstance(i, (str, int))]
+    if max_inline_ids < 0:
+        max_inline_ids = 0
+    inline = ids[:max_inline_ids]
+    overflow = len(ids) - len(inline)
+    rendered_ids = ", ".join(inline)
+    if overflow > 0:
+        suffix = ", " if rendered_ids else ""
+        rendered_ids = f"{rendered_ids}{suffix}\u2026+{overflow}"
+    return f"{ICON} Memory: {hits}/{asks} \u00b7 ids=[{rendered_ids}]"
+
+
+def should_emit(
+    summary: dict[str, Any],
+    *,
+    cost_profile: str = "standard",
+    visibility_off: bool = False,
+) -> bool:
+    """Apply the cadence + opt-out gates from the contract."""
+    if visibility_off:
+        return False
+    asks = int(summary.get("asks", 0) or 0)
+    if asks <= 0:
+        return False
+    profile = (cost_profile or "standard").strip().lower()
+    if profile == "lean":
+        return asks >= 3
+    return True
+
+
+__all__ = [
+    "DEFAULT_ASKED_TYPES",
+    "DEFAULT_MAX_INLINE_IDS",
+    "ICON",
+    "format_line",
+    "should_emit",
+    "summarise_visibility",
+]

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.17.0"
+    "version": "1.19.0"
   },
   "plugins": [
     {

package/CHANGELOG.md

@@ -318,6 +318,103 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.19.0](https://github.com/event4u-app/agent-config/compare/1.18.0...1.19.0) (2026-05-05)
+
+### Features
+
+* **rules:** treat slash command as operator and prose as target ([f73947e](https://github.com/event4u-app/agent-config/commit/f73947e93bc8121524d811a5f17d548499023751))
+* **ai-council:** auto-prune session folders past retention window ([bbfaa93](https://github.com/event4u-app/agent-config/commit/bbfaa93fd28bc3a84030c30ab9cea429ac68bea5))
+* **settings-sync:** additive sync with verbatim user-line preservation ([f996cf3](https://github.com/event4u-app/agent-config/commit/f996cf3811e924d2ffecbc3d11bac447308efc5a))
+* **roadmap:** add quality_cadence setting to throttle /roadmap execute pipeline runs ([d5ef7bf](https://github.com/event4u-app/agent-config/commit/d5ef7bf85e70c95103c6fc65507f99fdd35050dd))
+* **ci:** add lint_showcase_sessions gate ([c4f48bb](https://github.com/event4u-app/agent-config/commit/c4f48bba05d266899282742320b7f83bc636cc7c))
+* **council:** add CLI entry-point with estimate/run/render subcommands (Phase 6.7) ([f20f599](https://github.com/event4u-app/agent-config/commit/f20f5993dda1325f19f8e26a130ef37f995b5a9d))
+* **taskfile:** modularize Taskfile.yml into taskfiles/ groups (Phase 6.1) ([41cbe46](https://github.com/event4u-app/agent-config/commit/41cbe46d6f9289c98bb3f717dcac74c44154fc21))
+* **hooks:** add verify-before-complete and minimal-safe-diff concerns ([2507aef](https://github.com/event4u-app/agent-config/commit/2507aefcc88857fd120cfd09d5c93555cb89b868))
+* **governance:** one-off-script lifecycle + showcase capture + tier-retrofit archive ([0940f91](https://github.com/event4u-app/agent-config/commit/0940f91d74a759de6601f5367e8fd3e2925f4c51))
+* **work_engine:** decision-trace + memory-visibility hooks, scoring, contracts ([91cb0a5](https://github.com/event4u-app/agent-config/commit/91cb0a547971ff5f9597997bc36607ca6049be89))
+* **rules:** tier frontmatter sweep across all 58 rules + lint + budget rebaseline ([a9c3694](https://github.com/event4u-app/agent-config/commit/a9c3694bb22cbd87574c1ffd53d0cb9b76a60479))
+* **hooks:** per-platform bridges, install integration, hooks:status, smoke ([c33058a](https://github.com/event4u-app/agent-config/commit/c33058a49a20c6d4d21a7933b85ea3b618a6d433))
+* **hooks:** universal dispatcher, manifest, envelope, state I/O ([28c4f8c](https://github.com/event4u-app/agent-config/commit/28c4f8c7f0e7bd50b6403dfeab0dcaa623dd5ca3))
+* add collision check to roadmap creation flow ([19b65d5](https://github.com/event4u-app/agent-config/commit/19b65d5f2500ddb7c8bfcbb7466c33de0d64043c))
+
+### Bug Fixes
+
+* **ai-council:** use max_completion_tokens for OpenAI o1 models ([8d9e179](https://github.com/event4u-app/agent-config/commit/8d9e179a36d3ba2c68de09ba426782fd43792b85))
+* **skills/roadmap-management:** drop task-ci literal to satisfy portability lint ([790af5e](https://github.com/event4u-app/agent-config/commit/790af5e61a3af3472027d2eef1d939106c95d6ea))
+* **install.sh:** avoid SIGPIPE race in clean_stale that deleted live files ([08670d6](https://github.com/event4u-app/agent-config/commit/08670d66c6285a84d15e44d00e5cfecc6870a4e7))
+* **roadmaps:** re-anchor relative paths in archived 3a protocol ([e0017de](https://github.com/event4u-app/agent-config/commit/e0017de1b55b43e2c8ea5b3f9b51f077cb68e0e3))
+
+### Performance
+
+* **ci:** parallelise test suite — bash xargs -P + pytest-xdist ([2e74b31](https://github.com/event4u-app/agent-config/commit/2e74b3104d0a881832cbebb4dcaddecc865b65c3))
+* **ai-council/bundler:** fix catastrophic regex backtracking in redact() ([0e277e7](https://github.com/event4u-app/agent-config/commit/0e277e7ca36b452cc1cc4d8abdeaaa14e9aebbaf))
+
+### Documentation
+
+* **roadmaps:** add chat-history hook-only reduction roadmap ([529f3b7](https://github.com/event4u-app/agent-config/commit/529f3b7c06fae8b560ce0bb436fc701b1418a024))
+* **roadmaps:** add road-to-proof-not-features draft ([4664bd4](https://github.com/event4u-app/agent-config/commit/4664bd42a0e0bd8ff9eddc6d8907ff9a217a8f11))
+* tighten wording in three rules and one command ([14ed864](https://github.com/event4u-app/agent-config/commit/14ed8640f18e3bfc52819bb150066ecc453fb17a))
+* **roadmap:** archive road-to-feedback-consolidation (43/43 done) ([f053c6d](https://github.com/event4u-app/agent-config/commit/f053c6df94620a4cbf89e75ba73a7bb369c9395b))
+* **roadmap:** close Phase 1 — showcase infra shipped, sessions deferred ([49a156b](https://github.com/event4u-app/agent-config/commit/49a156b40eecd728841b2eaef3565850f1020e0a))
+* **roadmap:** close Phase 6 — mark 6.1/6.4/6.5/6.7 complete (89%) ([4b645cf](https://github.com/event4u-app/agent-config/commit/4b645cf9fc9acb7b7bc227f790e00c3efae66790))
+* **readme:** 3-path entry table + tier-coverage drift sentinel (Phase 6.4 + 6.5) ([ae712f0](https://github.com/event4u-app/agent-config/commit/ae712f034e5eb67481175835d7a9eded921ee222))
+* **roadmap:** mark Phase 5 complete (Tier-1 hook concerns shipped) ([433c5d1](https://github.com/event4u-app/agent-config/commit/433c5d1efb352de26671caed0e24a6b1e673eab6))
+* **readme:** trim under 500-line linter ceiling ([2c3b496](https://github.com/event4u-app/agent-config/commit/2c3b496552cdd73b02e7b08d5c231a9f86e326c3))
+* **agents:** roadmap progress, ownership matrix, agents index sync ([2368e37](https://github.com/event4u-app/agent-config/commit/2368e37aee886125997bfda4299599ebea9a14ec))
+* add feedback consolidation roadmap and regenerate dashboard ([96fce45](https://github.com/event4u-app/agent-config/commit/96fce45055b2da367b8a45536c7a5bdcd1e03d84))
+
+### Refactoring
+
+* **hooks:** concerns share atomic-write state I/O + dispatcher-friendly stdin ([5cac705](https://github.com/event4u-app/agent-config/commit/5cac705edfd46ad8d27ffd0008bdf4723317a4eb))
+
+### Tests
+
+* **hooks:** parity tests for tier-1 hook concerns ([540468c](https://github.com/event4u-app/agent-config/commit/540468cd150447d6b588d3015865660a555e4f8d))
+
+### Chores
+
+* **tools:** regenerate .windsurfrules with slash-command-routing-policy operator/target sections ([7825600](https://github.com/event4u-app/agent-config/commit/78256000a2da9cc313eb272059bb363acbc5290e))
+* **rules:** sync compressed slash-command-routing-policy with operator/target sections ([916357c](https://github.com/event4u-app/agent-config/commit/916357c7d185d717187845478e8318025330d3a9))
+* **rules:** promote verify-before-complete and minimal-safe-diff to tier 2a ([d62fb84](https://github.com/event4u-app/agent-config/commit/d62fb845a14065706c46c4425b261b57ac155c27))
+* ignore .agent-chat-history.session sidecar ([42741c8](https://github.com/event4u-app/agent-config/commit/42741c87f83bf24416eb3916cbced865ae642688))
+* **infra:** wire lint-rule-tiers + lint-hook-manifest + lint-one-off-age tasks; pyproject pytest importlib; .windsurfrules Copilot fallback ([5b88093](https://github.com/event4u-app/agent-config/commit/5b8809398dd332a3ebad3478f7a38cf48ef119e1))
+* **roadmaps:** archive structural-optimization companion artefacts ([928c884](https://github.com/event4u-app/agent-config/commit/928c88469787cd037c54acd0006039ee9b86f9bb))
+
+## [1.18.0](https://github.com/event4u-app/agent-config/compare/1.17.0...1.18.0) (2026-05-04)
+
+### Features
+
+* **rules:** mandate hardening tier classification on new and edited rules ([42ff7c1](https://github.com/event4u-app/agent-config/commit/42ff7c1765e931a3e5e487ef83d01ca597a65800))
+* **hooks:** wire Tier 1 hooks on Claude Code for hardening parity ([55ede24](https://github.com/event4u-app/agent-config/commit/55ede24e65b5ab7e827fa3a40b04fe9dab091392))
+* **rules:** enforce placement for agent-authored roadmaps ([1624ede](https://github.com/event4u-app/agent-config/commit/1624ede571bcdd28adb7d8dd4868a92b9dbde646))
+* roadmap complexity standard with shape and tier linters ([bd1bac6](https://github.com/event4u-app/agent-config/commit/bd1bac650013e449e7318c60586b7648dbcc144e))
+* **hardening:** tier-1 hooks for onboarding-gate and context-hygiene ([5d107cd](https://github.com/event4u-app/agent-config/commit/5d107cd6fa1352d609491df12604ae0ddb7d7113))
+* **always-budget:** hard-compress direct-answers and no-cheap-questions ([2cb9b0b](https://github.com/event4u-app/agent-config/commit/2cb9b0be7b3e6486c3689fec75e7672507ca97cb))
+* outcome baselines and pattern-memory demos for foundational rules ([f43ede7](https://github.com/event4u-app/agent-config/commit/f43ede70a59cb7460557e6d76b041562056e78ee))
+
+### Bug Fixes
+
+* **check-refs:** treat .augment/state/*.json as runtime-only paths ([3d4c766](https://github.com/event4u-app/agent-config/commit/3d4c76695af38e764facc8630a97e553f5aac67f))
+* **rules:** sync compressed rules with hardening callouts ([89bd072](https://github.com/event4u-app/agent-config/commit/89bd07267d04d6346a1f36df92759c9208777a9a))
+
+### Documentation
+
+* **contexts,contracts:** unlink stable artifacts from archived roadmaps ([af4e5c2](https://github.com/event4u-app/agent-config/commit/af4e5c2de6dfb0d2143f48213e04d41c9354deca))
+* **contexts:** lock Tier 2 nudge surface, Tier 3 dispositions, platform parity ([10685a7](https://github.com/event4u-app/agent-config/commit/10685a7f3fceec1b93365cef3531a5e81f55396f))
+* **roadmaps:** relocate budget-v2-matrix to contexts as durable rationale ([33b903a](https://github.com/event4u-app/agent-config/commit/33b903a36feeacffddedde11ff9b1bc3bd5173e3))
+
+### Refactoring
+
+* **state:** move hook runtime state from .augment/state/ to agents/state/ ([ef5265e](https://github.com/event4u-app/agent-config/commit/ef5265e1ead67b089c4438efcbd4e94f120c6d3e))
+
+### Chores
+
+* **plugin:** restructure marketplace.json to registry shape ([f3e6f24](https://github.com/event4u-app/agent-config/commit/f3e6f2425fefef2cc5fc338d27e8628ab45a4d41))
+* **council:** archive Budget-v2 audit one-off ([00bf46e](https://github.com/event4u-app/agent-config/commit/00bf46e680e3a66bdbddac35e1ec3a08a8aa11f4))
+* **roadmaps:** archive hardening and context-layer-maturity tracks ([21dec26](https://github.com/event4u-app/agent-config/commit/21dec26b7a6455ab95df6704773426e3dd35574f))
+* regenerate dashboards, hashes, and roadmap progress ([06c50a9](https://github.com/event4u-app/agent-config/commit/06c50a9653bf4250a557ba2fe5a39b8609b3df30))
+* archive ai_council one-off scripts and add location guard ([63e6dbd](https://github.com/event4u-app/agent-config/commit/63e6dbdc49749e97621bcaeaa49f81beb5ffc98c))
+
 ## [1.17.0](https://github.com/event4u-app/agent-config/compare/1.16.0...1.17.0) (2026-05-04)
 
 ### Features

package/README.md

@@ -7,20 +7,22 @@ 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>129 Skills</strong> · <strong>58 Rules</strong> · <strong>95 Commands</strong> · <strong>48 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>129 Skills</strong> · <strong>58 Rules</strong> · <strong>95 Commands</strong> · <strong>51 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
 
 ## Start here
 
-New to agent-config? 60 seconds, three links:
+Three ways in, depending on what you're doing today:
 
-1. **[Install](#quickstart)** — `composer require` or `npm install`, then run the installer.
-2. **[First command](#2-minute-demo-implement-ticket)** — `/implement-ticket` or `/work` walkthrough.
-3. **[Where the rules live](#documentation)** — `.augment/`, `.claude/`, `.cursor/`, and friends.
+| Path | Audience | What it does |
+|---|---|---|
+| **[`/onboard`](.agent-src/commands/onboard.md)** | New user, fresh install | Captures name, IDE, rtk, and cost profile; sets `onboarding.onboarded=true` |
+| **[`task ci`](docs/development.md#ci--verification)** | Contributor working **on** this package | Runs the full sync + lint + test pipeline; must be green before push |
+| **[`task generate-tools`](docs/development.md#tool-generation)** | Multi-agent user / consumer project | Rebuilds `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` from the source |
 
----
+If none of those apply yet — start with the [Quickstart](#quickstart) and pick a path once it's installed.
 
 ## Quickstart
 
@@ -63,6 +65,14 @@ project-locally for all supported AI tools. Task is required for
 *contributors* who want to rebuild the compressed content locally — see
 [CONTRIBUTING.md](CONTRIBUTING.md).
 
+**Verify hook coverage** after installing — every supported platform
+(Augment, Claude, Cursor, Cline, Windsurf, Gemini CLI, Copilot fallback)
+is wired through one universal dispatcher per
+[`hook-architecture-v1`](docs/contracts/hook-architecture-v1.md). Run
+`./agent-config hooks:status` for the matrix (`--strict` for CI,
+`--format json` for tooling). The installer also dry-fires the
+dispatcher per bridge as a post-install smoke test (skip: `--no-smoke`).
+
 ### For individual use (optional)
 
 Install directly in your agent for global, cross-project use:
@@ -479,20 +489,10 @@ task lint-skills   # Lint skills, rules, commands
 
 ## Requirements
 
-**To install the package into a consumer project:**
-
-- **Bash** — primary installer is `scripts/install`, orchestrating
-  `scripts/install.sh` (payload sync) and `scripts/install.py` (bridges).
-  Available on macOS, Linux, and WSL.
-- **Python 3.10+** — required for the bridge stage only. Pre-installed
-  on macOS 12.3+ and all major Linux distros. If missing, the
-  orchestrator skips bridges and completes the payload sync.
-- **Composer or npm** — to pull the package itself.
-
-**Platform support:** macOS 12.3+, Linux (modern distros), and Windows
-(WSL2) are fully supported. Git Bash works but symlinks require
-Developer Mode; native PowerShell / cmd is not supported. Contributors
-rebuilding `.augment/` locally also need [Task](https://taskfile.dev/).
+- **Bash** — `scripts/install` orchestrates payload sync (`install.sh`) and bridges (`install.py`).
+- **Python 3.10+** — bridge stage only; missing → orchestrator skips bridges.
+- **Composer or npm** — to pull the package.
+- **Platform:** macOS 12.3+, Linux, WSL2. Git Bash needs Developer Mode for symlinks; native PowerShell / cmd unsupported. Contributors rebuilding `.augment/` also need [Task](https://taskfile.dev/).
 
 ## License
 

package/config/agent-settings.template.yml

@@ -121,6 +121,24 @@ pipelines:
   # want a silent agent; `custom` profile ignores this default entirely.
   skill_improvement: true
 
+# --- Roadmap execution ---
+#
+# Controls when /roadmap execute runs the project's quality pipeline
+# (the `task ci` / `make test` / `npm run check` style command).
+# Steps are ALWAYS marked `[x]` and the dashboard is ALWAYS regenerated
+# in the same response — that cadence is governed by `roadmap-progress-sync`
+# and is non-negotiable. This setting only governs *quality tool runs*.
+roadmap:
+  # When to run quality tools during /roadmap execute.
+  #   end_of_roadmap = once, before archiving the completed roadmap (default — fastest, fewest tokens)
+  #   per_phase      = once after every completed phase
+  #   per_step       = after every completed step (legacy verbose; highest token cost)
+  # Trade-off: end_of_roadmap saves tokens and time but lets errors compound
+  # across phases. Pick per_phase if the work is risky or unfamiliar.
+  # Iron Law `verify-before-complete` still applies — fresh quality output
+  # is mandatory before any "roadmap complete" claim regardless of cadence.
+  quality_cadence: end_of_roadmap
+
 # --- Subagent orchestration ---
 #
 # Controls model selection and parallelism for subagent-based workflows
@@ -195,6 +213,11 @@ ai_council:
     max_calls: 10
     max_total_usd: 0.50
 
+  # Retention for `agents/council-sessions/` audit folders. Sessions
+  # older than this are pruned automatically on the next `save()`.
+  # `0` disables pruning (keep forever — disk grows unbounded).
+  session_retention_days: 14
+
 # --- Onboarding ---
 #
 # Tracks whether the initial setup flow (/onboard) has been completed

package/docs/architecture.md

@@ -65,7 +65,7 @@ fails on any source-side violation, without producing artifacts.
 | **Skills** | 129 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
 | **Rules** | 58 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
 | **Commands** | 95 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
-| **Guidelines** | 48 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Guidelines** | 51 | 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 **327 public artefacts** shipped by
+Consumer-facing catalog of all **330 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
@@ -301,14 +301,16 @@ are excluded.
 | command | [`upstream-contribute`](../.agent-src/commands/upstream-contribute.md) |  | Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package |
 | command | [`work`](../.agent-src/commands/work.md) |  | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git. |
 
-## Guidelines (48)
+## Guidelines (51)
 
 | kind | name | category | description |
 |---|---|---|---|
 | guideline | [`agent-interaction-and-decision-quality`](../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md) | agent-infra |  |
+| guideline | [`ask-when-uncertain-demos`](../docs/guidelines/agent-infra/ask-when-uncertain-demos.md) | agent-infra |  |
 | guideline | [`asking-and-brevity-examples`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md) | agent-infra |  |
 | guideline | [`break-glass-usage`](../docs/guidelines/agent-infra/break-glass-usage.md) | agent-infra |  |
 | guideline | [`developer-judgment`](../docs/guidelines/agent-infra/developer-judgment.md) | agent-infra |  |
+| guideline | [`direct-answers-demos`](../docs/guidelines/agent-infra/direct-answers-demos.md) | agent-infra |  |
 | guideline | [`engineering-memory-data-format`](../docs/guidelines/agent-infra/engineering-memory-data-format.md) | agent-infra |  |
 | guideline | [`language-and-tone-examples`](../docs/guidelines/agent-infra/language-and-tone-examples.md) | agent-infra |  |
 | guideline | [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) | agent-infra |  |
@@ -322,6 +324,7 @@ are excluded.
 | guideline | [`self-improvement-pipeline`](../docs/guidelines/agent-infra/self-improvement-pipeline.md) | agent-infra |  |
 | guideline | [`size-and-scope`](../docs/guidelines/agent-infra/size-and-scope.md) | agent-infra |  |
 | guideline | [`tool-integration`](../docs/guidelines/agent-infra/tool-integration.md) | agent-infra |  |
+| guideline | [`verify-before-complete-demos`](../docs/guidelines/agent-infra/verify-before-complete-demos.md) | agent-infra |  |
 | guideline | [`readme-size-and-splitting`](../docs/guidelines/docs/readme-size-and-splitting.md) | docs |  |
 | guideline | [`playwright`](../docs/guidelines/e2e/playwright.md) | e2e |  |
 | guideline | [`api-design`](../docs/guidelines/php/api-design.md) | php |  |

package/docs/contracts/adr-settings-sync-engine.md

@@ -0,0 +1,127 @@
+---
+stability: beta
+---
+
+# ADR — Settings sync engine: stdlib-only round-trip
+
+> **Status:** Decided · 2026-05-04
+> **Context:** Additive Settings Sync roadmap — review round 2
+> (Self-Review + AI Council, Anthropic + OpenAI) flagged the
+> 735-line `scripts/sync_yaml_rt.py` as potential NIH burden vs.
+> adopting `ruamel.yaml` as a third-party dependency.
+> **Builds on:** [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md)
+> § Sync rules — defines the additive-merge-with-user-line-preservation
+> contract this engine implements.
+
+## Decision
+
+`.agent-settings.yml` synchronization uses a **custom, stdlib-only
+round-trip parser + emitter** in [`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py),
+not `ruamel.yaml` or any other third-party YAML library.
+
+The engine implements a narrow YAML subset (block-mappings, scalars,
+flow-list values, comments, CRLF/LF) that covers the full surface of
+`.agent-settings.yml` plus its template (`config/agent-settings.template.yml`).
+Out-of-subset YAML — anchors, aliases, multi-document streams, complex
+keys, nested flow mappings — is **not supported** and raises `ValueError`.
+
+The merge layer (additive walk, max-index insertion, scalar→section
+guard, healer for legacy `_user._user.foo` corruption, EOL
+normalization) sits on top of the parser and is custom regardless of
+the parser choice.
+
+## Why this was a real question
+
+Three options were on the table:
+
+1. **`ruamel.yaml` for parse + emit, custom merge on top.** Rejected.
+2. **`PyYAML` for parse, custom emitter for round-trip.** Rejected
+   earlier in the roadmap — PyYAML's parser drops comments and
+   formatting before the merger ever sees them.
+3. **Custom stdlib-only parser + emitter + merger.** Chosen.
+
+### Why ruamel.yaml does not match the contract
+
+The driving requirement from `layered-settings.md` is **verbatim
+user-line preservation** — every byte of every line in the user's
+file is preserved unless that line carries a key the merger is
+explicitly editing. Tests pin this contract by asserting byte-identity
+across two consecutive sync runs (`test_user_block_round_trip_is_idempotent`,
+`test_three_level_idempotent`).
+
+`ruamel.yaml` is a round-trip-aware library, not a verbatim one — it
+re-parses into an in-memory model and **re-emits** through its own
+emitter. This re-emit normalizes:
+
+| Behavior | ruamel.yaml | Custom engine |
+|---|---|---|
+| User-line bytes (whitespace, quoting, blanks) | re-emitted, may shift | preserved 1:1 |
+| Mixed CRLF/LF in user file | normalized to one EOL (typically platform default) | detected + normalized to the user's predominant EOL |
+| `personal: null` blocking template-section injection | requires custom merge logic regardless | scalar guard in `_merge_into` |
+| Legacy `_user._user.foo.bar` healer (one-off migration) | requires custom logic regardless | `heal_user_block` |
+| Synthetic header rendering for newly-inserted template keys | re-emits the entire file | only renders the new subtree |
+| Unknown user blocks at top level | preserved as data, but indent / quoting may shift on emit | preserved verbatim |
+| 3rd-party dependency in distribution package | +1 (`ruamel.yaml` + transitive `ruamel.yaml.clib`) | 0 |
+
+The rows where the libraries diverge are exactly the rows the test
+suite asserts on.
+
+### Cost analysis
+
+| Axis | Custom engine | ruamel.yaml |
+|---|---|---|
+| Lines of code | 735 (engine) + 335 (merge/heal) = 1070 | ~400 (parser+emitter saved) + 335 (merge/heal stays) + adapter glue = ~735 |
+| Net code saved | — | ~335 lines |
+| 3rd-party deps | 0 | +2 (`ruamel.yaml`, `ruamel.yaml.clib`) |
+| Runtime YAML surface | narrow (documented subset) | full YAML 1.2 |
+| Verbatim guarantee | yes | no |
+| Performance | irrelevant — cold-path, runs on profile change | irrelevant |
+
+The 335-line saving is real but offset by a stronger contract (verbatim)
+and a 0-dep posture. The package is a distribution-layer library
+(`composer.json` `type: library`, `package.json` thin manifest); it
+already restricts itself to stdlib for portability across consumer
+projects, several of which lock Python deps tightly.
+
+## Consequences
+
+- **Maintenance:** the engine must keep covering the YAML subset its
+  template + user files exercise. Any new template feature (e.g. a
+  block-style nested list) is a parser change, not a config change.
+- **Error surface:** YAML outside the subset (anchors, complex keys)
+  surfaces as a friendly `ValueError` from `_rt.sync()`, caught by
+  `sync_agent_settings.main` and turned into exit code 2 with a
+  user-readable message. Documented in
+  `tests/test_sync_agent_settings.py::test_malformed_user_yaml_exits_2_with_message`.
+- **Test debt:** `tests/test_sync_round_trip.py` (34 tests) and
+  `tests/test_sync_agent_settings.py` (15 tests) are the contract.
+  Any parser change must keep those green and is the entry point
+  for new fixtures under `tests/fixtures/sync_yaml_rt/`.
+
+## Revisit triggers
+
+This decision is revisited (new ADR with successor link) when **any**
+of the following holds:
+
+1. `.agent-settings.yml` schema gains a YAML feature outside the
+   supported subset (anchors, multi-doc, complex keys, nested flow
+   mappings) — the cost of extending the parser exceeds the cost of
+   adopting ruamel.
+2. The verbatim-preservation contract is relaxed (e.g. consumers
+   accept that sync can re-format) — the driver for the custom engine
+   is gone.
+3. The 0-dep posture for Python tooling is dropped at the package level
+   — the marginal cost of one more dep collapses.
+4. A maintenance bug surfaces in the engine that would have been
+   prevented by ruamel's mature spec coverage.
+
+## See also
+
+- [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md)
+  § Sync rules — the contract this engine implements.
+- [`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py) module
+  docstring — the supported YAML subset, listed exhaustively.
+- `tests/test_sync_round_trip.py` — verbatim, scalar-guard, healer,
+  CRLF, and synthetic-header pinning.
+- `tests/test_sync_agent_settings.py` — CLI integration, profile
+  override, malformed-input exit code.