@event4u/agent-config 3.1.1 → 3.3.0

package/docs/decisions/ADR-023-host-agent-protocol.md

@@ -0,0 +1,129 @@
+---
+adr: 023
+status: accepted
+date: 2026-05-24
+decision: host-agent-protocol
+supersedes: —
+superseded_by: —
+phase: v3.x · employee-product-and-external-proof Phase 4
+type: forward-looking
+---
+
+# ADR-023 — Host-agent protocol — CLI shell-out, three-tier fallback
+
+## Status
+
+**Accepted** · 2026-05-24. First of three sub-ADRs created by
+[`ADR-022`](ADR-022-daily-workspace-decomposition.md). Locks the
+protocol boundary between the daily workspace and the host agents
+(Claude Code, Codex, Gemini, Augment, Cursor, Cline, Windsurf,
+others). ADR-024 and ADR-025 follow this decision.
+
+Companion artefacts:
+
+- Contract: [`docs/contracts/host-agent-protocol.md`](../contracts/host-agent-protocol.md)
+- Council question: [`agents/decisions/open-questions/daily-workspace-shape.md`](../../agents/decisions/open-questions/daily-workspace-shape.md)
+- Predecessor ADR: [`ADR-022`](ADR-022-daily-workspace-decomposition.md)
+
+## Context
+
+The council critique on the original Phase 4 chrome question
+identified the host-agent protocol as the blocking unknown. The
+workspace must (a) launch a conversation in the host with a
+pre-filled prompt and (optionally) a pre-selected skill, and (b)
+read structured tool / model output back without parsing the host's
+UI. Either capability missing forces the workspace into "render a
+banner and ask the user to paste" territory.
+
+The inventory in `host-agent-protocol.md` enumerates what each
+named host agent exposes today. The convergent finding:
+
+- **Claude Code, Codex, Gemini** — first-party CLIs with documented
+  stdin / stdout JSON envelopes. Both surfaces present, with caveats.
+- **Augment, Cursor, Cline, Windsurf** — IDE / extension hosts. Hook
+  trampolines exist for post-event observation but neither surface
+  exists at the protocol layer.
+
+No vendor-stable RPC, MCP-driven agent control, or shared SQLite
+exists across this set. Building against any single non-CLI host
+locks the workspace to one IDE; building against the CLI set covers
+the most users without vendor coordination.
+
+## Decision
+
+Adopt a **CLI shell-out protocol** as the workspace's only
+host-agent integration mechanism in v0, with a **three-tier**
+fallback policy:
+
+### Tier 1 — first-class CLI host
+
+Workspace spawns `claude -p "<prompt>" --output-format json` (or the
+Codex / Gemini equivalent) as a subprocess. The JSON envelope is the
+contract; parsing is by named keys; session id is preserved across
+turns. Claude Code is the only Tier-1 host with a stable
+skill-resolution surface today.
+
+### Tier 2 — degraded CLI host
+
+Reserved for hosts that gain one of the two surfaces but not both
+(e.g. launch with no trace, or trace with no launch). No host
+occupies this tier today; the slot exists so vendor changes don't
+force a binary tier 1 / tier 3 reclassification.
+
+### Tier 3 — observe-only host (inbox handoff)
+
+For hosts without either surface (Augment, Cursor, Cline, Windsurf,
+JetBrains, others), the workspace writes the rendered prompt + skill
+context into `~/.event4u/agent-config/workspace/inbox/<id>.md` and
+surfaces a one-line copy-to-clipboard banner. The user opens the
+host themselves. No tighter integration is attempted in v0. Hook
+trampolines (`scripts/hooks/*-dispatcher.sh`) remain available for
+passive recording but do not initiate conversations.
+
+### Stability & fail-closed
+
+A host-agent CLI release that breaks the JSON envelope demotes the
+host to Tier 3 with a workspace banner until
+[`host-agent-protocol.md`](../contracts/host-agent-protocol.md) is
+updated. No silent stdout reparse, no positional-key fallback.
+
+## Consequences
+
+**Positive**
+
+- The workspace can ship against the existing CLI surface today; no
+  vendor coordination required.
+- Tier-3 hosts get a documented, honest fallback rather than a
+  half-built integration that breaks under the next vendor release.
+- The protocol surface is small enough to test end-to-end in CI
+  (subprocess + JSON parse).
+
+**Negative**
+
+- IDE / extension hosts are second-class until vendors expose a
+  launch / trace surface. The workspace cannot drive Cursor or
+  Augment in v0 except via inbox handoff.
+- Codex and Gemini are Tier 1 but lack skill resolution; the
+  workspace must pre-render skill context into the prompt body.
+  ADR-024 covers this.
+- The session-state model is per-host: closing the workspace mid-turn
+  does not stop the host CLI subprocess.
+
+**Reversal cost** — low at the protocol layer (the contract file is
+single-source); medium at the workspace if features have been built
+against assumed Tier-1 capabilities for hosts that drop a surface.
+
+## Open questions (next-ADR-deferred)
+
+- v0 floor: which features survive in the no-skill-surface case
+  (Codex / Gemini)? ADR-024 will answer.
+- Chrome: does the workspace ship as a browser tab against the
+  installer GUI, an Electron / Tauri app, or a TUI? ADR-025 will
+  answer, informed by what ADR-024 demands.
+
+## Cross-references
+
+- Protocol contract: [`docs/contracts/host-agent-protocol.md`](../contracts/host-agent-protocol.md)
+- Council CLI precedent: [`ai-council` skill](../../.agent-src/skills/ai-council/SKILL.md) — same subprocess + JSON-envelope pattern, in production.
+- Hook architecture: [`docs/contracts/hook-architecture-v1.md`](../contracts/hook-architecture-v1.md) — Tier-3 observe-only surface.
+- Predecessor ADR: [`ADR-022`](ADR-022-daily-workspace-decomposition.md).

package/docs/decisions/ADR-024-workspace-v0-feature-floor.md

@@ -0,0 +1,126 @@
+---
+adr: 024
+status: accepted
+date: 2026-05-24
+decision: workspace-v0-feature-floor
+supersedes: —
+superseded_by: —
+phase: v3.x · employee-product-and-external-proof Phase 4
+type: forward-looking
+---
+
+# ADR-024 — Workspace v0 feature floor
+
+## Status
+
+**Accepted** · 2026-05-24. Second of three sub-ADRs created by
+[`ADR-022`](ADR-022-daily-workspace-decomposition.md), depends on
+[`ADR-023`](ADR-023-host-agent-protocol.md). Locks the minimum
+viable shell that recruit-session participants will evaluate.
+
+## Context
+
+The original Phase 4 roadmap proposed a three-rail workspace (role
+launcher · conversation pane · knowledge-source rail) with persistent
+session history, citations, explain-trace, and per-user document
+store. The council flagged this as unachievable in the stated ≤ 6
+weeks given a single-engineer budget — and observed that the
+recruit-session signal (Phase 1) is not yet collected, so the v0
+scope cannot be over-fitted to assumed user needs.
+
+ADR-023 narrows the host-agent surface to Tier-1 CLI shell-out
+(Claude Code, Codex, Gemini) plus a Tier-3 inbox-handoff fallback.
+The v0 floor must be the smallest surface that exercises both tiers
+end-to-end so the recruit sessions can falsify the workspace
+premise.
+
+## Decision
+
+The v0 ships **three features only**:
+
+### 1. Role-keyed task launcher
+
+- Reads `agents/roles/<role>/skills.yml` + per-role prompts directory.
+- One-click launcher: pick role → pick task → renders the prompt
+  with skill context inlined (so it works on Codex / Gemini too).
+- Routes to the active host:
+  - **Tier 1** → spawns `claude -p` / `codex exec` / `gemini` subprocess
+    per [`ADR-023`](ADR-023-host-agent-protocol.md).
+  - **Tier 3** → writes the rendered prompt into the inbox file and
+    surfaces a copy-to-clipboard banner.
+- No skill execution happens inside the workspace itself.
+
+### 2. Per-user conversation log
+
+- Single append-only JSONL per session at
+  `~/.event4u/agent-config/workspace/sessions/<yyyy-mm-dd>/<session-id>.jsonl`.
+- Captures: launcher input (role, task, rendered prompt), host-agent
+  envelope output (Tier 1) or inbox-handoff marker (Tier 3),
+  timestamps. No PII in filenames. Encryption deferred.
+- No remote sync. No cross-user view. Local-only.
+
+### 3. Knowledge-pane stub
+
+- Reads from the Phase 2 `knowledge:` memory namespace (when
+  populated) and renders source citations *next to* the launcher
+  output. Does **not** parse Tier-1 envelopes for inline citations
+  in v0 — that's a v1 ask.
+- When the knowledge namespace is empty, the pane shows a
+  one-line "no sources yet" message and links to the
+  ingestion contract.
+
+### Hard cuts from the original Phase 4 scope
+
+The following are **deferred** to v1+ and explicitly out of scope
+for v0:
+
+- Inline citations inside the conversation pane.
+- Plain-mode explain-trace (Phase 6 dependency; reads same JSON
+  envelope but is its own surface).
+- Document-store integration (Phase 5; would force a v0 schema
+  decision before recruit sessions inform it).
+- Multi-host concurrency (one host CLI at a time per workspace).
+- Accessibility audit (deferred to post-recruit-session because the
+  chrome decision in ADR-025 changes the surface).
+
+### Budget
+
+- Single engineer, **8 weeks** (revised from the original 6 weeks
+  per the council critique). Stretch goal: 6 weeks if recruit
+  sessions defer the knowledge-pane stub.
+
+## Consequences
+
+**Positive**
+
+- Smallest possible surface that exercises the Tier-1 + Tier-3
+  protocol split. Recruit-session signal is interpretable.
+- Codex / Gemini work end-to-end via inlined skill context — no host
+  is structurally excluded.
+- The three artefacts (launcher, JSONL log, knowledge stub) are
+  testable in isolation and ship-able incrementally.
+
+**Negative**
+
+- Phase 5 (documents) and Phase 6 (plain-mode explain) cannot start
+  until v0 lands. Three months of strict sequencing.
+- "No inline citations" will read as a regression vs the original
+  roadmap pitch; needs to be flagged in recruit-session prep.
+- The inbox-handoff fallback is rough by design; Tier-3 users will
+  feel second-class until v1.
+
+**Reversal cost** — low. The three features are decoupled; any can
+be dropped or expanded without rewriting the others.
+
+## Open questions (next-ADR-deferred)
+
+- The chrome: browser-tab against installer GUI · Electron / Tauri ·
+  TUI-first. ADR-025 answers, informed by what these three features
+  actually need from a UI.
+
+## Cross-references
+
+- Predecessor ADRs: [`ADR-022`](ADR-022-daily-workspace-decomposition.md), [`ADR-023`](ADR-023-host-agent-protocol.md).
+- Knowledge ingestion contract: [`docs/contracts/local-knowledge-ingestion.md`](../contracts/local-knowledge-ingestion.md).
+- Role experience contract: [`docs/contracts/role-experience.md`](../contracts/role-experience.md).
+- Roadmap: [`agents/roadmaps/road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/road-to-employee-product-and-external-proof.md) Phase 4.

package/docs/decisions/ADR-025-workspace-chrome.md

@@ -0,0 +1,119 @@
+---
+adr: 025
+status: accepted
+date: 2026-05-24
+decision: workspace-chrome
+supersedes: —
+superseded_by: —
+phase: v3.x · employee-product-and-external-proof Phase 4
+type: forward-looking
+---
+
+# ADR-025 — Workspace chrome — browser tab against the installer GUI
+
+## Status
+
+**Accepted** · 2026-05-24. Third of three sub-ADRs created by
+[`ADR-022`](ADR-022-daily-workspace-decomposition.md), depends on
+[`ADR-023`](ADR-023-host-agent-protocol.md) (protocol) and
+[`ADR-024`](ADR-024-workspace-v0-feature-floor.md) (feature floor).
+Picks the UI shape that wraps the v0 feature floor.
+
+## Context
+
+The original Phase 4 question framed chrome as a four-way pick:
+
+| Option | Pitch |
+|---|---|
+| **(a) Extend installer GUI** | Reuse `packages/core/installer/src/gui/`, add workspace routes. Same loopback server, same CSRF gate, same browser. |
+| **(b) Electron / Tauri desktop app** | Native shell, OS integration (tray icon, hotkeys, autostart). |
+| **(c) Browser tab against the installer GUI** | Same as (a) on the runtime side, but framed as a standalone surface (`/workspace`) the user bookmarks. |
+| **(d) TUI-first** | Terminal UI, optional browser companion. Lowest install footprint. |
+
+The council demanded ADRs 023 and 024 land first. With those in
+place: the v0 surface is three small features (launcher, JSONL log,
+knowledge stub) talking to a CLI subprocess. There is no need for
+OS-level integration, no native APIs to call, no real-time low-latency
+rendering. The installer already ships a loopback HTTP + CSRF +
+browser-launch path ([`docs/contracts/gui-wizard.md`](../contracts/gui-wizard.md)).
+
+## Decision
+
+Ship workspace v0 as **(c) — a browser tab against the installer
+GUI**.
+
+Concretely:
+
+- New route group `/workspace` inside the existing
+  `packages/core/installer/src/gui/server.ts` Node server (single
+  process, single CSRF token, same loopback bind).
+- `npx @event4u/agent-config workspace` opens the browser at the
+  `/workspace` route — same launch UX as `init --gui`, different
+  default landing page.
+- Per-user state lives under `~/.event4u/agent-config/workspace/`
+  (sessions JSONL + inbox files per ADR-024).
+- The installer GUI and the workspace UI **share the same shell**
+  (header, identity strip, theme) so a user installing for the
+  first time sees the workspace as the natural next surface.
+
+### Why this option
+
+- **(c)** is the only option that reuses the proven loopback +
+  CSRF + browser-launch path. Zero new infrastructure surface.
+- **(a)** is functionally identical at runtime — the only delta is
+  framing. The framing matters: a user-facing "workspace" needs its
+  own URL and bookmark story. (c) gets that for free.
+- **(b)** Electron / Tauri adds a ~150 MB install, a code-signing
+  story, an autoupdate channel, and a native event loop. None of
+  that is needed for the v0 floor; deferred to v1 if recruit
+  sessions surface OS-integration demand.
+- **(d)** TUI-first is intriguing for the developer audience but
+  excludes the non-developer roles (galabau owner, content creator,
+  consultant) named in Phase 1 — the audience this roadmap is for.
+
+### Hard rule: no chrome rewrite without recruit-session signal
+
+The chrome choice does **not** survive the recruit sessions
+silently. If Phase 1 (recruit sessions) surfaces a hard "browser
+tabs are wrong" signal from ≥ 2 of the 3 cohorts, this ADR is
+superseded by a new ADR-027 before any further work on the chrome.
+A maintainer note (not a vendor lock-in) ensures the rewrite can
+happen at v0.5, not v2.
+
+## Consequences
+
+**Positive**
+
+- Zero new infrastructure. Installer GUI is the substrate.
+- Cross-platform for free (browser).
+- One CSRF / port / bind story across installer + workspace —
+  one audit surface, one threat model.
+
+**Negative**
+
+- No native OS hooks (tray icon, global hotkey, autostart). Users
+  must manually run `npx ... workspace` to open the tab.
+- Browser-tab UX has a "where did my workspace go?" failure mode
+  when the tab is closed. Mitigated by a persistent bookmark and a
+  reopen-on-launch flag in `.agent-settings.yml`.
+- Electron / Tauri loyalists will read this as conservative; the
+  v1 ADR can reopen if signal supports it.
+
+**Reversal cost** — medium. Migrating from browser-tab to native
+requires re-implementing the shell and the asset bundling pipeline,
+but the underlying state model (filesystem JSONL + inbox) is shell-
+agnostic.
+
+## Open questions (post-recruit-session)
+
+- Tray-icon / autostart story (Phase 1 + Phase 4 v0.5 — defer).
+- Multi-tenant browser surface for the deployed `agent-config`
+  topology (covered by [`ADR-021`](ADR-021-deployment-shape.md);
+  v0 is single-user local only).
+
+## Cross-references
+
+- Predecessor ADRs: [`ADR-022`](ADR-022-daily-workspace-decomposition.md), [`ADR-023`](ADR-023-host-agent-protocol.md), [`ADR-024`](ADR-024-workspace-v0-feature-floor.md).
+- GUI wizard substrate: [`docs/contracts/gui-wizard.md`](../contracts/gui-wizard.md).
+- Installer architecture: [`ADR-016`](ADR-016-installer-architecture.md).
+- Deployment shape: [`ADR-021`](ADR-021-deployment-shape.md).

package/docs/decisions/ADR-026-explain-mode-translation.md

@@ -0,0 +1,117 @@
+---
+adr: 026
+status: accepted
+date: 2026-05-24
+decision: explain-mode-translation
+supersedes: —
+superseded_by: —
+phase: v3.x · employee-product-and-external-proof Phase 6
+type: forward-looking
+---
+
+# ADR-026 — Explain-mode translation — plain as a renderer, not a new pipeline
+
+## Status
+
+**Accepted** · 2026-05-24. Phase 6 design. Depends on the existing
+`explain-v1` envelope shape stabilized in `agent-memory` 3.0 and the
+workspace surface from [`ADR-025`](ADR-025-workspace-chrome.md).
+
+## Context
+
+Feedback A names the technical explain-trace as a non-technical-employee
+barrier. Today the right rail shows `trust_score: 0.74`,
+`promotion_history: [...]`, `contradictions: 0` — vocabulary that
+assumes the reader knows the memory model. For galabau, content-creator,
+and consultant roles, this is opaque.
+
+Two options surveyed:
+
+| Option | Pitch | Cost |
+|---|---|---|
+| **(a) Second MCP surface** | Add `memory_explain_plain` returning a pre-translated envelope. | New endpoint, new schema, drift risk between two surfaces, requires MCP version bump. |
+| **(b) Renderer over existing envelope** | Treat plain mode as a pure rendering function over the existing `explain-v1` envelope. Per-role glossary overrides labels. | Zero MCP change, zero data drift, zero schema bump. Renderer testable with fixtures. |
+
+## Decision
+
+Ship Phase 6 plain mode as **(b) — a pure renderer over the existing
+`explain-v1` envelope**.
+
+Concretely:
+
+- `renderExplain(envelope, { mode, glossary?, locale? })` is a pure
+  function in `packages/core/src/workspace/explain/`.
+- Two modes: `technical` (current surface, verbatim) and `plain`
+  (4 labelled paragraphs: where from, how confident, when reviewed,
+  what's contested).
+- 4-band confidence label (Very High / High / Medium / Low) with
+  default thresholds per [`docs/contracts/explain-modes.md`](../contracts/explain-modes.md);
+  thresholds overridable per role.
+- 3-band freshness label (Fresh / Aging / Stale) from `decay.applied_factor`.
+- Per-role `agents/roles/<role>/explain-glossary.yml` overrides
+  default labels and band thresholds. Glossary YAMLs are the
+  one carve-out from the `.md`-must-be-English rule for role-native
+  rendered strings.
+- `/why` quick command available to every role; resolves `mem://<id>`
+  markers in the last reply and calls `memory_explain` per id, then
+  renders in the active mode.
+
+## Why (b)
+
+- **Zero MCP drift.** One envelope, two views. No risk of plain
+  text saying something the engineer view contradicts.
+- **Testable.** Pure function over fixtures. Golden tests cover
+  high-trust, low-trust, contradicted, recently-promoted, deprecated.
+- **No version bump.** `agent-memory` MCP surface stays at the
+  current contract; consumers running older clients still see the
+  technical envelope unchanged.
+- **Glossary carve-out is bounded.** Only the `explain-glossary.yml`
+  per role holds runtime strings in role-native language; the
+  contract `.md`, the ADR, the renderer code stay English.
+
+## Why not (a)
+
+- A second MCP endpoint duplicates the envelope shape and creates
+  two surfaces that must stay in sync. Drift will land within one
+  release.
+- Schema bump on `agent-memory` cascades to every downstream package
+  consuming the MCP; Phase 6 is not the right time to force that.
+
+## Consequences
+
+**Positive**
+
+- Plain mode lands as a renderer change, no MCP version bump.
+- Per-role glossary opens the door for the recruit-session
+  participants (Phase 1) to localize the plain surface without a
+  code change.
+- Technical mode survives unchanged for engineering-lead role.
+
+**Negative**
+
+- Plain mode is downstream of envelope shape; an `explain-v2`
+  envelope (next major) requires updating the renderer too. Cost
+  is bounded — the renderer is one file.
+- Glossary localization can drift from English defaults if a role
+  ships a partial override. Mitigated by the renderer falling back
+  to defaults for missing keys.
+
+**Reversal cost** — low. Replacing (b) with (a) later if the
+renderer surface grows beyond pure rendering (e.g. needs a different
+data fetch) requires only adding the second MCP endpoint; existing
+glossary YAMLs translate forward.
+
+## Open questions (deferred)
+
+- Localization of the technical view (today: English only). Out of
+  scope for v0; deferred until ≥ 1 recruit-session participant
+  asks for it.
+- Audio / spoken-mode rendering of the plain envelope for the
+  consultant-on-the-road role. Defer to a future ADR.
+
+## Cross-references
+
+- Contract: [`docs/contracts/explain-modes.md`](../contracts/explain-modes.md).
+- Envelope: [`docs/contracts/agent-memory-contract.md`](../contracts/agent-memory-contract.md).
+- Workspace: [`ADR-025`](ADR-025-workspace-chrome.md), [`docs/contracts/daily-workspace.md`](../contracts/daily-workspace.md).
+- Roles: [`docs/contracts/role-experience.md`](../contracts/role-experience.md).

package/docs/decisions/ADR-027-changelog-machine-vs-manual.md

@@ -0,0 +1,129 @@
+---
+adr: 027
+status: accepted
+date: 2026-05-25
+decision: changelog-machine-vs-manual
+supersedes: —
+superseded_by: —
+phase: v3.x · changelog-era-auto-split Phase 4
+type: discovery-loop-closure
+review_date: 2027-05-25
+---
+
+# ADR-027 — CHANGELOG convention — confirm manual narrative + auto-split for 12 months
+
+## Status
+
+**Accepted** · 2026-05-25. Closes Phase 4 of
+[`road-to-changelog-era-auto-split.md`](../../agents/roadmaps/archive/road-to-changelog-era-auto-split.md).
+Time-boxed: review on 2027-05-25 or earlier if a trigger below fires.
+
+## Context
+
+The AI Council that produced the auto-split design surfaced one upstream
+question: **is the manual changelog convention itself the right primitive
+for a package that bills itself as an "Universal AI Agent OS"?** Phase 4
+investigates without committing to a rewrite — either confirm
+`docs/contracts/CHANGELOG-conventions.md` + the Tier 2/3 machinery stand
+for 12 months, or draft a successor roadmap.
+
+### Step 1 — Consumer touchpoint audit
+
+Every place a consumer reads the changelog and which fields they read:
+
+| # | Surface | What the consumer sees | Field weight |
+|---|---|---|---|
+| 1 | **GitHub Release notes** | `plan.changelog_body` rendered via `scripts/release.py:818` | narrative + bullets + tests-delta |
+| 2 | **npmjs.com package page** | auto-rendered `CHANGELOG.md` (top of file) | narrative paragraph dominates the fold |
+| 3 | **packagist.org package page** | same — auto-rendered `CHANGELOG.md` | same |
+| 4 | **`README.md` footer** | link only to `CHANGELOG.md` and `releases/latest` | navigation, no content |
+| 5 | **`CHANGELOG.md` direct** | full structured entries | full Keep-a-Changelog shape |
+| 6 | **`docs/archive/CHANGELOG-pre-*.md`** | historical eras behind the active-era pointer | follow-up reads only |
+| 7 | **`agents/settings/contexts/adr-artifact-engagement.md` § L100** | guidance to write a deprecation note in `CHANGELOG.md` | governance / authoring, not consumer |
+
+`docs/getting-started-by-role.md` — not in scope. No role-pack `FIRST_WIN.md` references the changelog.
+
+**Reader insight.** Surfaces 1–3 are the high-traffic consumer surfaces.
+Each renders the *top* of the changelog: the narrative paragraph + the
+first bullet group + the tests-delta. The narrative paragraph carries
+the framing every other layer (bullets, compare-link) loses.
+
+### Step 2 — Spike comparison against the audit
+
+Three shapes, measured against the 3.2.0 release (38 commits, 141 lines
+of narrative + bullets in the current convention):
+
+| Metric | Current (manual narrative + auto-split) | (a) `release-please` fully generated | (b) Hybrid (manual paragraph + generated bullets) |
+|---|---:|---:|---:|
+| **Token budget per release** | ~2.8k (141 lines × ~80 chars) | ~1.1k (38 commits × ~120 chars) | ~2.6k (same as current; bullets generated, paragraph hand-written) |
+| **Maintainer minutes per release** | 5–15 (write narrative; auto-split runs in `task release`) | 0 direct + ~30/month policing commit messages | 5–10 (paragraph only) |
+| **Information density per line** | high — narrative compresses 5–10 bullets of context | low — every infrastructure commit becomes a line | high — same as current |
+| **Parseability for downstream agents** | high — `### Features` / `### Fixes` / `### BREAKING` are semantic anchors | medium — same headings, but no narrative anchor to disambiguate scope churn | high |
+| **Hands-off failure mode** | era over-cap → auto-split fires | commit-message drift pollutes the log → no recovery without rewriting commits | narrative drift → degrades to release-please equivalent |
+
+The fully-generated shape **loses the narrative paragraph**, which is
+the field weight #1–3 surfaces lean on. The hybrid shape is what the
+current convention *already* allows — `release-please` is just the
+extreme end of the auto-spectrum; the convention sits at a defensible
+middle.
+
+The operational cost that prompted the question (era over-cap blocking
+the release PR) is solved by Tier 2 in the same roadmap. The discovery
+question therefore reduces to: **is the narrative paragraph worth
+~2.5k tokens per release?** Audit says yes — it is the field consumers
+read first and the field that differentiates the package from bot
+output.
+
+## Decision
+
+**Confirm `docs/contracts/CHANGELOG-conventions.md` + Tier 2/3
+machinery for 12 months.** No successor roadmap.
+
+The current convention:
+
+- Keeps the **hand-written narrative paragraph** as the load-bearing
+  framing for consumer surfaces (npm, packagist, GitHub Releases).
+- Lets `scripts/release.py` generate the **bullet list** under
+  Features / Fixes / Chores / Docs / BREAKING via the auto-split flow
+  plus the existing Keep-a-Changelog shape.
+- Lets the **drift gate** (`tests/test_changelog_eras.py`) catch
+  non-release edits that grow the active era past 250 lines.
+
+The "Universal AI Agent OS" framing **argues for**, not against, a
+human-curated changelog — agents that consume `CHANGELOG.md` as a
+ground-truth of "what changed" prefer structured, semantic, framed
+entries over a flat commit dump.
+
+## Consequences
+
+- `docs/contracts/CHANGELOG-conventions.md` stands as-is. The
+  Tier 3 Step 3 "Gate-vs-script contract" subsection is the canonical
+  reference for the gate / script split.
+- No new tooling lands as a Phase 4 follow-up.
+- Review on **2027-05-25** or earlier if any trigger fires:
+  1. The narrative paragraph stops being written for two consecutive
+     releases (signal: convention is breaking down naturally).
+  2. The active-era body grows past 250 lines from non-release edits
+     more than twice in a quarter (signal: humans are bypassing the
+     gate; auto-split is no longer the right primitive).
+  3. A downstream consumer (npm/packagist/GitHub Release renderer)
+     changes how it slices the top-of-file (signal: the field weight
+     assumption above is invalidated).
+  4. Council session re-opens the question with new evidence.
+
+## Alternatives considered
+
+| Option | Why rejected |
+|---|---|
+| **`release-please` fully generated** | Loses the narrative paragraph; surfaces 1–3 lose their highest-weight field. |
+| **Hybrid (manual paragraph + generated bullets, separate tool)** | Indistinguishable from current convention in output; adds a tool boundary without changing the artefact. |
+| **Drop the changelog entirely, point to GitHub Releases** | npm / packagist auto-render `CHANGELOG.md` from the repo; deleting it degrades surfaces 2–3 to a generic placeholder. |
+
+## References
+
+- [`docs/contracts/CHANGELOG-conventions.md`](../contracts/CHANGELOG-conventions.md) — convention being confirmed.
+- [`agents/roadmaps/archive/road-to-changelog-era-auto-split.md`](../../agents/roadmaps/archive/road-to-changelog-era-auto-split.md) — closes Phase 4.
+- [`agents/runtime/council/responses/changelog-era-split-2026-05-25.json`](../../agents/runtime/council/responses/changelog-era-split-2026-05-25.json) — the originating council synthesis.
+- `scripts/_lib/changelog_eras.py` — shared cap + splitter (Tier 2 output).
+- `scripts/release.py:818` — `plan.changelog_body` → GitHub Release notes wire.
+- `tests/test_changelog_eras.py`, `tests/test_changelog_split.py` — gate + splitter coverage.