@event4u/agent-config 2.9.0 → 2.11.0

package/docs/contracts/memory-visibility-v1.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Memory-visibility v1
@@ -24,6 +25,7 @@ and a single space:
 
 ```
 🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>]
+🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>] · affected: <keys>
 ```
 
 Examples:
@@ -32,6 +34,8 @@ Examples:
 🧠 Memory: 3/4 · ids=[mem_42, mem_57, mem_91]
 🧠 Memory: 0/2 · ids=[]
 🧠 Memory: 5/5 · ids=[mem_a01, mem_a02, mem_a03, …+2]
+🧠 Memory: 3/4 · ids=[mem_42, mem_57] · affected: confidence_band,applied_rules
+🧠 Memory: 2/4 · ids=[mem_42] · affected: none
 ```
 
 Cap at 5 ids inline; remainder rendered as `…+N`. The full id list
@@ -45,10 +49,15 @@ lives in the decision-trace JSON
 | `hits` | Count of `memory_retrieve_*` calls during this turn that returned ≥ 1 entry. |
 | `asks` | Count of `memory_retrieve_*` calls during this turn — both successful and empty. |
 | `ids` | Stable memory entry ids returned across all calls, deduped, ordered by retrieval timestamp. |
+| `affected` | Optional trailing segment. Comma-separated list of decision-trace keys that diverged when this memory was consulted vs not consulted. Closed key list defined in [`decision-trace-v1.md § Memory consequence keys`](decision-trace-v1.md#memory-consequence-keys). Rendered as `none` when `hits ≥ 1` but no key diverged. Omitted entirely when `hits == 0` or when the producer cannot compute a counterfactual trace. |
 
 `hits ≤ asks` is invariant. If `asks == 0`, the engine MUST suppress
 the line entirely — no `0/0` noise.
 
+The `affected` segment is a forward-compat trailing extension per
+the Stability clause below — clients pinned to the segment-free
+shape MUST still parse the line.
+
 ## Privacy floor
 
 The visibility line and the JSON it derives from MUST NOT contain:
@@ -88,6 +97,31 @@ counts and ids for downstream metrics.
 Cost-profile lookup respects `.agent-settings.yml`'s `cost_profile`
 key. Default is `standard`.
 
+## End-of-run "Memory changed decisions" block
+
+When the visibility line carries a non-empty `affected` segment, the
+engine MUST also append a structured block at the end of the run's
+report surface so reviewers can audit attribution without parsing
+the inline segment:
+
+```
+Memory changed decisions:
+- mem_42 → confidence_band
+- mem_57 → confidence_band
+```
+
+Rules:
+
+- Suppressed entirely when `affected` is empty or absent (no key
+  diverged, or memory was not consulted).
+- Each consulted id from the visibility line's `ids` is paired with
+  each affected key. v1 attribution is aggregate; per-id attribution
+  is a follow-up risk tracked in the roadmap Risk register.
+- Block heading is the literal string `Memory changed decisions:`
+  followed by `-` bullet lines in `<id> → <key>` shape.
+- Implementation: `format_changed_decisions_block` in
+  `work_engine/scoring/memory_visibility.py`.
+
 ## Audit-as-memory feed
 
 The visibility output produced by the engine is the input to the

package/docs/contracts/one-off-script-lifecycle.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # One-off-script lifecycle

package/docs/contracts/orchestration-dsl-v1.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Orchestration DSL v1

package/docs/contracts/package-self-orientation.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Package Self-Orientation

package/docs/contracts/persona-schema.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Persona Schema — two-tier (Core / Specialist)

package/docs/contracts/release-trunk-sync.md

@@ -0,0 +1,104 @@
+---
+stability: beta
+keep-beta-until: 2026-08-12
+---
+
+# ADR — Release-trunk sync: main fast-forwards on every tag
+
+> **Status:** Decided · 2026-05-14
+> **Context:** PR #43 feedback (Level-5/6 product rating) and PR #143
+> revealed `main` lagging the latest tag by N skills + rules at multiple
+> points across the 2.x cycle. External readers landing on `main`
+> consistently saw stale README counts and missing skill catalogues
+> relative to the npm/Packagist artefact.
+> **Closes:** [Road to Productization](../../agents/roadmaps/road-to-productization.md) § P1.2.
+
+## Decision
+
+Every tagged release (`X.Y.Z`) **fast-forwards `main` to the tag's
+commit as the final step of the release pipeline**. No exceptions. No
+grace period.
+
+The fast-forward is owned by [`scripts/release.py`](../../scripts/release.py)
+and runs after the GitHub Release is published. The release pipeline
+is **not green** until `main == <new-tag>` at the remote.
+
+`main` is therefore a **moving stable trunk pointer**, not a feature
+branch. External readers (README, AGENTS.md, marketplace metadata, npm
+tarball provenance) reading `main` see the artefact that was last
+published, not work-in-progress.
+
+## Protocol
+
+1. `scripts/release.py` cuts `release/X.Y.Z`, bumps version files,
+   opens a release PR against `main`, waits for CI, merges.
+2. The merge commit on `main` becomes the tag's commit; the tag is
+   pushed.
+3. `publish-npm.yml` and the marketplace flow trigger on the tag.
+4. The release pipeline asserts `git rev-parse origin/main ==
+   git rev-parse refs/tags/X.Y.Z` before exit-0.
+5. If a hotfix lands on `release/X.Y.Z` after step 1 but before step 4,
+   the FF still happens — release-branch commits are part of the
+   release, not a separate trunk.
+
+### Why fast-forward, not merge
+
+Fast-forward keeps `main` linear with the tag history. A merge-commit
+on top of the tag would put `main` at a SHA that is **not** the tag's
+SHA, re-introducing the exact divergence this contract closes.
+
+If a fast-forward is impossible (force-push to `main`, divergent
+history, abandoned release-prep), the pipeline **fails loudly**; the
+operator either resets `main` manually with an audit trail or aborts
+the release.
+
+## CI Gate (P1.3)
+
+[`scripts/check_release_trunk_sync.py`](../../scripts/check_release_trunk_sync.py)
+runs on every `release/X.Y.Z` branch (detected by `git rev-parse
+--abbrev-ref HEAD` matching `^release/\d+\.\d+\.\d+$`).
+
+It enforces: **`main` is at most ONE tagged release behind the
+release-prep branch's target version.**
+
+- On `release/2.11.0`: `main` may be at `2.10.0` or `2.11.0`. `2.9.0`
+  or older → **hard fail**.
+- On any other branch class (feature, fix, chore, docs, the agent's
+  own `feat/road-to-productization` branch): the check is a **no-op**
+  exit-0 — feature branches never trip the gate.
+- Wired into `task ci` as `check-release-trunk-sync`. No warning-only
+  mode; the exit code is the gate.
+
+### Bootstrap mode
+
+When the repo state does not yet match the gate (transitional first
+run after this contract lands), the check reads
+`docs/contracts/release-trunk-sync.bootstrap` for an opt-out window
+keyed by current version. The bootstrap file is purged at the next
+release. Absence of the file = gate is live.
+
+## Rollback
+
+Revertible by removing `check-release-trunk-sync` from `Taskfile.yml`
+and deleting `scripts/check_release_trunk_sync.py`. No state, no
+schema, no migration. Branch-detection key (`release/X.Y.Z`) is
+already used by `scripts/release.py` so removing this contract does
+not orphan the convention.
+
+## Risks
+
+| # | Risk | Mitigation |
+|---|---|---|
+| 1 | Gate fires on feature branches mid-PR | Branch-name regex; non-`release/` branches no-op exit-0 |
+| 2 | Hotfix release leaves `main` behind | FF runs **after** hotfix commits land on the release branch |
+| 3 | Manual tag (no `scripts/release.py`) skips the FF | Out of scope of this contract — covered by `release-guard.yml` which fails on tag/version mismatch; manual tags already break the pipeline |
+| 4 | Detached HEAD or shallow checkout breaks detection | Check gracefully exits-0 with a `::warning::` line when `git rev-parse --abbrev-ref HEAD == HEAD` (detached) |
+
+## See also
+
+- [`scripts/release.py`](../../scripts/release.py) — release pipeline owner.
+- [`.github/workflows/release-guard.yml`](../../.github/workflows/release-guard.yml)
+  — tag/version-file integrity gate (orthogonal: this contract handles
+  trunk position, release-guard handles version-string integrity).
+- [`agents/roadmaps/road-to-productization.md`](../../agents/roadmaps/road-to-productization.md)
+  § Phase 1.

package/docs/contracts/roadmap-complexity-standard.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Roadmap Complexity Standard

package/docs/contracts/rule-classification.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 

package/docs/contracts/rule-interactions.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Rule-Interaction Matrix
@@ -99,6 +100,31 @@ junior (yields). For `complements`, ordering is documentary only.
   in the rule files.
 - Skill ↔ rule interactions — the matrix is rule-only. Skills are
   invoked, not always-active.
+- **Orchestration-layer surfaces** (AI Council, Memory, Work-Engine /
+  Decision-Engine): these are runtime systems, not `always`-rules.
+  Their interactions are governed by their own contracts and stay
+  out of this matrix by design — see "Out of scope" below.
+
+## Out of scope — orchestration surfaces (Council × Memory × Work-Engine)
+
+The matrix is **rule-only**. The orchestration layer is governed by
+dedicated contracts; cross-referencing them here would duplicate the
+source of truth and weaken it. Canonical contracts:
+
+| Surface | Canonical contract |
+|---|---|
+| Decision-Engine gates (`min_confidence`, `block_on_risk`, `require_memory_hits`, `on_block`) | [`decision-engine-gates.md`](decision-engine-gates.md) |
+| Decision-trace shape (what the engine emits per phase) | [`decision-trace-v1.md`](decision-trace-v1.md) |
+| Memory contract (entries, scopes, retention) | [`agent-memory-contract.md`](agent-memory-contract.md) |
+| Memory visibility in the trace (`affected` keys) | [`memory-visibility-v1.md`](memory-visibility-v1.md) |
+| AI-Council consultation flow | [`../skills/ai-council/SKILL.md`](../../.agent-src.uncompressed/skills/ai-council/SKILL.md) |
+
+Where an `always`-rule **does** interact with one of these surfaces
+(e.g. `non-destructive-by-default` gating a memory-driven action), the
+gate lives in the rule and the precedence is captured in this matrix
+as a rule-pair (the orchestration surface is the *occasion*, not a
+participant). For Council ↔ Memory ↔ Work-Engine interactions among
+themselves, the dedicated contracts above are authoritative.
 
 ## See also
 

package/docs/contracts/rule-priority-hierarchy.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Rule Priority Hierarchy

package/docs/contracts/rule-router.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 

package/docs/contracts/settings-sync-yaml-subset.md

@@ -0,0 +1,139 @@
+---
+stability: beta
+keep-beta-until: 2026-08-12
+---
+
+# Settings-sync YAML subset
+
+**Purpose.** Pin the YAML feature set that `.agent-settings.yml` and
+`config/agent-settings.template.yml` may use, so contributors can cite a
+contract instead of inferring it from
+[`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py) source. The
+sync engine ([ADR](adr-settings-sync-engine.md)) is a custom stdlib-only
+round-trip parser/emitter; staying inside the subset below is what
+keeps user-line preservation (every byte of every user line round-trips
+unchanged unless the merger explicitly edits the key).
+
+Authoritative source: this document. The module docstring of
+`sync_yaml_rt.py` mirrors it; on drift, this file wins and the docstring
+is corrected to match.
+
+## Supported
+
+### Document shape
+
+- One YAML document per file. No `---` or `...` document separators.
+- UTF-8. CRLF and LF line endings — both accepted, preserved per-line.
+
+### Mappings (sections)
+
+- Block-style mappings only (`key: value` on its own line).
+- Indent: 2- or 4-space, **no tabs** in indent.
+- Nested mappings unlimited in depth (the template uses 3 levels —
+  e.g. `chat_history.archive.cleanup_after_days`).
+- Duplicate keys at the same level: **last wins** (the later line
+  carries the value; the earlier entry is replaced).
+
+### Scalars (values)
+
+- Bare scalars: `enabled`, `42`, `true`, `~`, `null`, `None`.
+- Single-quoted strings: `'literal text'`.
+- Double-quoted strings: `"literal text"`.
+- Bools, ints, `~` / `null` / `None` are kept **verbatim** — the
+  parser does not normalise `True` → `true` or `null` → `~`.
+
+### Lists (sequences of scalars)
+
+- Block-style lists:
+  ```yaml
+  allowlist:
+    - foo
+    - bar
+  ```
+  Indent inside the list must be consistent.
+- Inline-flow lists, **flat only**: `[a, b, c]`.
+- List items are scalars only. Nested mappings inside a list item are
+  **not** supported (see below).
+
+### Comments and blank lines
+
+- `#`-comments — full-line and inline (`key: value  # comment`). Both
+  preserved verbatim, including leading whitespace and the gap before
+  `#`.
+- Blank lines preserved verbatim — the engine never collapses them.
+
+## Not supported (parser raises `ValueError` with a line number)
+
+The following YAML features are out of contract. A user file that uses
+any of them surfaces as `ValueError` from `scripts/sync_yaml_rt.py:sync`,
+which `scripts/sync_agent_settings.py` catches and reports as **exit
+code 2** with a line-numbered message.
+
+- **Anchors and aliases** — `&name`, `*name`.
+- **Multi-document streams** — `---` / `...` separators.
+- **Nested flow mappings** — `key: {nested: value}` inline. Block-style
+  nested mappings are fine; flow-style nested mappings are not.
+- **Nested mappings inside list items** — `- name: foo` followed by
+  indented children. Lists hold scalars only.
+- **Complex keys** — `? [composite, key]: value`.
+- **Tagged scalars** — `!!str 42`, `!Custom value`.
+- **Multiline scalar styles** — `|` (literal) and `>` (folded) block
+  scalars.
+- **Tabs in indent** — even one tab character in indent.
+- **Mixed indent inside a block** — every child of a parent must share
+  the same indent.
+
+Pinned by `tests/test_sync_round_trip.py` (34 tests) — every
+not-supported feature has at least one fixture that asserts the
+`ValueError` message.
+
+## Test pinning
+
+- Verbatim round-trip: `tests/test_sync_round_trip.py::test_user_block_round_trip_is_idempotent`, `::test_three_level_idempotent`.
+- Out-of-subset rejection: same file, fixtures under
+  `tests/fixtures/sync_yaml_rt/` named `bad_*.yml`.
+- CLI exit code on malformed input:
+  `tests/test_sync_agent_settings.py::test_malformed_user_yaml_exits_2_with_message`.
+
+Any parser change is gated on those tests staying green. New fixtures
+for new features land under `tests/fixtures/sync_yaml_rt/`.
+
+## Why this subset (and why it is fixed)
+
+The driving requirement from
+[`layered-settings`](../guidelines/agent-infra/layered-settings.md) is
+**verbatim user-line preservation**. `ruamel.yaml` and PyYAML both
+re-emit through their own emitters, which normalises whitespace,
+quoting, and blank-line placement. A stdlib parser limited to this
+subset gives byte-identity across two consecutive syncs — the property
+the merger relies on for additive insertion.
+
+Out-of-subset YAML therefore is not a parser bug; it is a contract
+violation by the user file. The friendly `ValueError` and exit code 2
+are the contract's failure surface.
+
+## Revisit triggers
+
+This subset is **fixed** until one of the
+[ADR revisit triggers](adr-settings-sync-engine.md#revisit-triggers)
+fires — namely:
+
+1. `.agent-settings.yml` schema gains a YAML feature outside the subset
+   (anchors, multi-doc, complex keys, nested flow mappings) — the cost
+   of extending the parser exceeds the cost of adopting `ruamel.yaml`.
+2. The verbatim-preservation contract is relaxed — the driver for the
+   custom parser 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 ruamel's mature spec
+   coverage would have prevented.
+
+A new ADR (with successor link) is required to change the subset; this
+document is updated in the same commit.
+
+## See also
+
+- [`docs/contracts/adr-settings-sync-engine.md`](adr-settings-sync-engine.md) — decision record for the stdlib-only engine.
+- [`docs/guidelines/agent-infra/layered-settings.md`](../guidelines/agent-infra/layered-settings.md) § Sync rules — the additive-merge-with-user-line-preservation contract this subset implements.
+- [`scripts/sync_yaml_rt.py`](../../scripts/sync_yaml_rt.py) — implementation; module docstring mirrors this file.
+- [`scripts/sync_agent_settings.py`](../../scripts/sync_agent_settings.py) — CLI driver and exit-code contract.

package/docs/contracts/skill-domains.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Skill Domains — 6-domain taxonomy

package/docs/contracts/tier-3-contrib-plugin.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Tier-3 contrib plugin pattern

package/docs/contracts/ui-stack-extension.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # UI Stack Extension — adding a new frontend stack to the UI track

package/docs/contracts/ui-track-flow.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # UI Track — Flow Contract

package/docs/customization.md

@@ -139,7 +139,7 @@ Rules:
 | Setting | Default | Description |
 |---|---|---|
 | `agent_config_version` | *(empty)* | Exact semver pin of the agent-config release (see above). Empty = unpinned. |
-| `cost_profile` | `minimal` | Token budget (`minimal`, `balanced`, `full`, `custom`) |
+| `cost_profile` | `balanced` | Token budget (`minimal`, `balanced`, `full`, `custom`) — rationale: [`docs/contracts/cost-profile-defaults.md`](contracts/cost-profile-defaults.md) |
 | `personal.user_name` | *(empty)* | User's first name for personalized responses |
 | `personal.minimal_output` | `true` | Suppress intermediate output |
 | `personal.play_by_play` | `false` | Share intermediate findings during analysis |

package/docs/getting-started.md

@@ -123,9 +123,11 @@ The system supports four configuration profiles:
 Set your profile in `.agent-settings.yml`:
 
 ```yaml
-cost_profile: minimal
+cost_profile: balanced
 ```
 
+`balanced` is the default — kernel + tier-1 auto-rules. Rationale:
+[`docs/contracts/cost-profile-defaults.md`](contracts/cost-profile-defaults.md).
 You can override any individual setting. See [Customization](customization.md) for details.
 
 ---

package/docs/installation.md

@@ -240,8 +240,8 @@ wrapper (`./agent-config`) can fall through to it when no
 The orchestrator chains payload sync and bridge generation:
 
 ```bash
-bash scripts/install                  # defaults to cost_profile=minimal
-bash scripts/install --profile=balanced
+bash scripts/install                  # defaults to cost_profile=balanced
+bash scripts/install --profile=minimal
 bash scripts/install --force          # overwrite existing bridges
 bash scripts/install --skip-bridges   # payload only
 bash scripts/install --skip-sync      # bridges only
@@ -287,7 +287,7 @@ regardless of which AI tool they use.** No per-developer plugin installation nee
 After initial setup, commit these files:
 
 ```
-.agent-settings.yml                ← shared profile (e.g., cost_profile: minimal)
+.agent-settings.yml                ← shared profile (e.g., cost_profile: balanced)
 agents/installed-tools.lock        ← AI bill of materials (ADR-008, Phase 3)
 .augment/                          ← rules, skills, commands (symlinks)
 .cursor/rules/                     ← Cursor rules (symlinks)
@@ -517,16 +517,18 @@ The system works immediately with sensible defaults. Optionally, create `.agent-
 to choose a profile:
 
 ```yaml
-cost_profile: minimal
+cost_profile: balanced
 ```
 
 | Profile | What's active | For whom |
 |---|---|---|
-| `minimal` (default) | Rules + Skills only, zero overhead | New users, solo devs |
+| `minimal` | Kernel only — Iron-Law floor, zero router | Token-constrained agents |
 | `balanced` | + Runtime dispatcher + shell handler | Most teams |
 | `full` | + Tool adapters (GitHub, Jira) | Platform teams |
 
-No profile configured = `minimal` behavior. → [Full profile details](customization.md)
+No profile configured = `balanced` behavior (default). Rationale:
+[`docs/contracts/cost-profile-defaults.md`](contracts/cost-profile-defaults.md).
+→ [Full profile details](customization.md)
 
 ---
 

package/docs/readme-split-plan.md

@@ -0,0 +1,102 @@
+# README three-audience split — plan
+
+Annotated outline for `P2.2a` in
+[`road-to-proof-not-features.md`](../agents/roadmaps/road-to-proof-not-features.md).
+Decides the **information architecture**, not the prose. No content
+rewrite happens in this step; `P2.2b` applies the mapping.
+
+## Target headings (top of README, in order)
+
+1. **Use it in your project** — anchor `#use-it`
+2. **Prove it** — anchor `#prove-it`
+3. **Contribute** — anchor `#contribute`
+
+Each branch opens with one paragraph + one primary CTA. AI Council is
+not mentioned in any branch (verified by `P3.4`).
+
+### Anchor-stability promise
+
+`P2.2b` must keep these existing anchors intact so external inbound
+links survive:
+
+| Anchor today | Lives under (new) | Why |
+|---|---|---|
+| `#quickstart` | `#use-it` | npm/composer search results, social links |
+| `#supported-tools` | `#use-it` | most-cited section on the web |
+| `#what-your-agent-is-asked-to-do` | `#prove-it` | linked from blog posts |
+| `#documentation` | `#use-it` | docs portal entry |
+| `#development` | `#contribute` | contributor guides |
+
+Other section anchors may be renamed; `lint-readme` checks the table
+above and the three new audience anchors only.
+
+## Block-by-block mapping
+
+Every existing top-of-README block, in source order, mapped to
+exactly one branch. "Drop" = block is retired; "Move" = relocated as-
+is; "Reframe" = block stays but its lead-in / CTA changes (still no
+copy rewrite in this step — the reframe direction is decided here,
+applied in `P2.2b`).
+
+| # | Block (current heading) | Lines | Branch | Action | Notes |
+|---|---|---|---|---|---|
+| 1 | Title + tagline + stats badge | 1–13 | — | Keep above branches | Survives unchanged; counts updated by `update_readme_counts`. |
+| 2 | `## Start here` (three-paths table) | 15–25 | — | **Drop** | Replaced by the three branch sections themselves; rows map cleanly: `/onboard` → Use, `task ci` → Contribute, `task generate-tools` → Use. |
+| 3 | `## Quickstart` lead-in | 27–39 | Use it | Move | Becomes the opening paragraph under `#use-it`. |
+| 4 | `### For teams (recommended)` | 40–79 | Use it | Move | Primary CTA for `#use-it`. |
+| 5 | `### Pick specific AIs` | 81–101 | Use it | Move | Stays under Quickstart subtree. |
+| 6 | `#### Global install` | 103–124 | Use it | Move | Subsection of Pick specific AIs. |
+| 7 | `### For individual use (optional)` | 126–144 | Use it | Move | Alternate install path. |
+| 8 | `### Self-hosted MCP on Cloudflare` | 146–226 | Use it | Move | Operator install path; deep but consumer-facing. |
+| 9 | `#### Lock your Worker behind Bearer` | 196–213 | Use it | Move | Subsection of MCP block; stays nested. |
+| 10 | `### Optional: persistent agent memory` | 228–247 | Use it | Move | Companion package install. |
+| 11 | `## 2-minute demo: /implement-ticket` | 251–285 | Prove it | Move | Flagship evidence surface. Primary CTA for `#prove-it`. |
+| 12 | `### Sibling entrypoint: /work` | 287–316 | Prove it | Move | Same engine, second envelope. |
+| 13 | `### Product UI track` | 318–347 | Prove it | Move | Third evidence surface. |
+| 14 | `## What your agent is asked to do` | 351–365 | Prove it | Move | Intent table — proof of behaviour, not features. |
+| 15 | `## What this package is — and what it isn't` | 369–398 | Prove it | Move | Scope-honesty surface; loadbearing for the "proof" framing. |
+| 16 | `## You don't need everything` (cost profiles) | 402–423 | Prove it | Reframe | Currently sits as "feature" prose; the new framing is "proof that the package shrinks to fit". |
+| 17 | `## Who this is for` (stack coverage) | 427–439 | Prove it | Move | Honest depth claim — also evidence-side. |
+| 18 | `## Featured Skills` | 443–462 | Use it | Move | Catalog teaser → consumer surface. |
+| 19 | `## Featured Commands` | 466–481 | Use it | Move | Catalog teaser → consumer surface. |
+| 20 | `## Supported Tools / Project-installed` | 487–527 | Use it | Move | Per-tool install matrix. |
+| 21 | `## Supported Tools / Plugin-installed` | 529–541 | Use it | Move | Subsection. |
+| 22 | `## Supported Tools / Cloud / Hosted-agent` | 543–558 | Use it | Move | Subsection. |
+| 23 | `## Core Principles` | 562–570 | Prove it | Move | Behavioural floor — proof-side. |
+| 24 | `## Documentation` (index table) | 574–589 | Use it | Move | Doc portal entry. |
+| 25 | `### Maintainer telemetry (opt-in)` | 591–608 | Contribute | Move | Engagement measurement — maintainer / contributor surface. |
+| 26 | `### Context-aware command suggestion` | 610–629 | Use it | Move | Consumer-facing feature toggle. |
+| 27 | `## Development` | 633–642 | Contribute | Move | Primary CTA for `#contribute`. |
+| 28 | `## Requirements` | 644–649 | Use it | Move | Install gate — Use-side, not Contribute. |
+| 29 | `## License` | 651–653 | — | Keep at bottom | Footer; outside the three branches. |
+
+## Branch outlines (post-migration shape)
+
+### `## Use it in your project`
+
+Opening paragraph: one-line "Two minutes from npx to a better-behaved
+agent." Primary CTA: `npx @event4u/agent-config init`. Children:
+Quickstart subtree (#3–#7), MCP operator path (#8–#9), optional memory
+(#10), Featured Skills + Commands (#18–#19), Supported Tools (#20–#22),
+Documentation (#24), Command suggestion (#26), Requirements (#28).
+
+### `## Prove it`
+
+Opening paragraph: one-line "What the agent actually does, with
+evidence." Primary CTA: `/implement-ticket` demo (#11). Children:
+`/work` (#12), Product UI track (#13), Intent table (#14), Scope
+statement (#15), Cost profiles reframed (#16), Stack coverage (#17),
+Core Principles (#23).
+
+### `## Contribute`
+
+Opening paragraph: one-line "Editing rules, skills, commands — the
+contributor loop." Primary CTA: `task ci` (#27). Children: Maintainer
+telemetry (#25). External links: `CONTRIBUTING.md`, `AGENTS.md`,
+`docs/development.md`.
+
+## Verification (P2.2c preview)
+
+Grep-based test asserts `## Use it in your project`, `## Prove it`,
+`## Contribute` appear in that order. `lint-readme` keeps anchor
+stability for the rows in the Anchor-stability promise table.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.9.0",
+    "version": "2.11.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,