@event4u/agent-config 9.8.0 → 9.10.0

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

@@ -1,129 +0,0 @@
----
-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

@@ -1,126 +0,0 @@
----
-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/archive/road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/archive/road-to-employee-product-and-external-proof.md) Phase 4.

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

@@ -1,119 +0,0 @@
----
-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

@@ -1,117 +0,0 @@
----
-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: [`internal/schemas/retrieval-v1.schema.json`](../../internal/schemas/retrieval-v1.schema.json).
-- 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

@@ -1,129 +0,0 @@
----
-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 condenses 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. <!-- council-ref-allowed: ADR decision trace -->
-- `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.