@event4u/agent-config 9.8.0 → 9.9.0

package/docs/contracts/agent-user-schema.md

@@ -1,170 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-13
----
-
-# `.agent-user.md` schema (v1)
-
-> **Status:** beta — locked for `1.18.0`. Re-evaluate fields after
-> Phase 3 has been in active use for ≥1 week.
-
-`.agent-user.md` is a single, project-root, gitignored Markdown file
-that captures who the user is and how they want the agent to address
-them. It is **deliberately minimal in v1** — name, language, role,
-style, and a single voice sample. Everything else is deferred until
-usage signal exists.
-
-The file is owned by the user. The agent never edits it without an
-explicit `accept` step.
-
-## Locked frontmatter (v1)
-
-```yaml
----
-version: 1
-identity:
-  name: "Matze"            # required — how the user wants to be addressed (full name or shorthand)
-language: "de"             # required — BCP-47-ish primary language ("de", "en", "fr", ...)
-role:                      # optional — unordered list of role labels (may be empty)
-  - founder
-  - engineer
-style:
-  pace: "pragmatic"        # pragmatic | thorough | rapid
-voice_sample: |            # optional — one paste of the user's typical writing
-  Mach das einfach. Wenn unklar, frag im Council.
-last_updated: "2026-05-15" # YYYY-MM-DD — bumped on every accepted change
----
-```
-
-`role` is an **unordered** YAML block-style list. Order carries no meaning
-(no "primary" role). The seeded enum mirrors `SEED_PROFILE_IDS` in
-[`scripts/config/profiles.py`](../../src/scripts/config/profiles.py):
-`founder`, `developer`, `content_creator`, `agency`, `finance`, `ops`.
-Free-form additions are accepted (forward-compatibility) — closed
-validation lives in the wizard / settings GUI, not in the loader.
-
-After the frontmatter, the body is a single freeform **`# Notes`**
-section. Hard cap: **100 lines** total file size (including
-frontmatter, body, and the Notes section). The 100-line cap is
-enforced by `/agents user accept` and `/agents user update`.
-
-## Field reference
-
-| Field | Required | Purpose |
-|---|---|---|
-| `version` | yes | Schema version. v1 is the only valid value today. |
-| `identity.name` | yes | How the agent addresses the user (full name or shorthand — user's choice). |
-| `language` | yes | Primary language; the agent mirrors per [`language-and-tone`](../../dist/agent-src/rules/language-and-tone.md). |
-| `role` | no | Unordered list of role labels (may be empty). Drives reviewer-voice selection and persona pairing when populated. Seeded enum mirrors `SEED_PROFILE_IDS`; additional free-form entries accepted; each present entry must be non-empty. The setup wizard never blocks a save on it. |
-| `style.pace` | yes | `pragmatic` (default), `thorough` (more verification), or `rapid` (shorter replies). |
-| `voice_sample` | no | Optional representative paste — sharpens mirror-back and tone calibration when present; may be empty. The setup wizard never blocks a save on it. |
-| `last_updated` | yes | ISO date, bumped on every accept. |
-
-## Explicit exclusions
-
-The agent NEVER writes any of the following to `.agent-user.md`, even
-with the user's explicit consent — they violate the privacy floor:
-
-- Credentials, API keys, passwords, tokens.
-- Third-party names (children, partners, colleagues, clients).
-- Third-party birthdays or dates.
-- Financial figures (salary, revenue, net worth, runway numbers).
-- Health, legal, or therapy status.
-- Demographics (relationship status, family context, age, location) —
-  **deferred to v2** pending usage data per the re-validation gate.
-- LinkedIn URL or any other external-source identifier — **deferred**
-  until a written host-agent-fetch contract and a "what counts as a
-  public profile field" privacy floor exist.
-
-## Loader contract
-
-Host agents read `.agent-user.md` at session start, in this priority
-order:
-
-1. `.agent-user.md` at project root (this contract).
-2. Nothing — agent uses generic address forms.
-
-The host agent surfaces the user's `identity.name` on first reply
-when the file is present.
-
-## Determinism floor
-
-The `agent-config` package itself contains **zero network code**.
-External enrichment (e.g. LinkedIn profile fetch) was rejected on
-determinism / ToS / test-impossibility grounds, and the host-agent
-delegation workaround was additionally rejected on contract-floor
-grounds (AI Council convergence — Anthropic, OpenAI, Google · 2026-05-14).
-v1 is paste-only via `/agents user init`.
-
-## Staleness
-
-When `last_updated` is older than 90 days, any `/agents user *`
-command surfaces a one-line warning (not a blocker):
-
-```
-⚠️  .agent-user.md was last updated YYYY-MM-DD (>90 days ago). Run /agents user review or /agents user update.
-```
-
-## Commands
-
-| Command | Role |
-|---|---|
-| `/agents user init` | Creates the file from a short interview. Refuses overwrite without `--force`. |
-| `/agents user show` | Read-only render. (Phase 2.) |
-| `/agents user review` | List buffered observations. (Phase 3.) |
-| `/agents user accept` | Apply selected observations; bumps `last_updated`. (Phase 3.) |
-| `/agents user update` | Open in IDE for manual edit; validates on save. (Phase 3.) |
-
-See [`command-clusters.md`](command-clusters.md) for the locked
-cluster registration.
-
-## Observation buffer
-
-Agents MAY append observations about the user (preferred reply style,
-detected language drift, repeated correction patterns) to a separate
-JSONL buffer at the project root:
-
-```
-.agent-user.observations.jsonl
-```
-
-The buffer is **append-only**, gitignored, and never read by the
-host-agent loader directly. It only feeds `/agents user review` →
-`/agents user accept`.
-
-Each line is a single JSON object:
-
-```json
-{"ts":"2026-05-15T10:23:00Z","field":"style.pace","suggest":"rapid","source":"chat","evidence":"user said 'mach kürzer' 3× this session"}
-```
-
-Allowed `field` values mirror the schema (`identity.name`,
-`language`, `role`, `style.pace`, `voice_sample`,
-`notes`). Anything outside that set is dropped on read.
-
-Privacy floor applies on write — never buffer credentials, third-party
-PII, financial figures, or health/legal status. The same
-[exclusions list](#explicit-exclusions) governs both `.agent-user.md`
-and the buffer.
-
-## Gitignore
-
-`.agent-user.md` and `.agent-user.observations.jsonl` are added to the
-package-managed `.gitignore` block
-([`src/config/gitignore-block.txt`](../../config/gitignore-block.txt)) and
-ignored by default. A `--shared` opt-in to commit `.agent-user.md` is
-deferred — only the doc note lands in v1. The observation buffer is
-**never** shared.
-
-## Example
-
-A complete, paste-ready fixture lives at
-[`docs/examples/agent-user.example.md`](../examples/agent-user.example.md).
-Copy it to the project root as `.agent-user.md` and edit, or run
-`/agents user init` for the interactive flow.
-
-## See also
-
-- [`language-and-tone`](../../dist/agent-src/rules/language-and-tone.md) — language-mirroring rule the loader feeds.
-- [`agents-md-thin-root`](../../dist/agent-src/skills/agents-md-thin-root/SKILL.md) — Thin-Root contract that this file complements (user-state vs project-state).
-- [`ghostwriter-schema`](ghostwriter-schema.md) — sibling voice primitive for **external public-figure** voices (`/ghostwriter:write`, mandatory disclosure footer). `.agent-user.md` covers the maintainer's **own** voice (`/post-as:me`, no footer); the three-primitive model is summarised in [`personas/README.md § See also — sibling voice primitives`](../../dist/agent-src/personas/README.md).

package/docs/contracts/agents-layout.md

@@ -1,148 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-17
----
-
-# `agents/` Directory Layout Contract
-
-> **Do not bypass this contract.** Every entry at the `agents/` root — file or
-> directory — must appear in this table. Unknown entries are CI violations
-> (`lint_agents_layout.ts` enforces this in source-repo mode, warns in consumer
-> mode). Adding a new top-level entry requires a PR that also updates this table
-> and the classification manifest (`src/config/agents-paths.yml`).
-
-## Design invariants
-
-1. **The `agents/` root stays flat-minimal.** Content lives in typed
-   subdirectories. New flat files require a contract edit and explicit rationale
-   (six whitelisted flat files exist; no new ones without a deliberate decision).
-2. **`agents/tmp/` is the user's inbox; `agents/tmp.old/` is the processed
-   archive.** The agent reads inbox files and moves them to `tmp.old/` after
-   consumption. The agent's own scratch goes to `agents/runtime/tmp/` or the
-   session scratchpad. See § User Inbox Workflow below.
-3. **Both `tmp/` and `tmp.old/` are gitignored in every scope.** Consumer
-   projects would commit their inbox without the managed block entry.
-
----
-
-## Whitelisted flat files
-
-| File | Git policy | Owner | Rationale |
-|---|---|---|---|
-| `index.md` | tracked-durable | agents (auto-regenerated) | Human-readable full index; regenerated by `./agent-config roadmap:progress` |
-| `roadmaps-progress.md` | tracked-durable | agents (auto-regenerated) | Roadmap dashboard; regenerated by `./agent-config roadmap:progress` |
-| `.agent-tools.yml` | tracked-durable | maintainer | Declares which tool projections `task generate-tools` builds |
-| `.maintainer-workspace.md` | tracked-durable | maintainer | Maintainer-facing workspace notes; source-repo only |
-| `.gitkeep` | tracked-durable | — | Keeps `agents/` in the tree even when all other files are ignored |
-| `installed-tools.lock` | **local-only** (gitignored) | installer (`scripts/install.py`) | Per-user install inventory; leaks `$HOME`; consumer-only artefact, must never be committed in the source repo |
-
----
-
-## Directory table
-
-Scope column: `pkg` = source repo only · `consumer` = consumer projects only · `both` = all.
-
-| Directory | Scope | Git policy | Retention | Owner | Purpose |
-|---|---|---|---|---|---|
-| `decisions/` | pkg | tracked-durable | permanent | council + humans | Low-impact council corpus, open questions, per-decision ADRs |
-| `evidence/` | pkg | tracked-durable (see notes) | permanent | tooling + humans | Research, analysis, audits, eval findings, metrics — everything evidential. Sub-dirs: `analysis/`, `audits/`, `architectural-drift/`, `archived-skills/`, `council/`, `eval-findings/`, `eval-corpora/`, `investigations/`, `mcp-sessions/`, `metrics/`, `notes/`, `reports/` |
-| `features/` | pkg | tracked-durable | permanent | maintainer | Feature-flag status docs (long-form complement to `.agent-tools.yml`) |
-| `knowledge/` | both | tracked-durable | permanent | human-gated (`/team-knowledge` skills) | Curated committed knowledge pages (sessions/, concepts/, procedures/, decisions/). Committed only after human review; never auto-written |
-| `memory/` | both | mixed (see notes) | permanent (durable) / TTL (intake) | `/memory:*` skills | Layer 1 memory pipeline: `intake/` (gitignored JSONL), `knowledge/` subdir (mirrors top-level knowledge/). Intake is local-only; curated YAML in subdirs is committed |
-| `notes/` | pkg | tracked-durable | permanent | maintainer | Ad-hoc analyst notes that are not evidence/reports (e.g. `visibility-sync-audit.md`). **Merge candidate** — new notes land in `evidence/notes/` going forward; existing file stays for now |
-| `overrides/` | both | tracked-durable | permanent | humans (`/override:*`) | Per-project skill/rule/command/guideline overrides; the only consumer-committed customisation layer |
-| `recruit-sessions/` | pkg | tracked-durable | permanent | maintainer | User-recruit study session data and runbooks |
-| `reference/` | pkg | tracked-durable | permanent | maintainer | External reference material: `ai-video/`, `docs/`, `ghostwriter/` |
-| `roadmap-assets/` | pkg | tracked-durable | permanent | maintainer | Supplemental assets for specific roadmaps (e.g. design-asset `.assets.md` files). **Merge candidate** — new assets can land in `evidence/` or alongside the roadmap file |
-| `roadmaps/` | pkg | tracked-durable | permanent | agents + maintainer | Active roadmaps; sub-dirs: `archive/`, `later/`, `skipped/`, `stubs/` |
-| `roles/` | pkg | tracked-durable | permanent | maintainer | Role-definition docs for consumer user-types (consultant, galabau, support, …) |
-| `runtime/` | both | **local-only** (gitignored, entire tree) | session / TTL | multiple scripts | Volatile runtime artefacts: council sessions/responses, price cache, chat-history, budget history, hook state, logs, mcp-telemetry, dispatcher lock, tmp scratch. Nothing inside is ever committed |
-| `settings/` | pkg | tracked-durable | permanent | maintainer | Long-lived package-level configuration and context documents: `contexts/`, `policies/` |
-| `state/` | both | **local-only** (gitignored) | session / TTL | hooks | Tier-1 hook runtime state (context-hygiene, verify-before-complete, etc.), the hot-context working-memory cache (`hot-context.md` — bounded 400 words, fixed sections `Last Updated / Branch / Key Facts / Active Threads / Open Verifications / Recent Changes`, overwritten on every `stop`, restored on `session_start`), and GUI wizard resume snapshot. Never committed |
-| `templates/` | pkg | tracked-durable | permanent | maintainer | Reusable template files for agents (currently empty; reserved for future use) |
-| `tickets/` | pkg | tracked-durable | permanent | maintainer + `emit-tickets` | Ticket bundles (`_registry.yml`, per-bundle dirs); governed by `road-to-ticket-bundles.md` |
-| `tmp/` | both | **local-only** (gitignored, BOTH scopes) | user-owned | **user only** | User inbox: free-form notes/todos for the agent to consume. Never auto-swept. See § User Inbox Workflow |
-| `tmp.old/` | both | **local-only** (gitignored, BOTH scopes) | TTL (30 days) | agent (moves only) | Processed inbox archive: the agent moves consumed `tmp/` files here after processing. Auto-swept by janitor at 30-day TTL; user can also delete manually |
-| `.harvest-local/` | pkg | **local-only** (gitignored) | retained evidence | maintainer | Source-confidentiality: named external-reference harvest evidence. 74 MB; never committed (see `source-confidentiality` rule) |
-
----
-
-## User Inbox Workflow
-
-```
-agents/tmp/        ← USER drops notes, todos, draft ideas here
-     ↓ agent reads + processes (roadmap create, memory promote, etc.)
-agents/tmp.old/    ← AGENT moves the consumed file here, same reply
-     ↓ janitor sweeps after 30 days
-     (deleted)
-```
-
-**Rules:**
-
-- `agents/tmp/` is the **user's space** — the agent only reads and moves from
-  it; the agent never writes files into it.
-- After consuming a file from `agents/tmp/` (as a command input), the agent
-  moves it to `agents/tmp.old/<original-name>` in the **same reply** as the
-  processing. No confirmation needed (gitignored, reversible, local-only).
-- The agent's own scratch (intermediate calculations, session notes) goes to
-  the **session scratchpad** or `agents/runtime/tmp/` — never into `agents/tmp/`.
-- `agents/tmp/` is **never** auto-swept by the janitor — it belongs to the user.
-  The janitor only touches `agents/tmp.old/` (TTL = 30 days).
-- Both directories are gitignored in **package and consumer scope** (entry in
-  `src/config/agents-paths.yml` with `scope: both`).
-
----
-
-## Consumer-only scope (slim profile)
-
-After `agent-config migrate`, a consumer project's `agents/` contains only:
-
-| Entry | Rationale |
-|---|---|
-| `overrides/` | Per-project skill/rule customisation |
-| `.event4u-bridge.yml` | Retired (ADR-020 amendment 2026-07-13); global root resolves from `~/.event4u/agent-config`. Legacy leftover only — deleted by installer / `refresh --project`. |
-| `.gitkeep` | Keeps `agents/` in the tree |
-| `knowledge/` | Optional: curated project-specific knowledge pages |
-| `memory/` | Optional: promotion pipeline (intake gitignored, curated YAML committed) |
-| `roadmaps/` | Optional: project-local roadmaps |
-| `tmp/` | Optional: user inbox (gitignored) |
-| `tmp.old/` | Optional: processed inbox archive (gitignored) |
-
-Entries that are **not** expected in consumers (and that `agent-config doctor`
-will warn about): `evidence/`, `decisions/`, `features/`, `reports/`,
-`recruit-sessions/`, `settings/`, `roles/`, `reference/`, `roadmap-assets/`,
-`notes/`, `tickets/`, `templates/`, `runtime/`, `state/`.
-
----
-
-## Overlap decisions (2026-07-06)
-
-| Pair | Decision |
-|---|---|
-| `evidence/` vs `reports/` vs `notes/` | **Keep `evidence/` as the umbrella.** `evidence/reports/` and `evidence/notes/` already exist as subdirs. New reports/notes land there. The top-level `reports/` and `notes/` are **legacy** — no new files; existing files can be migrated per future clean-up PR (non-blocking). |
-| `memory/` vs `knowledge/` | **Keep both** with a crisp boundary: `knowledge/` = committed curated pages (human-reviewed); `memory/` = promotion pipeline (intake is gitignored JSONL; only curated YAML subsets get committed). |
-| `templates/` vs `roadmap-assets/` | **Both empty/minimal — keep as reserved.** `templates/` = reusable agent-facing templates; `roadmap-assets/` = supplemental for specific roadmaps. New assets prefer `evidence/` sub-dirs unless they are true roadmap supplements. No migration needed today. |
-| `recruit-sessions/`, `features/`, `tickets/` | **Keep all three** — distinct purposes, each has an active owner and lifecycle (recruit-sessions = user research; features = flag docs; tickets = bundle system). |
-
----
-
-## What needs a contract edit
-
-Any PR that:
-- Adds a new top-level directory to `agents/`
-- Adds a new whitelisted flat file to `agents/`
-- Changes the git policy of an existing entry
-- Changes the consumer-scope subset
-
-...must update this table in the same commit, update `src/config/agents-paths.yml`,
-and add the new entry to `ALLOWED_SOURCE_DIRS` (or `ALLOWED_FLAT_FILES`) in
-`src/scripts/lint_agents_layout.ts`.
-
-## See also
-
-- `src/config/agents-paths.yml` — machine-readable classification manifest (Phase 3)
-- `src/scripts/lint_agents_layout.ts` — CI enforcement
-- `docs/contracts/migrate-command.md` — consumer migration flow
-- ADR-020 — global-only install; bridge marker
-- ADR-050 — workspace vs package root boundary
-- `source-confidentiality` rule — `.harvest-local/` rationale

package/docs/contracts/agents-md-tech-stack.md

@@ -1,75 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Tech stack — deep detail
-
-Outboarded from `AGENTS.md` Phase 2 of `road-to-augment-limit-fit` to
-keep the front-door file under the Augment workspace-guidelines
-budget. AGENTS.md retains a 2-3 sentence summary; everything below
-is the long-form reference.
-
-## Recommended ingestion path for non-text formats
-
-PDF, DOCX, XLSX, PPTX, EPUB, image, and audio inputs route through the
-[`markitdown`](../../dist/agent-src/skills/markitdown/SKILL.md) skill — a
-thin markdown-only wrapper over Microsoft's MIT-licensed
-`markitdown-mcp` server (peer-side install, zero Python in this
-package). The skill ships the four-layer security defense:
-
-1. **Skill checklist** — frontmatter declares allowed input types, max
-   sizes, and the disallow list (no remote URLs, no executables).
-2. **Narrow API** — the skill exposes `convert(path) → markdown`; no
-   shell-out, no arbitrary file globbing.
-3. **Docker read-only** — `markitdown-mcp` runs in a read-only
-   container with the mount restricted to the input file's directory.
-4. **Localhost binding** — the MCP server binds to `127.0.0.1` only;
-   no exposure to the host network.
-
-Calibrated token claim: 3-5× comprehension on text-heavy formats
-(PDF, DOCX), 10-50× on image-heavy formats (scanned PDF, PPTX with
-diagrams). Measure locally with
-`./scripts-run src/scripts/measure_markitdown_lift` against
-`tests/fixtures/markitdown-corpus/`.
-
-## Cognition-only floor for Wings 2–4
-
-Wings 2 (Product + Foundation), 3 (GTM + Growth), and 4 (Money +
-Strategy + Ops) enforce a no-SaaS-auth, no-vendor-SDK,
-no-stage-prescription floor: cognition artifacts (markdown tables,
-scoring rubrics, walkthroughs) must work in any host without
-external dependencies.
-
-Mechanical enforcement: the structural-malice check in
-`scripts/skill_linter.py` blocks:
-
-- Credential exfiltration patterns (env-var reads of `*_TOKEN`,
-  `*_KEY`, `*_SECRET` followed by network egress).
-- Remote execution (subprocess to URLs, `eval` of network-fetched
-  content).
-- Shell injection in subprocess calls (string-concat shell commands
-  with user-controlled input).
-
-See `.agent-src.uncondensed/rules/skill-quality.md` § Structural
-Malice Floor for the full rule.
-
-## Distribution mechanics
-
-- `type: library` in `composer.json`; no `app/` directory, no
-  application runtime (no Laravel, Symfony, Next.js, or other
-  framework app code).
-- Published to Composer and npm as `event4u/agent-config` /
-  `@event4u/agent-config`.
-- Installed into consumer projects via `scripts/install.sh` (Bash)
-  and `scripts/install.py` (Python bridge).
-
-## See also
-
-- [`AGENTS.md`](../../AGENTS.md) — front-door (kernel orientation only)
-- [`docs/architecture.md`](../../docs/architecture.md) — package
-  architecture and cloud-bundle pipeline
-- [`.agent-src.uncondensed/rules/skill-quality.md`](../../.agent-src.uncondensed/rules/skill-quality.md)
-  — Structural Malice Floor
-- [`dist/agent-src/skills/markitdown/SKILL.md`](../../dist/agent-src/skills/markitdown/SKILL.md)
-  — markitdown skill entry point