@event4u/agent-config 9.8.0 → 9.10.0

package/docs/contracts/value-report-schema.md

@@ -1,168 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-28
----
-
-# Value Report Schema (`value-v1`)
-
-Parser-visible contract for the JSON report emitted by
-[`scripts/_lib/value_report.py`](../../src/scripts/_lib/value_report.py)
-and consumed by [`scripts/render_value_md.py`](../../src/scripts/render_value_md.py).
-Sibling of [`benchmark-report-schema.md`](benchmark-report-schema.md);
-companion to [`value-dashboard-spec.md`](value-dashboard-spec.md) which
-owns the semantics this contract types.
-
-## File layout
-
-```
-internal/bench/
-├── pricing.yaml                         # per-1M model rates + sourced_on dates
-└── reports/
-    └── value/
-        ├── 2026-05-28T10-30-00Z.json    # machine-readable value-v1 report
-        ├── 2026-05-28T10-30-00Z.md      # optional human dump (informational)
-        └── latest.json                  # symlink or copy of newest report
-```
-
-Filename format: `<UTC ISO-8601 with `:` → `-`>.{json,md}`. Sortable
-lexicographically.
-
-## JSON schema (v1)
-
-```yaml
-schema_version: 1                   # int — bump on a breaking change
-schema_id: value-v1                 # string literal
-generated_at: <ISO-8601 UTC>
-reference_scale:
-  requests: 1000                    # int — N requests being priced
-  avg_input_tokens: 8000            # int — assumed input tokens per request
-  avg_output_tokens: 600            # int — assumed output tokens per request
-  model_tier: sonnet                # haiku | sonnet | opus
-  pricing_sourced_on: <ISO date>    # from internal/bench/pricing.yaml
-baseline:
-  label: "Ohne Paket / Without package"
-  input_tokens_per_request: <int>   # the 0-point of the ladder
-cost_ladder:
-  - id: load
-    label: "<German + English>"
-    what_it_does: "<≤ 80 char phrase>"
-    token_delta: <signed int>       # per-request input token delta
-    eur_delta: <float>              # priced at reference_scale
-    cumulative_pct: <signed float>  # % of baseline.input_tokens_per_request
-    confidence: measured | estimated | vendor-claim | pending | available
-    source_report: <relative path>  # raw report this was derived from
-    footnote: "<optional caveat>"   # e.g. "Thin-Root files excluded"
-  - id: thin
-    ...                             # the thin-projection lever; ships behind
-    ...                             # the lean_projection.mode kill-switch
-    ...                             # (default eager-all) → confidence: available
-  - id: condense
-    ...
-  - id: rtk
-    ...
-  - id: terse
-    ...
-behaviour:
-  - id: selection
-    label: "<German + English>"
-    what_this_means: "<one line caption>"
-    with: <value>                   # metric-specific
-    without: <value>
-    delta: <signed value>           # with - without
-    unit: pct | count | ratio | seconds
-    mode: live | dry-run
-    source_report: <relative path>
-  - id: destructive-stops
-    ...
-  - id: ask-vs-act
-    ...
-  - id: completion
-    ...
-totals:
-  cumulative_token_delta: <signed int>   # sum of cost_ladder token_deltas
-  cumulative_eur_delta: <float>          # priced at reference_scale
-  cumulative_pct: <signed float>         # net % of baseline
-  net_verdict: net-saving | net-cost | break-even   # by sign of cumulative_pct
-notes:
-  - "Cost is reported in tokens only — no € figure (API pricing misleads subscription users)."
-  - "<other invariants surfaced as plain prose>"
-```
-
-> **Rendering note.** The `eur_delta` / `cumulative_eur_delta` /
-> `pricing_sourced_on` fields stay in the JSON for back-compat, but the
-> rendered dashboard (`docs/value.md`) shows **tokens only** — no € column,
-> no €-per-1k figure, no NETTO € line. See `scripts/render_value_md.py`.
-
-## Invariants
-
-- **No silent drops.** Missing input → emit the rung with
-  `confidence: pending` and a `source_report` pointing to the raw
-  report path the renderer *expected* to find. Never omit a rung
-  from `cost_ladder` because data was missing.
-- **No saving label on negative.** A rung with `token_delta > 0` is a
-  *cost* rung; a rung with `token_delta < 0` is a *saving* rung;
-  zero is *neutral*. The linter
-  ([`scripts/lint_value_dashboard.py`](../../src/scripts/lint_value_dashboard.py))
-  rejects any rendered "saving" label on a positive `token_delta`.
-- **No `measured` without a real source.** A rung that carries
-  `confidence: measured` MUST have a `source_report` that exists on
-  disk under `internal/bench/reports/`. The linter walks this.
-- **Reference scale is documented.** The renderer prints the
-  `reference_scale` block prominently in the dashboard so a reader
-  can recompute mentally for a different workload.
-- **Mode badge is mandatory in `behaviour`.** Every behaviour metric
-  carries `mode: live | dry-run`. The renderer prints the badge
-  inline; a `dry-run` value is never the headline.
-
-## Cumulative rule
-
-`cumulative_pct[i]` = the running cumulative of `token_delta` from
-rungs `0..i` divided by `baseline.input_tokens_per_request`,
-expressed as a signed percentage. The **NETTO** line that the
-renderer prints in Panel A is identical to `totals.cumulative_pct`.
-
-```
-cumulative[i]   = sum(rung.token_delta for rung in cost_ladder[:i+1])
-cumulative_pct  = 100 * cumulative[i] / baseline.input_tokens_per_request
-```
-
-A rung with `confidence: pending` contributes `token_delta: 0` to
-the cumulative (its raw value is the renderer's best guess from the
-raw report; it MUST NOT influence the headline until it flips to
-`measured`).
-
-A rung with `confidence: available` is **measured** but ships behind a
-default-off kill-switch (e.g. the `thin` rung gated on
-`lean_projection.mode`, default `eager-all`). Its measured `token_delta`
-is displayed, but — like `pending` — it contributes `0` to the default
-cumulative / NETTO: the headline reflects what actually ships by default,
-not the best achievable after an opt-in flip. The footnote states the
-would-be total and the validation state. Only `measured`, `estimated`,
-and `vendor-claim` rungs count toward the cumulative.
-
-## Markdown shape (informational human dump)
-
-The `.md` sibling of every `value-v1.json` is informational — a
-flat textual dump of the same data, useful for `git diff` review and
-human spot-checks. The **production** rendering is
-`docs/value.md`, produced by `scripts/render_value_md.py` from the
-latest `value-v1.json`.
-
-The optional `.md` dump carries:
-
-1. `# Value Report — <generated_at>`
-2. `## Reference scale` — the `reference_scale` block.
-3. `## Cost ladder` — one section per rung with its full fields.
-4. `## Behaviour` — one section per metric with its full fields.
-5. `## Totals` — cumulative line + verdict.
-6. `## Notes` — invariants surfaced as prose.
-
-## Cross-references
-
-- Semantics — [`value-dashboard-spec.md`](value-dashboard-spec.md)
-- Roadmap — the `road-to-readable-value-dashboard` roadmap (archived)
-- Pricing source — [`internal/bench/pricing.yaml`](../../internal/bench/pricing.yaml)
-- Rung normaliser — [`scripts/_lib/value_ladder.py`](../../src/scripts/_lib/value_ladder.py)
-- Report assembler — [`scripts/_lib/value_report.py`](../../src/scripts/_lib/value_report.py)
-- Renderer — [`scripts/render_value_md.py`](../../src/scripts/render_value_md.py)
-- Linter — [`scripts/lint_value_dashboard.py`](../../src/scripts/lint_value_dashboard.py)

package/docs/contracts/workflow-packs.md

@@ -1,121 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Workflow packs
-
-> **Status:** beta — first draft 2026-05-16 (Phase 2 Item 7 of
-> `step-15-product-refinement`).
-
-A **workflow pack** bundles a `(profile + preset + command-set +
-skill-allowlist)` combination into a single YAML so a user can adopt
-the full opinionated stance for their role without picking five
-independent settings.
-
-Packs do **not** introduce new commands, skills, or rules. They are
-a **composition contract** — every reference must resolve to an
-existing artefact that has already passed its own contract / linter
-gates.
-
-## Schema
-
-```yaml
-# .agent-src.uncondensed/packs/<pack-id>.yml
-pack:
-  id: <pack-id>                      # kebab-case, file name without .yml
-  audience:
-    label: "<human-readable>"
-    one_liner: "<= 120 chars, what the pack does for the user>"
-  composition:
-    profile_id: <profile.id>         # MUST exist in profiles/
-    preset_id: <preset.id>           # MUST exist in presets/
-  surface:
-    commands_allowed:                # ≤ 12 — slash-command names without leading slash
-      - <command>
-    skills_allowed:                  # ≤ 15 — skill IDs from skills-catalog
-      - <skill>
-    personas:                        # ≤ 4 — persona IDs from personas/
-      - <persona>
-  rationale:                         # why this combination, not free-form notes
-    why_this_profile: "<one paragraph>"
-    why_this_preset: "<one paragraph>"
-    why_these_commands: "<one paragraph>"
-```
-
-### Field semantics
-
-| Field | Type | Required | Notes |
-|---|---|:-:|---|
-| `pack.id` | string | yes | Matches file stem. No collision with `profile.id` or `preset.id`. |
-| `composition.profile_id` | string | yes | Override applied to the chain documented in [`profile-system`](profile-system.md). Pack-supplied id wins over `.agent-settings.yml` only when the user explicitly opts in via `/onboard --pack <id>`. |
-| `composition.preset_id` | string | yes | Override applied to the chain documented in [`config-presets`](config-presets.md). Same opt-in semantics. |
-| `surface.commands_allowed` | list[string] | yes | Cap = **12**. Items must appear in [`command-clusters`](command-clusters.md). The pack does **not** disable other commands — the cap is for the wizard's first-screen rendering, not enforcement. |
-| `surface.skills_allowed` | list[string] | yes | Cap = **15**. Items must appear in `docs/skills-catalog.md`. Same render-only semantics. |
-| `surface.personas` | list[string] | yes | Cap = **4**. Items must appear in `.agent-src.uncondensed/personas/`. |
-| `rationale.*` | string | yes | Forces every pack to justify its composition in plain prose; reviewed at PR time, not at runtime. |
-
-## Resolution chain
-
-Packs are an **opt-in layer above the profile + preset chain**. The
-loader at `scripts/config/packs.py` (Phase 2 deliverable — not yet
-shipped) reads the pack iff:
-
-1. `--pack <id>` flag passed to `/onboard` or `agent-config init`, **or**
-2. `pack.id` set in `.agent-settings.yml` (written by `/onboard --pack`).
-
-When a pack is active:
-
-- `composition.profile_id` is passed to `profiles.load()` as
-  `pack_profile_id` (already wired — see `scripts/config/profiles.py`).
-- `composition.preset_id` is passed to `presets.load()` analogously.
-- `surface.*` lists override the rendered command / skill lists in
-  `/onboard` and in the README "Six entry paths" surface **for the
-  duration of the active pack only**.
-
-Removing a pack (`/onboard --pack none`) reverts to the underlying
-profile + preset defaults; **no data is lost**.
-
-## Validation
-
-`scripts/lint_packs.py` (Phase 2 deliverable — not yet shipped) fails
-CI on:
-
-- Missing required field.
-- `profile_id` / `preset_id` / `commands_allowed` / `skills_allowed`
-  / `personas` referencing an artefact that does not exist.
-- Cap violation (commands > 12, skills > 15, personas > 4).
-- `pack.id` collision with another pack, profile, or preset id.
-
-Until the linter lands, packs are reviewed by hand at PR time against
-this schema.
-
-## What packs do **not** do
-
-- **Do not** declare new commands. Use [`command-clusters`](command-clusters.md).
-- **Do not** modify rules. Use the kernel-rule edit process.
-- **Do not** override safety floors. Domain-safety rules
-  (`.agent-src.uncondensed/rules/domain-safety-*.md`) apply
-  unconditionally — packs cannot widen the deny-list.
-- **Do not** ship telemetry or usage hints. Packs are pure composition.
-
-## Seed packs
-
-Three packs ship at Phase 2 Item 7 close:
-
-| Pack id | Profile | Preset | One-liner |
-|---|---|---|---|
-| `founder-mvp` | `founder` | `fast` | Ship the MVP and the pitch deck in the same week. |
-| `content-engine` | `content_creator` | `balanced` | Editorial calendar, brand voice, and ghostwriter on one loop. |
-| `agency-delivery` | `agency` | `strict` | Multi-client refine → estimate → deliver with audit-grade trace. |
-
-Each pack lives at `.agent-src.uncondensed/packs/<id>.yml` and is
-covered by the validation rules above.
-
-## See also
-
-- [`profile-system`](profile-system.md) — profile axis (audience defaults)
-- [`config-presets`](config-presets.md) — preset axis (risk appetite)
-- [`command-clusters`](command-clusters.md) — verb axis (invocation)
-- [`command-taxonomy`](command-taxonomy.md) — discoverability axis
-- `step-15-product-refinement` § Phase 2 Item 7

package/docs/contracts/workspace-boundary.md

@@ -1,84 +0,0 @@
----
-stability: stable
----
-
-# Workspace Boundary Contract
-
-> **Status** · stable · 2026-06-14. Governed by
-> [`ADR-095`](../decisions/ADR-095-workspace-boundary-contract.md). Exists to
-> stop "workspace" from becoming the new "meta" — a catch-all that absorbs
-> every nearby concern until it owns everything and means nothing.
-
-The **workspace** is the task-orchestration layer behind `/work`,
-`/implement-ticket`, and the host-drive loop — 13 modules under
-`src/cli/python/workspace_*.py`. This contract draws the line around it.
-
-## Owns
-
-The workspace owns the **orchestration and lifecycle** of work:
-
-- **Task orchestration** — picking up, sequencing, and driving a task to done.
-- **Host-session lifecycle** — host detection, tier selection, fallback, the
-  drive loop, the kill-switch.
-- **Continuation** — multi-turn resume: a long task survives across turns
-  instead of restarting cold.
-- **Drive health** — task completion / abandonment / retry telemetry, drive
-  kill-switch signals, local workspace analytics **as drive-health data**.
-
-## Does NOT own
-
-The workspace orchestrates these domains but does **not** own their
-*design, semantics, or policy*. It may **consume** their artefacts (read a
-skill body to hand it off; read a profile to launch under it) — it must not
-**define** them:
-
-| Not owned | Owner lives at | The line |
-|---|---|---|
-| **Skill design** | `src/skills/`, `condense.py`, `skill_linter.py` | Workspace may *resolve* a skill body for hand-off; it must not define what a skill is or how it is authored. |
-| **Profile semantics** | `src/profiles/`, `build_discovery_manifest.py` | Workspace may *launch under* a profile; it must not decide what a profile means. |
-| **Video-provider logic** | `src/scripts/ai-video/` | Workspace never reaches into provider adapters or lifecycle. |
-| **MCP-registry policy** | the MCP builder / registry surface | Workspace never encodes which MCP servers exist or how they install. |
-| **Analytics product strategy** | the telemetry / product-analytics surface | Workspace records *drive-health* metrics locally; it does not decide analytics product strategy. |
-
-## Drift detection — import-edge check + doc-governance
-
-Two layers, with an explicit division of labour:
-
-1. **Import-edge linter** (`scripts/lint_workspace_boundary.py`, AST-static,
-   wired into CI). Fails if any `src/cli/python/workspace_*.py` module imports
-   an owner-module of a not-owned domain. This is the cheap, precise lock — it
-   catches the most common concrete drift (a workspace module reaching into
-   video / MCP / skill-design internals).
-
-2. **Doc-governance (review).** The import check enforces **import edges
-   only**. It does **not** catch *semantic* drift — a workspace module that
-   encodes profile-semantics or analytics-*product-strategy* judgement without
-   importing anything forbidden. That stays a **review responsibility** against
-   this contract. **A green import check is not proof the boundary holds** — it
-   is one supplement to boundary thinking, not a substitute for it.
-
-### Escape hatch
-
-A genuinely justified import may carry an inline pragma:
-
-```python
-import some_owner_module  # boundary-exception: <reason>
-```
-
-The linter then allows that line. A `boundary-exception` is reviewed like any
-boundary change — it is a documented, deliberate exception, not a silent
-bypass. Persistent exceptions are a signal to revisit this contract or the
-module's placement.
-
-## Day-one state
-
-Survey of all 13 `workspace_*.py` modules (2026-06-14, recorded in ADR-095):
-**zero violations**. The only cross-module import is intra-workspace
-(`workspace_inbox → workspace_skills`). The import check therefore locks a
-boundary that currently holds.
-
-## See also
-
-- [`ADR-095`](../decisions/ADR-095-workspace-boundary-contract.md) — the decision.
-- [`ADR-050`](../decisions/ADR-050-workspace-vs-package-root-boundary.md) — the workspace-vs-package-root trust boundary (this refines it at module level).
-- [`daily-workspace.md`](daily-workspace.md) — the daily-workspace surface contract.

package/docs/contracts/workspace-documents.md

@@ -1,144 +0,0 @@
----
-stability: experimental
----
-
-# 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).