@event4u/agent-config 2.10.0 → 2.11.0

package/docs/contracts/hook-architecture-v1.md

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

package/docs/contracts/implement-ticket-flow.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # `/implement-ticket` — Flow Contract

package/docs/contracts/installed-tools-lockfile.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Installed-Tools Lockfile — Wire Contract

package/docs/contracts/kernel-membership.md

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

package/docs/contracts/linear-ai-rules-inclusion.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Linear AI — rules inclusion list

package/docs/contracts/linear-ai-three-layers.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Linear AI — three-layer split rationale

package/docs/contracts/linter-structural-model.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Linter Structural Model

package/docs/contracts/load-context-budget-model.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # `load_context:` Budget Accounting Model

package/docs/contracts/load-context-schema.md

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # `load_context:` Frontmatter Schema

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

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

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

@@ -1,5 +1,6 @@
 ---
 stability: beta
+keep-beta-until: 2026-08-12
 ---
 
 # Settings-sync YAML subset

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/package.json

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

package/scripts/check_beta_review_markers.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+Beta-review-marker checker for `docs/contracts/`.
+
+Every contract whose frontmatter declares `stability: beta` MUST carry
+exactly one of the following frontmatter markers (per
+`docs/contracts/STABILITY.md` § Beta-review markers, ratified in
+`road-to-productization.md` § P5.4):
+
+  - `promote-to: stable`
+  - `keep-beta-until: YYYY-MM-DD`     (max 90 days from the last review)
+  - `superseded-by: <contract-id>`
+
+Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
+
+Usage:
+    python3 scripts/check_beta_review_markers.py
+    python3 scripts/check_beta_review_markers.py --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass
+from datetime import date, timedelta
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+CONTRACTS_DIR = Path("docs/contracts")
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+STABILITY_RE = re.compile(r"^stability:\s*(\w+)\s*$", re.MULTILINE)
+PROMOTE_RE = re.compile(r"^promote-to:\s*stable\s*$", re.MULTILINE)
+KEEP_RE = re.compile(r"^keep-beta-until:\s*(\d{4}-\d{2}-\d{2})\s*$", re.MULTILINE)
+SUPERSEDED_RE = re.compile(r"^superseded-by:\s*\S+\s*$", re.MULTILINE)
+
+MAX_REVIEW_WINDOW_DAYS = 90
+
+
+@dataclass
+class Violation:
+    file: str
+    reason: str
+    severity: str  # "error" | "warning"
+
+
+def read_frontmatter(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    txt = path.read_text(encoding="utf-8")
+    m = FRONTMATTER_RE.match(txt)
+    return m.group(1) if m else None
+
+
+def check_one(path: Path, today: date) -> list[Violation]:
+    fm = read_frontmatter(path)
+    if fm is None:
+        return []
+    sm = STABILITY_RE.search(fm)
+    if not sm or sm.group(1) != "beta":
+        return []
+    markers = [
+        ("promote-to", bool(PROMOTE_RE.search(fm))),
+        ("keep-beta-until", bool(KEEP_RE.search(fm))),
+        ("superseded-by", bool(SUPERSEDED_RE.search(fm))),
+    ]
+    set_markers = [name for name, present in markers if present]
+    rel = str(path.relative_to(ROOT))
+    if not set_markers:
+        return [Violation(
+            file=rel,
+            reason="stability=beta but no review marker; add one of "
+                   "`promote-to: stable` | `keep-beta-until: <date>` | "
+                   "`superseded-by: <id>` (see STABILITY.md § Beta-review markers)",
+            severity="error",
+        )]
+    if len(set_markers) > 1:
+        return [Violation(
+            file=rel,
+            reason=f"multiple beta-review markers set ({', '.join(set_markers)}); "
+                   "exactly one is allowed",
+            severity="error",
+        )]
+    km = KEEP_RE.search(fm)
+    if km:
+        review_date = date.fromisoformat(km.group(1))
+        max_date = today + timedelta(days=MAX_REVIEW_WINDOW_DAYS)
+        if review_date > max_date:
+            return [Violation(
+                file=rel,
+                reason=f"keep-beta-until={review_date} exceeds the "
+                       f"{MAX_REVIEW_WINDOW_DAYS}-day window (max: {max_date})",
+                severity="error",
+            )]
+    return []
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    args = ap.parse_args()
+    today = date.today()
+    violations: list[Violation] = []
+    for p in sorted((ROOT / CONTRACTS_DIR).glob("*.md")):
+        violations.extend(check_one(p, today))
+    if args.json:
+        print(json.dumps({"violations": [asdict(v) for v in violations]}, indent=2))
+    else:
+        if not violations:
+            print("✅  All beta contracts carry a valid review marker.")
+        else:
+            for v in violations:
+                icon = "❌" if v.severity == "error" else "⚠️ "
+                print(f"{icon}  {v.file}: {v.reason}")
+            print(f"\n{len(violations)} violation(s).")
+    return 1 if any(v.severity == "error" for v in violations) else 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:  # pragma: no cover
+        print(f"internal error: {exc}", file=sys.stderr)
+        sys.exit(3)