@event4u/agent-config 2.8.0 → 2.10.0

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

@@ -4,6 +4,12 @@ Implements the v1 line shape from
 ``docs/contracts/memory-visibility-v1.md``:
 
     🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>]
+    🧠 Memory: <hits>/<asks> · ids=[<...>] · affected: <keys>
+
+The optional ``· affected: <keys>`` trailing segment surfaces which
+closed-list decision-trace keys diverged because memory was
+consulted — see ``docs/contracts/decision-trace-v1.md`` "Memory
+consequence keys".
 
 The semantics matched to the work-engine model:
 
@@ -23,6 +29,8 @@ from __future__ import annotations
 
 from typing import Any, Iterable
 
+from .decision_trace import derive_confidence_band, derive_risk_class
+
 ICON = "\U0001F9E0"  # 🧠
 DEFAULT_MAX_INLINE_IDS = 5
 DEFAULT_ASKED_TYPES = (
@@ -32,6 +40,13 @@ DEFAULT_ASKED_TYPES = (
     "historical-patterns",
 )
 
+CONSEQUENCE_KEYS: tuple[str, ...] = (
+    "confidence_band",
+    "risk_class",
+    "applied_rules",
+    "test_plan",
+)
+
 
 def summarise_visibility(
     memory: Any,
@@ -69,16 +84,111 @@ def summarise_visibility(
     return {"asks": asks, "hits": hits, "ids": ids}
 
 
+def _normalise_key_value(value: Any) -> Any:
+    """Return a comparable shape for a consequence-key value.
+
+    List-shaped keys (``applied_rules``, ``test_plan``) compare as
+    sorted tuples so order is not a divergence; scalar keys
+    (``confidence_band``, ``risk_class``) compare as-is.
+    """
+    if isinstance(value, list):
+        return tuple(sorted(str(item) for item in value))
+    return value
+
+
+def diff_consequence_keys(
+    trace_with: dict[str, Any], trace_without: dict[str, Any],
+) -> list[str]:
+    """Return sorted keys whose values diverge between two traces.
+
+    Iterates the closed ``CONSEQUENCE_KEYS`` list defined in
+    ``docs/contracts/decision-trace-v1.md``. A key is considered
+    *diverged* when its normalised value differs between the two
+    traces. Per the contract, when both sides are ``None`` the key
+    is suppressed from the diff entirely.
+    """
+    affected: list[str] = []
+    for key in CONSEQUENCE_KEYS:
+        a = trace_with.get(key)
+        b = trace_without.get(key)
+        if a is None and b is None:
+            continue
+        if _normalise_key_value(a) != _normalise_key_value(b):
+            affected.append(key)
+    return sorted(affected)
+
+
+def compute_affected(
+    *,
+    memory_hits: int,
+    verify_claims: int = 0,
+    verify_first_try_passes: int = 0,
+    ambiguity_flag: bool = False,
+    changes: Any = None,
+    applied_rules: list[str] | None = None,
+    test_plan: list[str] | None = None,
+) -> list[str] | None:
+    """Compute the ``affected`` consequence keys for the visibility line.
+
+    Returns:
+        * ``None`` when no memory was consulted (``memory_hits <= 0``)
+          — caller MUST omit the ``· affected: …`` segment.
+        * ``[]`` when memory was consulted but no closed-list key
+          diverged — caller MUST render ``· affected: none``.
+        * sorted list of keys otherwise.
+
+    The counterfactual trace is "what the heuristics would have
+    emitted if ``memory_hits`` had been ``0``". v1 covers
+    ``confidence_band`` and ``risk_class`` via the existing scoring
+    helpers; ``applied_rules`` and ``test_plan`` pass through
+    unchanged because they are not yet memory-derived in the
+    engine — the keys stay in the closed list so the diff
+    infrastructure is in place when they wire in.
+    """
+    if memory_hits <= 0:
+        return None
+    trace_with = {
+        "confidence_band": derive_confidence_band(
+            memory_hits=memory_hits,
+            verify_claims=verify_claims,
+            verify_first_try_passes=verify_first_try_passes,
+            ambiguity_flag=ambiguity_flag,
+        ),
+        "risk_class": derive_risk_class(changes),
+        "applied_rules": list(applied_rules) if applied_rules else None,
+        "test_plan": list(test_plan) if test_plan else None,
+    }
+    trace_without = {
+        "confidence_band": derive_confidence_band(
+            memory_hits=0,
+            verify_claims=verify_claims,
+            verify_first_try_passes=verify_first_try_passes,
+            ambiguity_flag=ambiguity_flag,
+        ),
+        "risk_class": derive_risk_class(changes),
+        "applied_rules": list(applied_rules) if applied_rules else None,
+        "test_plan": list(test_plan) if test_plan else None,
+    }
+    return diff_consequence_keys(trace_with, trace_without)
+
+
 def format_line(
     summary: dict[str, Any],
     *,
     max_inline_ids: int = DEFAULT_MAX_INLINE_IDS,
+    affected: list[str] | None = None,
 ) -> 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".
+
+    When ``affected`` is not ``None``, append the
+    ``· affected: <keys>`` trailing segment from
+    ``docs/contracts/memory-visibility-v1.md``: empty list renders as
+    ``affected: none`` (consulted but no key diverged);
+    non-empty list renders the comma-separated keys.
     """
     asks = int(summary.get("asks", 0) or 0)
     if asks <= 0:
@@ -94,7 +204,39 @@ def format_line(
     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}]"
+    line = f"{ICON} Memory: {hits}/{asks} \u00b7 ids=[{rendered_ids}]"
+    if affected is not None:
+        rendered_affected = ",".join(affected) if affected else "none"
+        line = f"{line} \u00b7 affected: {rendered_affected}"
+    return line
+
+
+def format_changed_decisions_block(
+    ids: Iterable[str], affected: Iterable[str] | None,
+) -> str | None:
+    """Render the end-of-run "Memory changed decisions" report block.
+
+    Per ``docs/contracts/memory-visibility-v1.md``: lists
+    ``<id> → <key>`` rows derived from the same diff source as the
+    visibility line's ``affected`` segment. Returns ``None`` when
+    no key diverged (``affected`` empty / ``None``) so the caller
+    suppresses the block entirely.
+
+    Attribution in v1 is aggregate: each consulted id pairs with
+    each affected key. Per-id attribution is captured as a
+    follow-up risk in the roadmap Risk register.
+    """
+    if not affected:
+        return None
+    affected_list = sorted(affected)
+    id_list = [str(i) for i in ids if isinstance(i, (str, int))]
+    if not id_list:
+        return None
+    lines = ["Memory changed decisions:"]
+    for entry_id in id_list:
+        for key in affected_list:
+            lines.append(f"- {entry_id} \u2192 {key}")
+    return "\n".join(lines)
 
 
 def should_emit(
@@ -116,9 +258,13 @@ def should_emit(
 
 
 __all__ = [
+    "CONSEQUENCE_KEYS",
     "DEFAULT_ASKED_TYPES",
     "DEFAULT_MAX_INLINE_IDS",
     "ICON",
+    "compute_affected",
+    "diff_consequence_keys",
+    "format_changed_decisions_block",
     "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": "2.8.0",
+    "version": "2.10.0",
     "keywords": [
       "agent-config",
       "skills",
@@ -70,6 +70,7 @@
         "./.claude/skills/bug-analyzer",
         "./.claude/skills/bug-fix",
         "./.claude/skills/bug-investigate",
+        "./.claude/skills/build-buy-partner",
         "./.claude/skills/challenge-me",
         "./.claude/skills/challenge-me-vision",
         "./.claude/skills/challenge-me-with-docs",
@@ -86,6 +87,8 @@
         "./.claude/skills/command-writing",
         "./.claude/skills/commit",
         "./.claude/skills/commit-in-chunks",
+        "./.claude/skills/comp-banding",
+        "./.claude/skills/competitive-moat-analysis",
         "./.claude/skills/competitive-positioning",
         "./.claude/skills/composer-packages",
         "./.claude/skills/compress",
@@ -95,6 +98,7 @@
         "./.claude/skills/context-create",
         "./.claude/skills/context-document",
         "./.claude/skills/context-refactor",
+        "./.claude/skills/contracts-cognition",
         "./.claude/skills/conventional-commits-writing",
         "./.claude/skills/copilot-agents-optimization",
         "./.claude/skills/copilot-config",
@@ -109,6 +113,7 @@
         "./.claude/skills/customer-research",
         "./.claude/skills/dashboard-design",
         "./.claude/skills/data-flow-mapper",
+        "./.claude/skills/data-handling-judgment",
         "./.claude/skills/database",
         "./.claude/skills/dcf-modeling",
         "./.claude/skills/deal-qualification-meddic",
@@ -151,6 +156,7 @@
         "./.claude/skills/fix-seeder",
         "./.claude/skills/flux",
         "./.claude/skills/forecast-accuracy",
+        "./.claude/skills/forecasting",
         "./.claude/skills/form-handler",
         "./.claude/skills/fundraising-narrative",
         "./.claude/skills/funnel-analysis",
@@ -160,6 +166,7 @@
         "./.claude/skills/grill-me",
         "./.claude/skills/gtm-launch",
         "./.claude/skills/guideline-writing",
+        "./.claude/skills/hiring-loop-design",
         "./.claude/skills/implement-ticket",
         "./.claude/skills/incident-commander",
         "./.claude/skills/jira-integration",
@@ -189,6 +196,7 @@
         "./.claude/skills/livewire",
         "./.claude/skills/livewire-architect",
         "./.claude/skills/logging-monitoring",
+        "./.claude/skills/market-entry-analysis",
         "./.claude/skills/markitdown",
         "./.claude/skills/mcp",
         "./.claude/skills/mcp-builder",
@@ -214,6 +222,8 @@
         "./.claude/skills/okr-tree-modeling",
         "./.claude/skills/onboard",
         "./.claude/skills/onboarding-design",
+        "./.claude/skills/onboarding-program",
+        "./.claude/skills/one-on-one-cadence",
         "./.claude/skills/openapi",
         "./.claude/skills/optimize",
         "./.claude/skills/optimize-agents-dir",
@@ -222,12 +232,14 @@
         "./.claude/skills/optimize-rtk",
         "./.claude/skills/optimize-skills",
         "./.claude/skills/orchestrate",
+        "./.claude/skills/org-design",
         "./.claude/skills/override",
         "./.claude/skills/override-create",
         "./.claude/skills/override-manage",
         "./.claude/skills/override-management",
         "./.claude/skills/package-reset",
         "./.claude/skills/package-test",
+        "./.claude/skills/perf-feedback-craft",
         "./.claude/skills/performance",
         "./.claude/skills/performance-analysis",
         "./.claude/skills/persona-writing",
@@ -241,6 +253,7 @@
         "./.claude/skills/po-discovery",
         "./.claude/skills/positioning-strategy",
         "./.claude/skills/prepare-for-review",
+        "./.claude/skills/privacy-review",
         "./.claude/skills/project-analysis-core",
         "./.claude/skills/project-analysis-hypothesis-driven",
         "./.claude/skills/project-analysis-laravel",
@@ -287,6 +300,8 @@
         "./.claude/skills/rtk-output-filtering",
         "./.claude/skills/rule-compliance-audit",
         "./.claude/skills/rule-writing",
+        "./.claude/skills/runway-cognition",
+        "./.claude/skills/scenario-modeling",
         "./.claude/skills/script-writing",
         "./.claude/skills/secrets-management",
         "./.claude/skills/security",
@@ -318,6 +333,7 @@
         "./.claude/skills/tests-execute",
         "./.claude/skills/threat-model",
         "./.claude/skills/threat-modeling",
+        "./.claude/skills/throughput-vs-morale-tradeoff",
         "./.claude/skills/token-optimizer",
         "./.claude/skills/traefik",
         "./.claude/skills/ui-component-architect",
@@ -328,6 +344,7 @@
         "./.claude/skills/using-git-worktrees",
         "./.claude/skills/validate-feature-fit",
         "./.claude/skills/verify-completion-evidence",
+        "./.claude/skills/vision-articulation",
         "./.claude/skills/voc-extract",
         "./.claude/skills/voice-and-tone-design",
         "./.claude/skills/websocket",

package/AGENTS.md

@@ -20,7 +20,7 @@ task ci                # full pipeline — green before PR
 - **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).
 - **Content pipelines** — A [compression](docs/architecture/compression.md), B [Augment projection](docs/architecture/augment-projection.md), C [multi-tool projection](docs/architecture/multi-tool-projection.md), D [Claude.ai bundle](docs/architecture/claude-bundle.md). Index: [`docs/architecture.md`](docs/architecture.md).
 - **Editing this repo** — Iron-Law rules (portability, source-of-truth, skill-quality) + Thin-Root contract: [`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** — `npm install` + `scripts/install.sh` + `.agent-settings.yml` opt-in flags, sandbox/offline install paths, verified-offline manifest: [`README.md`](README.md).
+- **Consumer story** — `npx` + `scripts/install.sh` + `.agent-settings.yml` opt-in flags, sandbox/offline install paths, verified-offline manifest: [`README.md`](README.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

@@ -18,6 +18,78 @@ Entry-shape contract: [`docs/contracts/CHANGELOG-conventions.md`](docs/contracts
 
 Four roadmaps land in this release.
 
+**Tier-0 trim (`road-to-surface-discipline` Phase 1)** — six CLI
+commands moved from Tier-0 to Tier-1 in `./agent-config --help` to
+collapse the daily-driver surface down to the seven commands a new
+contributor actually needs in their first session. Commands stay
+fully invokable by full name — only the default `--help` view
+changed. Source of truth: `docs/contracts/command-surface-tiers.md`.
+
+Pre/post diff of `./agent-config --help` Tier-0 block:
+
+| Command | Pre | Post | Rationale |
+|---|:-:|:-:|---|
+| `init` | Tier-0 | Tier-0 | daily-driver entrypoint |
+| `sync` | Tier-0 | Tier-0 | daily-driver entrypoint |
+| `validate` | Tier-0 | Tier-0 | daily-driver entrypoint |
+| `work` | Tier-0 | Tier-0 | daily-driver entrypoint |
+| `implement-ticket` | Tier-0 | Tier-0 | daily-driver entrypoint |
+| `help` | Tier-0 | Tier-0 | help meta-command |
+| `--version` | Tier-0 | Tier-0 | help meta-command |
+| `first-run` | Tier-0 | **Tier-1** | one-time setup; not in daily loop |
+| `keys:install-anthropic` | Tier-0 | **Tier-1** | one-time credential setup |
+| `keys:install-openai` | Tier-0 | **Tier-1** | one-time credential setup |
+| `council:estimate` | Tier-0 | **Tier-1** | on-demand review tool |
+| `council:run` | Tier-0 | **Tier-1** | on-demand review tool |
+| `council:render` | Tier-0 | **Tier-1** | on-demand review tool |
+
+Net surface delta: **0 new commands, 0 removed commands.** Only the
+`--help` surfacing changed. Run `./agent-config --help --tier=1` for
+the full power-user view (15 commands) or `--tier=all` for
+maintenance / hooks / MCP / telemetry (26 additional commands).
+
+**Diagnostic Hub (`road-to-surface-discipline` Phase 2)** — the
+existing `./agent-config doctor` is repositioned as the single
+entrypoint for health checks. New `CHECK_IDS` registry plus
+`doctor --check <id>` filter; `--list-checks` enumerates every
+runner; failing checks print the literal command line that
+reproduces the failure. Surface delta: **0 new commands** — only
+flags and registry plumbing.
+
+**MCP beta gating (`road-to-surface-discipline` Phase 3)** — MCP
+promotion criteria pinned in
+[`docs/contracts/mcp-beta-criteria.md`](docs/contracts/mcp-beta-criteria.md)
+with a four-gate contract (offline-readiness, scope, drift, runtime).
+`doctor --check mcp-beta-readiness` enforces the gates; failing tests
+under `tests/test_mcp_beta_gates.py` codify the promotion bar.
+Cloud-scope behaviour cross-referenced from
+[`docs/contracts/mcp-cloud-scope.md`](docs/contracts/mcp-cloud-scope.md).
+
+**Architecture refresh (`road-to-surface-discipline` Phase 4)** —
+[`docs/architecture.md`](docs/architecture.md) and
+[`docs/mcp-server.md`](docs/mcp-server.md) re-anchor the 6-layer
+system model (consumer → tools → installer → package → kernel →
+runtime). `AGENTS.md` re-trimmed to honour the Thin-Root contract
+(< 3,000 chars). No code churn — docs only.
+
+**Tier-usage telemetry (`road-to-surface-discipline` Phase 5)** —
+empirical retiering signal added behind a default-off opt-in. New
+`telemetry.tier_usage` namespace in `.agent-settings.yml`; signal
+contract pinned in
+[`docs/contracts/command-clusters.md`](docs/contracts/command-clusters.md)
+§ tier-usage (whitelist: `ts_bucket`, `command`, `tier`, `outcome`,
+`user_hash`; hourly time buckets; 16-char salted user hash; no paths,
+no argv). Retiering thresholds (≥ 20 invocations and ≥ 3 distinct
+users over 30 days) live in the same contract. A new
+`tier_usage_report.py` template script aggregates the local log into
+a frequency table and refuses to render rows that violate the
+privacy floor. The existing `doctor` gains a `tier-usage-readiness`
+check (warn when disabled or empty; fail when every record is
+poisoned; ok when ≥ 1 record passes the floor). Surface delta: **0
+new commands, 0 new skills, 0 new personas** — telemetry rides on
+the existing dispatcher and the existing `doctor` entrypoint.
+
+
 **Package consolidation** — the standalone wrapper package
 `@event4u/create-agent-config` is retired. `npx @event4u/agent-config init`
 is now the canonical one-shot entrypoint; the bundle package gains an
@@ -357,6 +429,68 @@ our recommendation order, not its support status.
 > that forces a new era split (`# Era: 2.8.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [2.10.0](https://github.com/event4u-app/agent-config/compare/2.9.0...2.10.0) (2026-05-14)
+
+### Features
+
+* **ci:** lint-hook-concern-budget Tier-1 fail-closed gate ([8d60b8a](https://github.com/event4u-app/agent-config/commit/8d60b8ab464c4c5bdc6d072bb2a9b0123942e13b))
+* **cli:** settings:check command + YAML subset contract ([638e740](https://github.com/event4u-app/agent-config/commit/638e74017ffea8d7c08073a949e86fde047db109))
+* **hooks:** hooks:doctor + hooks:replay subcommands + fixture corpus ([3156e25](https://github.com/event4u-app/agent-config/commit/3156e25fd3253fc926a57b92e14b407a9ed54b58))
+* **work-engine:** add decision-trace memory_visibility hook + scoring ([bf056ac](https://github.com/event4u-app/agent-config/commit/bf056ace877a696afa5fe758053ea1eb350e5dff))
+
+### Bug Fixes
+
+* **roadmap:** point productization P6 gate at archived proof-not-features path ([35a1009](https://github.com/event4u-app/agent-config/commit/35a1009cffdfde28c7b0384c890c31a7e62b70cf))
+
+### Documentation
+
+* **roadmap:** complete road-to-proof-not-features 16/16 + sync dashboard ([89af72d](https://github.com/event4u-app/agent-config/commit/89af72d5514b74c19d533b5a2e69ff7ddf16ecbc))
+* **readme:** split README by audience + audience-order contract ([60a87c0](https://github.com/event4u-app/agent-config/commit/60a87c056555a80585d25555f3d5b87d54c7283a))
+
+### Refactoring
+
+* **check-council-references:** structural carve-outs for immutable inputs and decision provenance ([3ed7784](https://github.com/event4u-app/agent-config/commit/3ed77841c42c5e3ebf4191611bb7fa4a52ed2fa0))
+
+### Chores
+
+* **roadmap:** archive road-to-proof-not-features (16/16 done, Phase 1 deferred) ([9d05aed](https://github.com/event4u-app/agent-config/commit/9d05aed79a46023b1e95c5488a1e3d5e78748e67))
+
+Tests: 3663 (+60 since 2.9.0)
+
+## [2.9.0](https://github.com/event4u-app/agent-config/compare/2.8.0...2.9.0) (2026-05-13)
+
+### Features
+
+* tier-usage telemetry settings + report template ([22172f2](https://github.com/event4u-app/agent-config/commit/22172f2a59b530034633ff72226506006c5fd81b))
+* mcp beta-readiness criteria with pending gate tests ([3653788](https://github.com/event4u-app/agent-config/commit/36537880e03546e9baf424b2fdd70aa69d41eb03))
+* expand doctor diagnostic hub to 10 checks ([372c193](https://github.com/event4u-app/agent-config/commit/372c19362f8037c76f919a2d918780ae5ec9cb40))
+* **roadmap:** add road-to-surface-discipline (council-reviewed) ([d9da987](https://github.com/event4u-app/agent-config/commit/d9da9870989ccdb7594cd693e9b18608b957ab79))
+* **linter:** wing-4 cognition-boundary checks + spine slot vocab ([c4d9a4b](https://github.com/event4u-app/agent-config/commit/c4d9a4ba8e5c7184b9be0a58d4d8b220a60cab7c))
+
+### Bug Fixes
+
+* **skills:** clear missing_inspect_step + bare_noun warnings ([0c88c6e](https://github.com/event4u-app/agent-config/commit/0c88c6ee45873e47fd8c7d356ec82b28b63b12c5))
+* **docs:** drop roadmap-file pointers from wing-4 ADRs and handoff ([ccd7624](https://github.com/event4u-app/agent-config/commit/ccd7624127094d0a01eda0901fa41c31319f7bc5))
+* **template:** bump agent_config_version pin to 2.8.0 ([f21e916](https://github.com/event4u-app/agent-config/commit/f21e916c6bb793fa6efe7d264a1e069e11ab4c62))
+* **skills:** spine slot citations + finance-partner polish ([9072783](https://github.com/event4u-app/agent-config/commit/90727831b223bd970d8425d158940bf3e3bc104f))
+
+### Documentation
+
+* archive surface-discipline roadmap + 2.8.0 changelog ([551e306](https://github.com/event4u-app/agent-config/commit/551e306e43fa82fffda9178bdaa690b19d8bec4e))
+* 6-layer architecture refresh + thin-root sync ([91d25a8](https://github.com/event4u-app/agent-config/commit/91d25a80b37fb1c1782c2d5f00f23925ba6ec1b3))
+* **roadmap:** complete road-to-money-strategy-ops phase 1 ([83cf9fe](https://github.com/event4u-app/agent-config/commit/83cf9fe99c034b71e146099eddc9ce5b3137f434))
+* **contracts:** register wing-4 spine slots + marketplace entries ([75b829d](https://github.com/event4u-app/agent-config/commit/75b829d162bc18ab3dc2dda6614d15a087a4f32a))
+
+### Refactoring
+
+* trim tier-0 surface from 13 to 7 commands ([a9eafd1](https://github.com/event4u-app/agent-config/commit/a9eafd1c5226c10209e3dee2b972f38d9c0f3dd9))
+
+### Chores
+
+* **generated:** regenerate derived outputs for wing-4 additions ([54f3779](https://github.com/event4u-app/agent-config/commit/54f3779a6d2161ed06bfb327c3e416ec107b4016))
+
+Tests: 3603 (+26 since 2.8.0)
+
 ## [2.8.0](https://github.com/event4u-app/agent-config/compare/2.7.0...2.8.0) (2026-05-13)
 
 ### Features

package/README.md

@@ -7,22 +7,42 @@ 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>189 Skills</strong> · <strong>61 Rules</strong> · <strong>106 Commands</strong> · <strong>71 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>206 Skills</strong> · <strong>61 Rules</strong> · <strong>106 Commands</strong> · <strong>72 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
 
-## Start here
-
-Three ways in, depending on what you're doing today:
-
-| 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.
+## Use it in your project
+
+You run the package from a consumer repo — bootstrap via `npx`, let the
+agent pick up your stack, and ship work end-to-end. New install? Start
+with the [Quickstart](#quickstart) to write `.agent-settings.yml`,
+`.augment/`, `.claude/`, …. Already installed? [Supported Tools](#supported-tools)
+shows which AIs the package wires up, and [Featured Commands](#featured-commands)
+lists the end-to-end workflows (`/implement-ticket`, `/work`, `/commit`,
+`/create-pr`). For a deeper tour, see the
+[2-minute demo: `/implement-ticket`](#2-minute-demo-implement-ticket).
+
+## Prove it
+
+The package is audit-disciplined by construction — every memory consult,
+decision key, and hook concern lands in `agents/state/` so you can
+replay it. [Core Principles](#core-principles) names the four invariants.
+[What this package is — and what it isn't](#what-this-package-is--and-what-it-isnt)
+draws the scope boundary. [Documentation](#documentation) lists the
+contracts the package ships against, including
+[`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) and
+[`decision-trace-v1`](docs/contracts/decision-trace-v1.md).
+
+## Contribute
+
+Working on the package itself rather than with it?
+[Development](#development) covers the `task ci` pipeline,
+[Requirements](#requirements) the toolchain, and
+[Maintainer telemetry](#maintainer-telemetry-opt-in-default-off) the
+opt-in measurement loop. The source-of-truth tree is
+`.agent-src.uncompressed/`; never hand-edit the generated `.augment/`
+or `.agent-src/`.
 
 ## Quickstart
 
@@ -244,7 +264,7 @@ Install in the same project (dev-only):
 npm install --save-dev @event4u/agent-memory
 ```
 
-→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta) · [Built-in MCP server](docs/mcp-server.md) (experimental — local stdio access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`)
+→ [Memory contract & retrieval API](docs/contracts/agent-memory-contract.md) (beta) · [Built-in MCP server](docs/mcp-server.md) (experimental — local stdio access from Claude Desktop / Cursor / Zed / Continue, install with `task mcp:setup`; promotion to beta gated on [`mcp-beta-criteria.md`](docs/contracts/mcp-beta-criteria.md))
 
 ---
 
@@ -510,7 +530,7 @@ slash-commands) &nbsp; 📌 = informational marker only (no auto-discovery
 or manual wiring required)
 
 > **What this means in practice:** Claude Code gets the full project-scoped
-> package (rules + 189 skills + 106 native commands); Augment Code gets the
+> package (rules + 206 skills + 106 native commands); Augment Code gets the
 > same content but only from a single global install at `~/.augment/`.
 > Cursor, Cline, Windsurf, Gemini CLI, GitHub Copilot, Roo Code, Codex CLI,
 > and Continue.dev only get the **rules** natively; skills and commands are

package/config/agent-settings.template.yml

@@ -390,6 +390,34 @@ memory:
   # Example: ["api[_-]?key", "/Users/[a-z]+/Library"]
   redact_patterns: []
 
+# --- Hooks ---
+#
+# Configuration surface for the hook dispatcher (see
+# docs/contracts/hook-architecture-v1.md). Each subkey targets one
+# concern script under scripts/hooks/ or scripts/. Defaults are safe;
+# tune only when CI surfaces a real signal.
+hooks:
+  # Concern budget gate (P3.3, lint_hook_concern_budget.py). Caps how
+  # many concerns may bind to a single (platform, event) cell and
+  # restricts fail_closed=true to an explicit Tier-1 allowlist.
+  #
+  # max_per_event — placeholder until Phase 1 of
+  # road-to-proof-not-features.md captures real session evidence.
+  # Threshold rule per roadmap: max(observed-in-Phase-1) × 1.5, rounded
+  # up. 8 = current-observed-max (5) × 1.5 = 7.5 → 8.
+  #
+  # tier1_concerns — concerns allowed to block agent execution on
+  # failure (fail_closed: true in the manifest). Promotion is explicit
+  # opt-in; keep empty until Phase 1 evidence justifies an entry.
+  #
+  # hard_fail — false = warn-only (default). Flip to true after ≥10
+  # captured sessions across host agents per
+  # road-to-distribution-and-adoption.md.
+  concern_budget:
+    max_per_event: 8
+    tier1_concerns: []
+    hard_fail: false
+
 # --- Update check ---
 #
 # Daily background check against the npm registry for a newer