@event4u/agent-config 3.1.1 → 3.3.0

package/docs/contracts/local-knowledge-ingestion.md

@@ -0,0 +1,96 @@
+---
+stability: beta
+keep-beta-until: 2026-08-24
+---
+
+# Local knowledge ingestion contract
+
+**Purpose.** Freeze the input shape, bounds, storage target, and redaction defaults for the single-user, local-only knowledge surface (`/knowledge:ingest`, `/knowledge:list`, `/knowledge:forget`) **before** any implementation lands. Closes the "Copy/Paste AI" complaint from feedback A without touching OAuth, multi-tenancy, or Hard-Floor connector territory.
+
+Last refreshed: 2026-05-24. Phase 2 of the employee-product workstream.
+
+## What this doc is **not**
+
+- Not the connector contract for GitHub / Jira / Confluence — those sit behind OAuth and stay cancelled in `road-to-internal-ai-os-deployment.md` Phase 5.
+- Not a remote-fetch surface — every input must resolve to a local path on the same machine the agent runs on.
+- Not a memory replacement — ingested content lives **inside** the existing memory layer under a dedicated namespace, never as a parallel store.
+
+## Input shapes
+
+The ingestion command accepts exactly these input shapes; anything else is rejected at the input validator with a structured error and no partial write.
+
+| Input | Resolution rule | Example |
+|---|---|---|
+| `file://<absolute-path>` | Single file. Path must be absolute and inside the user's home or the project root (no `/etc`, `/var`, `~root/`, `..` escapes). | `file:///Users/maintainer/clients/acme/brief.pdf` |
+| Local folder path | Recursive walk; symlinks not followed; hidden directories skipped (`.git`, `.venv`, `node_modules`). | `/Users/maintainer/clients/acme/` |
+| `.zip` archive | Unpacked to a temp dir inside `$TMPDIR/agent-knowledge-<uuid>`, walked, then the temp dir is removed before the command returns. | `/Users/maintainer/clients/acme.zip` |
+
+**Remote URLs are rejected** — `http://`, `https://`, `s3://`, `gs://`, `azure://`. The error message names `/knowledge:ingest` as local-only by design.
+
+## Supported MIME types
+
+The ingestion module routes each file through the existing `markitdown` adapter when the MIME type is not native markdown.
+
+| MIME | Adapter | Notes |
+|---|---|---|
+| `text/markdown` | passthrough | UTF-8 only; other encodings rejected |
+| `text/plain` | passthrough | UTF-8 only |
+| `application/pdf` | `markitdown` | OCR if scanned; OCR confidence < 0.7 surfaces as `low_confidence` tag |
+| `application/vnd.openxmlformats-officedocument.wordprocessingml.document` (`.docx`) | `markitdown` | |
+| `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` (`.xlsx`) | `markitdown` | One sheet per chunk |
+| `application/epub+zip` (`.epub`) | `markitdown` | Chapter per chunk |
+| `image/png`, `image/jpeg` | `markitdown` OCR | OCR confidence stored same as PDF |
+
+Unsupported MIME → file skipped with a counted `skipped: <mime>` entry in the command summary. No partial-content writes.
+
+## Bounds (non-negotiable, enforced at command entry)
+
+| Bound | Limit | Rationale |
+|---|---|---|
+| Total ingest size | ≤ 100 MB per `/knowledge:ingest` call | Keeps a single ingestion bounded; multi-ingest is fine |
+| Document count | ≤ 1000 per call | Avoids unbounded walks on a misconfigured folder |
+| Per-file size | ≤ 20 MB | One outlier file cannot blow the budget |
+| Total memory footprint | ≤ 500 MB across all ingests | LRU eviction at the namespace level when crossed |
+| Path traversal depth | ≤ 10 directories | Cheap guard against pathological folder trees |
+
+Crossing any bound is a **hard reject** at command entry — not a warning. The command returns a structured error with the bound name and the observed value.
+
+## Storage target
+
+Ingested content lives inside the existing memory namespace as a dedicated prefix:
+
+```
+memory/
+└── knowledge/
+    ├── <ingest-id>/         # uuid7 per ingest call
+    │   ├── manifest.json    # source path, count, timestamps, redactions
+    │   └── chunks/<n>.md    # one markdown chunk per logical unit
+```
+
+- `<ingest-id>` is a uuid7 so timestamps are recoverable from the id; never user-controlled.
+- `manifest.json` is the audit row — used by `/knowledge:list` and by the LRU eviction loop.
+- Chunks are markdown only after the adapter has run; the original binary is never stored.
+
+The MCP tool `memory_retrieve` (existing surface in `agent-memory`) **must** tag retrieved entries from this namespace with `source: knowledge`. The host model decides what to do with user-supplied vs maintainer-curated entries; this contract only requires the tag.
+
+## Redaction defaults
+
+Redaction runs **before** the chunk write, never after.
+
+- **PII allowlist** — only the following identifier classes survive the ingest: project names, document titles, headings, technical terminology. Everything else that pattern-matches a PII regex set (e-mail addresses, phone numbers, IBAN, credit-card-shaped strings, SSN-shaped strings) is replaced with class placeholders (`[EMAIL]`, `[PHONE]`, `[IBAN]`, `[CC]`, `[SSN]`).
+- **Secrets never stored** — anything matching the existing `gitleaks` ruleset (or equivalent) is replaced with `[SECRET]` and the manifest's `secrets_redacted` counter is incremented. A chunk with ≥ 1 secret redaction is tagged `contains_redactions: true`.
+- **The user can opt out per-call** with `--no-redact`, but the manifest captures the flag so the audit trail names exactly which ingests bypassed redaction. The default is always redact.
+
+## Eviction policy
+
+LRU at the namespace level. When the 500 MB cap is crossed, oldest ingests (by `manifest.last_touched`) are dropped whole — never per-chunk. `last_touched` updates on every `memory_retrieve` hit against an entry in the namespace. The user can pin an ingest with `/knowledge:list --pin <ingest-id>`; pinned ingests are never evicted.
+
+## Command surface (deferred to impl PR)
+
+`/knowledge:ingest <path>`, `/knowledge:list`, `/knowledge:forget <prefix>` are defined elsewhere — this contract pins their **inputs, bounds, storage, and redaction**. The Python module that implements the file walk + MIME routing + chunk writing lives at `packages/core/installer/python/knowledge_ingest.py`, ≤ 600 LOC (bumped from the pre-impl ≤ 400 budget once five PII classes, five secret patterns, LRU eviction, manifest persistence, pin/unpin and the multi-verb CLI were all in one file — splitting would have added an import seam without changing the surface), per Phase 2 Step 2.
+
+## Open questions (Phase 2 council pass, optional)
+
+- Chunk size — fixed (e.g. 2 KB markdown) vs adaptive per document? Default: 2 KB until the recruit sessions or eval surface a reason to change.
+- OCR confidence threshold — 0.7 is a guess; first three sessions inform the right number.
+- Pinning UX — `--pin` flag vs a separate `/knowledge:pin` command. Default in this contract: a flag on `/knowledge:list`.

package/docs/contracts/mcp-beta-criteria.md

@@ -7,7 +7,7 @@ mcp_scope: lite
 
 > **Status:** Active · governs the `experimental → beta` promotion for
 > the MCP surface (`scripts/mcp_server/` local stdio kernel + the
-> hosted `workers/mcp/` bridge). Owned by Phase 3 of the
+> hosted `internal/workers/mcp/` bridge). Owned by Phase 3 of the
 > `road-to-surface-discipline` roadmap (see `agents/roadmaps/`).
 > Companion contract:
 > [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) (local) ·

package/docs/contracts/mcp-cloud-scope.md

@@ -5,7 +5,7 @@ mcp_scope: lite
 
 # MCP Server — Cloud Scope (A0-cloud Hard Contract)
 
-> **Status:** Active · covers `workers/mcp/` (TypeScript Cloudflare
+> **Status:** Active · covers `internal/workers/mcp/` (TypeScript Cloudflare
 > Worker bridge), MVP-1 surface. Extends — does **not** supersede —
 > [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md), which retains
 > exclusive ownership of `scripts/mcp_server/` (local stdio).
@@ -15,7 +15,7 @@ mcp_scope: lite
 ## Purpose
 
 Locks the **execution-safety boundary** for the hosted MCP Worker. Any
-code under `workers/mcp/` must satisfy this contract verbatim. The
+code under `internal/workers/mcp/` must satisfy this contract verbatim. The
 local stdio kernel and the hosted Worker are two distinct surfaces; a
 deviation in one is **not** authorized by a precedent in the other.
 
@@ -46,7 +46,7 @@ prose-only.
 - **What it never does:** execute Python scripts, shell out, spawn
   runtimes, touch consumer FS, write to R2, mutate consumer state,
   call upstream LLM APIs, or read `.agent-src.uncompressed/`.
-- **Owner code path:** `workers/mcp/` (TypeScript, Cloudflare Worker).
+- **Owner code path:** `internal/workers/mcp/` (TypeScript, Cloudflare Worker).
   This contract is the normative spec.
 - **Auth model:** `public` (default) or `bearer-auth` (operator opt-in)
   per `## Auth surface`. HMAC and CF Access are declared but deferred.
@@ -194,7 +194,7 @@ runtime mode switch.
   returns HTTP `401` with a JSON-RPC error envelope (code `-32001`,
   message `"Unauthorized"`) and the RFC 6750
   `WWW-Authenticate: Bearer realm="agent-config-mcp"` header.
-  Implementation: `workers/mcp/src/index.ts` § auth gate (the
+  Implementation: `internal/workers/mcp/src/index.ts` § auth gate (the
   `if (requiredToken) { … }` block).
 - **Liveness carve-out:** the `GET /` liveness probe is
   unauthenticated by design — health checks and `curl` smoke tests

package/docs/contracts/mcp-registry-manifest.schema.json

@@ -52,7 +52,7 @@
                 "tools_count": {
                     "type": "integer",
                     "minimum": 0,
-                    "description": "Sourced from workers/mcp/content.json#/tool_catalog/tools. Hard-sourced — no fallback. R3 (discovery roadmap) is a hard prerequisite per the AI-Council external review."
+                    "description": "Sourced from internal/workers/mcp/content.json#/tool_catalog/tools. Hard-sourced — no fallback. R3 (discovery roadmap) is a hard prerequisite per the AI-Council external review."
                 },
                 "install_hint_stdio": { "type": "string", "minLength": 1 }
             }

package/docs/contracts/mcp-tool-inventory.md

@@ -47,7 +47,7 @@ keep-beta-until: 2026-08-14
 ## Glossary
 
 - **Side-effect** — `ro` (read-only) · `fs-write` (filesystem write) · `shell` (spawns processes).
-- **Transports** — `stdio` (`scripts/mcp_server/`) · `worker` (`workers/mcp/`). A tool may live on both.
+- **Transports** — `stdio` (`scripts/mcp_server/`) · `worker` (`internal/workers/mcp/`). A tool may live on both.
 - **Stub** — catalog-listed for discovery; returns the `not_implemented` envelope from
   [`mcp-tool-stub-envelope.md`](mcp-tool-stub-envelope.md) until promoted.
 

package/docs/contracts/mcp-tool-stub-envelope.md

@@ -20,7 +20,7 @@ a 500.
 ## Source of truth
 
 `scripts/mcp_server/consumer_tool_catalog.json` (schema_version 1).
-Both the stdio server and the Cloud Worker bundle (`workers/mcp/`,
+Both the stdio server and the Cloud Worker bundle (`internal/workers/mcp/`,
 packed by `scripts/pack_mcp_content.py`) read from this file. The
 manifest returned by `tools/list` is byte-identical apart from
 per-tool `implemented_on` metadata.

package/docs/contracts/measurement-baseline.md

@@ -24,7 +24,7 @@ Four axes, all numeric, all reproducible from the same input:
 
 Schemas: [`benchmark-report-schema.md`](benchmark-report-schema.md) ·
 [`benchmark-corpus-spec.md`](benchmark-corpus-spec.md). Reports land at
-`bench/reports/<utc-stamp>-<corpus>[-projection].{json,md}` —
+`internal/bench/reports/<utc-stamp>-<corpus>[-projection].{json,md}` —
 timestamped, never overwritten, content-addressed by run.
 
 ## Corpora — frozen for the soak window
@@ -67,10 +67,10 @@ NO ANECDOTE, NO INDIVIDUAL REPORT, NO ROADMAP-SIDE OVERRIDE.
 [`scripts/bench_baseline_ready.py`](../../scripts/bench_baseline_ready.py)
 returns exit 0 iff both:
 
-1. **Wall-clock soak:** `today − bench/baseline-start.txt ≥ --min-days` (default 60)
-2. **Report density:** `bench/reports/*-<corpus>.json` count ≥ `--min-reports` (default 30)
+1. **Wall-clock soak:** `today − internal/bench/baseline-start.txt ≥ --min-days` (default 60)
+2. **Report density:** `internal/bench/reports/*-<corpus>.json` count ≥ `--min-reports` (default 30)
 
-Soak start anchored at [`bench/baseline-start.txt`](../../bench/baseline-start.txt)
+Soak start anchored at [`internal/bench/baseline-start.txt`](../../bench/baseline-start.txt)
 = **2026-05-16**. Earliest possible flip: **2026-07-15**, contingent
 on the 30-report floor.
 
@@ -86,11 +86,11 @@ On baseline closure, the step-4 closeout writes the numeric verdict to
 [`docs/parity/bench.json`](../parity/bench.json) — frozen snapshot with
 the 30+ reports averaged, drift verdict, and the compression-default
 decision per the kill-criterion table. That file is the artefact every
-P2 roadmap reads — not the live `bench/reports/` directory.
+P2 roadmap reads — not the live `internal/bench/reports/` directory.
 
 ## Carve-outs
 
-- **Pricing freshness:** [`bench/pricing.yaml`](../../bench/pricing.yaml) rows must carry `sourced_on: YYYY-MM-DD`. Stale prices = stale numbers = no trust (ruflo "measured-vs-claimed" pattern).
+- **Pricing freshness:** [`internal/bench/pricing.yaml`](../../bench/pricing.yaml) rows must carry `sourced_on: YYYY-MM-DD`. Stale prices = stale numbers = no trust (ruflo "measured-vs-claimed" pattern).
 - **Subjective grading excluded:** quality scoring is mechanical via `quality_assertion`. No vibes.
 - **Cursor / Cline / Windsurf:** rules-only surfaces, no SKILL.md projection. `bench:projection` reports them as `not_applicable` — the gap is acknowledged, not silently dropped.
 

package/docs/contracts/role-experience.md

@@ -0,0 +1,121 @@
+---
+stability: beta
+keep-beta-until: 2026-08-24
+---
+
+# Role-experience contract
+
+**Purpose.** Freeze the on-disk shape of a `role-experience` — the artefact that turns a non-developer persona (galabau owner, content creator, consultant, …) into a first-class entry point with three first tasks, a named prompt library, and a curated skill shortlist. Pins the interface **before** the launcher in Phase 4 reads it, so the launcher and the role authors can move independently.
+
+Last refreshed: 2026-05-24. Phase 3 of the employee-product workstream.
+
+## What a role experience is
+
+A folder at `agents/roles/<role>/` that contains:
+
+- One **identity index** (`index.md`) — one-paragraph persona, three concrete first tasks, recommended pack list, install-path hint.
+- A **prompt library** (`prompts/<name>.md`) — 5–10 named prompts, each a single markdown file with structured frontmatter and a parameterised body the launcher can fill.
+- A **skill shortlist** (`skills.yml`) — the existing skills the launcher should surface for this role, in priority order. Cites existing skills only; never duplicates them.
+
+A role experience is **not**:
+
+- A new skill — the shortlist references existing skills under `packages/<pack>/.agent-src.uncompressed/skills/`. The role experience curates; it does not implement.
+- A documentation page — `docs/getting-started-by-role.md` is the prose surface and links **to** the role experience, never duplicates it.
+- A persona file under `personas/` — personas are review voices the AI Council uses; role experiences are end-user entry points.
+
+## Folder shape
+
+```
+agents/roles/<role>/
+├── index.md            # identity + three first tasks + recommended packs
+├── skills.yml          # skill shortlist (priority-ordered)
+└── prompts/
+    ├── <name-1>.md
+    ├── <name-2>.md
+    └── …               # 5–10 prompts
+```
+
+`<role>` is a kebab-case identifier; it doubles as the launcher key and the URL slug. Reserved words: `default`, `_template`, `_archive`.
+
+## `index.md` frontmatter (required)
+
+```yaml
+---
+role: <kebab-case-id>
+display_name: "Galabau owner"
+tagline: "One-sentence description visible in the launcher rail."
+recommended_packs: [core, founder-strategy]   # cites existing packs only
+install_path_hint: "MCP recommended (Claude Desktop) · CLI when …"
+recruit_session_ref: "agents/recruit-sessions/01-galabau-owner.md"  # nullable until session lands
+status: stable | beta | draft
+---
+```
+
+The body of `index.md` then lists, in this order:
+
+1. **Persona paragraph** (≤ 80 words) — who this role is for, in the role's own language.
+2. **Three first tasks** — each a single sentence + the prompt name (`prompts/<name>.md`) that bootstraps it.
+3. **Recommended pack list** — referenced from frontmatter, expanded with one-line rationale per pack.
+
+## Prompt frontmatter (required)
+
+Each `prompts/<name>.md` carries:
+
+```yaml
+---
+name: <kebab-case-id>            # unique within the role's prompts/ folder
+intent: "One sentence: what the user gets out of this prompt."
+inputs:
+  - name: customer_brief
+    required: true
+    shape: "free-text paragraph"
+  - name: tone
+    required: false
+    shape: "one of [neutral, warm, urgent]"
+output_shape: "Markdown — H2 sections, ≤ 600 words, structured offer."
+skill_hint: refine-prompt        # which skill the host should foreground; cites existing skill
+---
+```
+
+The body is the parameterised prompt itself, with `{{input_name}}` placeholders the launcher fills before sending to the host model. Bodies stay ≤ 200 lines; prompts longer than that get split.
+
+## `skills.yml` shape
+
+```yaml
+# Priority-ordered. The launcher surfaces the first 5 in its default view; the rest go behind "more".
+skills:
+  - id: refine-prompt
+    why: "Tightens fuzzy customer briefs before any drafting."
+  - id: voice-and-tone-design
+    why: "Locks the role's voice so emails read consistent across customers."
+  - id: doc-coauthoring
+    why: "Section-by-section drafting flow for longer offers."
+```
+
+Every `id` must resolve to an existing skill under `packages/<pack>/.agent-src.uncompressed/skills/<id>/SKILL.md` — verified by the lint pass in Phase 3 Step 6.
+
+## Versioning + status
+
+- `status: draft` — scaffold only, no recruit-session evidence yet. Launcher hides drafts in the default view.
+- `status: beta` — scaffold + at least one recruit session backs the first-task choice. Launcher surfaces with a `beta` badge.
+- `status: stable` — at least two recruit sessions concurred on the role's first tasks and the friction-inventory landed at ≤ 3 P0 items.
+
+Status promotion is a maintainer decision, captured in the `recruit_session_ref` frontmatter trail. Demotion (stable → beta) happens when a follow-up recruit session contradicts the existing first-task choice.
+
+## Lint pass (deferred to Phase 3 Step 6)
+
+The lint pass (`task lint-role-experiences`, wired into `task ci`) asserts:
+
+1. Every `agents/roles/<role>/index.md` has all required frontmatter keys + at least 3 first tasks.
+2. Every `prompts/<name>.md` has the four required frontmatter keys (`name`, `intent`, `inputs`, `output_shape`) plus `skill_hint`.
+3. Every `skills.yml#skills[].id` resolves to an existing skill.
+4. Every `recommended_packs[]` entry resolves to an existing pack manifest.
+5. Status promotion never happens without a non-null `recruit_session_ref`.
+
+Lint pass code lives at `scripts/lint_role_experiences.py`, ≤ 200 LOC. Until the lint pass ships, the scaffolds in Phase 3 Steps 2–4 are hand-validated against this contract.
+
+## Open questions (Phase 3 optional council pass)
+
+- Per-role default model — should `index.md` carry a `default_model` frontmatter key the launcher honours, or stay at the host's global default? Default in this contract: stay at host default; per-role override is a future ADR.
+- Prompt input typing — should `inputs[].shape` be free-text or constrained to a small enum (`text`, `enum`, `file-path`, `url`)? Default: free-text; constraint enum is a future tightening.
+- Multi-language prompt bodies — German vs English by role? Default: prompt bodies follow the language policy of the package (English); the host translates at runtime per `language-and-tone`.

package/docs/contracts/workspace-documents.md

@@ -0,0 +1,140 @@
+# Workspace Documents Contract
+
+> **Status** · v0 / design · 2026-05-24. Phase 5 of the
+> employee-product workstream.
+> Builds on the [`daily-workspace`](daily-workspace.md) surface and
+> the host-agent protocol from
+> [`ADR-023`](../decisions/ADR-023-host-agent-protocol.md). Documents
+> are the **output shape** of selected launcher prompts.
+
+## When a launcher prompt produces a document
+
+A launcher prompt is **document-shaped** when its frontmatter sets
+`output_shape: document`. Otherwise the prompt is **chat-shaped**
+(default) — the host reply lands in the session JSONL log only.
+
+```yaml
+# agents/roles/galabau/prompts/angebot-erstellen.md
+---
+title: Angebot erstellen
+output_shape: document
+document_type: offer
+slug: from_title
+---
+```
+
+Recognised `document_type` values (v0): `offer`, `mail-draft`,
+`memo`, `brief`, `video-script`. Unknown types are rejected at
+launcher-load time with a banner; the prompt falls back to
+chat-shaped.
+
+## Storage layout
+
+```
+~/.event4u/agent-config/workspace/documents/
+├── offer/
+│   ├── kundeX-angebot-2026-05-24.md          ← body
+│   └── kundeX-angebot-2026-05-24.history.jsonl ← per-save revision log
+├── mail-draft/
+├── memo/
+├── brief/
+└── video-script/
+```
+
+Slug rules: kebab-case ASCII; deduped by appending `-2`, `-3`, …;
+filename never contains PII. Slug default = `slugify(title) + "-" + iso-date`.
+
+## Document frontmatter
+
+```markdown
+---
+type: offer
+title: Angebot Kunde X
+created_at: 2026-05-24T12:08:00Z
+last_edited_at: 2026-05-24T12:14:00Z
+source_prompt: agents/roles/galabau/prompts/angebot-erstellen.md
+source_session: 20260524T120800Z-a1b2c3d4
+role: galabau
+tags: [kunde-x, gartenbau, 2026-q2]
+schema: workspace-document/v0
+---
+
+[document body — Markdown, host-generated, user-edited]
+```
+
+`source_prompt` + `source_session` form the provenance pair: every
+document points back to the prompt that produced it and the session
+that ran it. The session JSONL stays in the session store; only the
+**reference** lives here.
+
+## Revision log
+
+Path: `<slug>.history.jsonl`. Append-only. One entry per save.
+
+```json
+{
+  "ts": "2026-05-24T12:14:00Z",
+  "actor": "user",
+  "kind": "save",
+  "delta": { "added": 12, "removed": 4 },
+  "body_sha256": "ab12…"
+}
+```
+
+Actor `host` marks the initial-creation save (from the host agent's
+reply). Actor `user` marks every subsequent edit. No body in the
+log — only the SHA. The body lives in the `.md` file; rollback walks
+the SHA chain and reconstructs from a tracked-base + delta is
+**deferred** to v1 (v0 keeps only the latest body).
+
+## Export
+
+| Format | How | Notes |
+|---|---|---|
+| Markdown | identity copy of `<slug>.md` | always available |
+| PDF | `markitdown` reverse path (preferred), `pandoc` fallback | requires `pandoc` on PATH for fallback |
+| DOCX | `pandoc <slug>.md -o <slug>.docx` | requires `pandoc` on PATH |
+
+Export target: user picks a folder via the OS picker. No autosave to
+cloud, no upload, no remote backend. Export failures surface as a
+banner; partial files are not left behind.
+
+## Workspace integration
+
+- Phase 4 right-rail "Recent documents" list shows ≤ 20 most-recent
+  entries scoped to the current role; click → opens the body in the
+  user's default Markdown editor.
+- The workspace **centre pane** for a document-shaped session shows
+  the document body live (read-only) plus a "Edit" button that
+  hands off to the OS default `.md` editor.
+- Closing the workspace does not lock the document file — it stays
+  user-editable.
+
+## Failure modes
+
+- Host CLI returns a non-document reply for a document-shaped prompt
+  → workspace stores the raw text under `<slug>.md` with a
+  `quarantine: true` frontmatter flag; UI shows a one-line banner.
+- Disk full → red banner, no silent body loss.
+- Frontmatter parse failure → revision log still appends a
+  `kind: save_failed` record; user's working file is preserved
+  alongside as `<slug>.broken.md`.
+
+## Coverage requirements (Phase 5 Step 6)
+
+- Golden tests on the export rendering: 3 fixture documents × 3
+  export formats (Markdown / PDF / DOCX). Fixtures under
+  `tests/golden/workspace-documents/`.
+- Schema-validation tests on the frontmatter contract using
+  `tests/fixtures/workspace-documents/valid/` and `invalid/`.
+- ≥ 80 % branch on save + history-append paths.
+
+## Cross-references
+
+- [`daily-workspace`](daily-workspace.md) — workspace shell that
+  hosts the document view.
+- [`host-agent-protocol`](host-agent-protocol.md) — how the document
+  body is produced.
+- [`local-knowledge-ingestion`](local-knowledge-ingestion.md) —
+  sources cited inside documents.
+- ADRs: [`023`](../decisions/ADR-023-host-agent-protocol.md), [`024`](../decisions/ADR-024-workspace-v0-feature-floor.md), [`025`](../decisions/ADR-025-workspace-chrome.md).

package/docs/decisions/ADR-022-daily-workspace-decomposition.md

@@ -0,0 +1,140 @@
+---
+adr: 022
+status: accepted
+date: 2026-05-24
+decision: daily-workspace-decomposition
+supersedes: —
+superseded_by: —
+phase: v3.x · employee-product-and-external-proof Phase 4
+type: forward-looking
+---
+
+# ADR-022 — Daily workspace — decomposition
+
+## Status
+
+**Accepted** · 2026-05-24. Phase 4 Step 1 of
+[`road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/road-to-employee-product-and-external-proof.md).
+Records the council's verdict on the original "workspace shape"
+question — that the question was malformed — and replaces a single
+chrome decision with three sequenced sub-decisions.
+
+The numeric reservation note in
+[`ADR-021`](ADR-021-deployment-shape.md) (ADRs 022–025 held for the
+internal-AI-OS-deployment roadmap) is retired: that roadmap is
+archived ([`agents/roadmaps/archive/road-to-internal-ai-os-deployment.md`](../../agents/roadmaps/archive/road-to-internal-ai-os-deployment.md))
+and the active strategy after release `3.1.1` is the
+employee-product / external-proof roadmap. ADR-022 claims the
+number under the new strategy.
+
+Companion artefacts:
+
+- Roadmap: [`agents/roadmaps/road-to-employee-product-and-external-proof.md`](../../agents/roadmaps/road-to-employee-product-and-external-proof.md)
+- Council question: [`agents/decisions/open-questions/daily-workspace-shape.md`](../../agents/decisions/open-questions/daily-workspace-shape.md)
+- Council verdict: `agents/runtime/council/responses/daily-workspace-shape.json` (gitignored)
+- Predecessor ADRs: [`ADR-014`](ADR-014-gui-framework-choice.md) (installer chrome), [`ADR-016`](ADR-016-installer-architecture.md) (installer architecture), [`ADR-020`](ADR-020-global-only-consumer-scope.md) (consumer scope).
+
+## Context
+
+Phase 4 of the post-`3.1.1` roadmap proposes a persistent daily
+workspace — left rail (role + task launcher), centre pane (active
+conversation with the host agent), right rail (knowledge sources +
+explain-trace) — as the missing daily-use surface for non-developer
+roles (galabau owner, content creator, consultant).
+
+The original Step 1 framed the decision as a four-way chrome pick:
+extend the GUI installer · separate Electron/Tauri app · browser tab
+· TUI-first. The council was asked to choose one.
+
+## What the council said
+
+Both council members (claude-sonnet-4-5, gpt-4o) **rejected the
+question as malformed** after a two-round debate. The convergent
+verdict, in their own words:
+
+> *"The ADR masquerades as a UI choice when it is actually three
+> entangled, unsequenced decisions: (1) the protocol boundary to
+> host agents, (2) the v0 feature scope that validates 'non-developers
+> prefer this', (3) the chrome that wraps that scope."*
+> — Anthropic
+
+> *"Without a stable, documented protocol between the workspace and
+> host agents, the ADR's proposition lacks substance and could be
+> shelved until a reliable, documented, and tested protocol is
+> defined."* — OpenAI
+
+The load-bearing critique is that the workspace contract requires
+two capabilities the host agents (Claude Code, Augment, Cursor,
+Cline, Windsurf) have not been confirmed to expose:
+
+1. A stable RPC / IPC surface for **launching a conversation with a
+   pre-filled prompt + pre-selected skill** (not just CLI flags that
+   drift per Hyrum's Law).
+2. Structured **explain-trace emission** (not "parse stdout and hope").
+
+Until both are proven for at least one host agent, no chrome option
+can be implemented — each inherits the same fatal coupling risk.
+
+## Decision
+
+Split Phase 4 Step 1 into three sequential sub-decisions, each its
+own ADR:
+
+1. **ADR-023 — Host-agent protocol contract** *(blocking)*. Inventory
+   the surface each named host agent exposes today, name the
+   fallback for missing surfaces, write `docs/contracts/host-agent-protocol.md`.
+   Status today: **drafted, not started**.
+2. **ADR-024 — Workspace v0 feature floor** *(depends on ADR-023)*.
+   Define the minimum viable shell that recruit-session participants
+   can evaluate. Pare back from "left rail + centre pane + right rail"
+   to whatever the protocol from ADR-023 can actually drive end-to-end.
+3. **ADR-025 — Workspace chrome** *(depends on ADR-024)*. The original
+   four-way pick (installer-extension · Electron/Tauri · browser tab ·
+   TUI), narrowed by what ADR-024 needs and what ADR-023 makes
+   feasible.
+
+The roadmap is updated accordingly: Phase 4 grows two new gating
+steps (ADR-023 + ADR-024) ahead of the chrome decision. The
+"≤ 6 weeks for one engineer" budget assumption from the original
+roadmap is preserved as a working figure — both council members
+flagged it as ambitious. ADR-024 will tighten it.
+
+## Consequences
+
+**Positive**
+
+- The blocking risk (host-agent protocol feasibility) is surfaced
+  as its own ADR with its own go/no-go gate, not buried under a
+  chrome debate.
+- Phase 4 cannot accidentally ship a chrome built on an unproven
+  integration substrate.
+- Recruit sessions (Phase 1) get a clearer signal of *what* to
+  validate: "does the v0 feature floor solve the daily-use gap?"
+  rather than "do you prefer this UI?"
+
+**Negative**
+
+- Phase 4 ships two additional ADRs before any code lands. Adds
+  governance overhead; the autonomous-execution rule narrows the
+  ask-tax but doesn't remove it.
+- The chrome decision (ADR-025) is deferred at least one council
+  round behind ADR-023 + ADR-024.
+
+**Reversal cost** — low. If ADR-023 proves the protocol is trivially
+stable, ADR-024 can collapse to a one-line "we re-adopt the
+original v1 scope" decision and ADR-025 proceeds against the
+original four-way pick.
+
+## Open questions (next-ADR-deferred)
+
+- Whether the host-agent protocol investigation should be
+  council-gated again or treated as a research artefact (ADR-023
+  will say).
+- Whether "host agent" remains plural or narrows to one supported
+  host for v0 (ADR-024 will say).
+
+## Cross-references
+
+- Council question file: [`agents/decisions/open-questions/daily-workspace-shape.md`](../../agents/decisions/open-questions/daily-workspace-shape.md)
+- Role identity scaffolds (Phase 3 output): [`agents/roles/`](../../agents/roles/)
+- Knowledge-ingestion contract (Phase 2 input): [`docs/contracts/local-knowledge-ingestion.md`](../contracts/local-knowledge-ingestion.md)