@event4u/agent-config 9.7.0 → 9.9.0

package/docs/contracts/orchestration-dsl-v1.md

@@ -1,153 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Orchestration DSL v1
-
-**Purpose.** Pin the YAML schema that the `/orchestrate` command
-reads to chain personas / skills / sub-agents into reproducible
-pipelines. A pipeline file is a deterministic, reviewable artifact
-that re-runs the same step sequence with the same inputs.
-
-**Scope.** Defines the file location, top-level shape, step kinds,
-input / output wiring, and the linter contract. Does **not** define
-the runtime semantics of each step kind — those live in the
-[`/orchestrate`](../../.agent-src.uncondensed/commands/orchestrate.md)
-command and the `work_engine` directive modules it delegates to.
-
-Last refreshed: 2026-05-11.
-
-## File location
-
-```
-.agent-config/orchestrations/<name>.yaml
-```
-
-`<name>` is kebab-case, matches the `name` field inside the file,
-and is unique across the consumer project's orchestrations directory.
-The directory is opt-in — `/orchestrate` falls back to the prompt
-when no file exists.
-
-## Top-level shape
-
-```yaml
-schema_version: 1
-name: pr-readiness-check
-description: |
-  Run the four review-lens judges against the current diff, then
-  consolidate verdicts into a single Markdown report.
-inputs:
-  - id: diff_target
-    description: Git ref to diff against. Default origin/main.
-    default: origin/main
-steps:
-  - id: bug
-    kind: skill
-    ref: judge-bug-hunter
-    with:
-      diff_target: ${{ inputs.diff_target }}
-  - id: security
-    kind: skill
-    ref: judge-security-auditor
-    with:
-      diff_target: ${{ inputs.diff_target }}
-  - id: tests
-    kind: skill
-    ref: judge-test-coverage
-    with:
-      diff_target: ${{ inputs.diff_target }}
-  - id: quality
-    kind: skill
-    ref: judge-code-quality
-    with:
-      diff_target: ${{ inputs.diff_target }}
-  - id: consolidate
-    kind: command
-    ref: review-changes
-    with:
-      verdicts:
-        - ${{ steps.bug.output }}
-        - ${{ steps.security.output }}
-        - ${{ steps.tests.output }}
-        - ${{ steps.quality.output }}
-outputs:
-  report: ${{ steps.consolidate.output }}
-```
-
-## Field semantics
-
-| Field | Type | Required | Meaning |
-|---|---|---|---|
-| `schema_version` | int | yes | Always `1`. Major bump on breaking changes. |
-| `name` | string | yes | Kebab-case identifier; matches filename. |
-| `description` | string | yes | One-paragraph statement of intent. |
-| `inputs[]` | list | no | Named pipeline inputs. Each has `id`, `description`, optional `default`. |
-| `steps[]` | list | yes | Ordered list of steps. Min 1, max 32. |
-| `steps[].id` | string | yes | Snake-case identifier; unique within the pipeline. |
-| `steps[].kind` | enum | yes | One of `skill` · `command` · `persona` · `subagent`. |
-| `steps[].ref` | string | yes | Reference id matching the `kind` namespace. |
-| `steps[].with` | map | no | Inputs to the step. Values MAY use `${{ inputs.X }}` / `${{ steps.Y.output }}` interpolation. |
-| `steps[].when` | string | no | Conditional expression — runs the step only if truthy. Limited to `${{ steps.X.output }}` equality and `success` / `failure` predicates. |
-| `outputs` | map | no | Named pipeline outputs. Surfaced in the final delivery report. |
-
-## Step kinds
-
-| `kind` | `ref` resolves to | Runtime |
-|---|---|---|
-| `skill` | `.agent-src.uncondensed/skills/<ref>/SKILL.md` | Dispatched via `work_engine` directive matching the skill's domain. |
-| `command` | `.agent-src.uncondensed/commands/<ref>.md` | Same dispatch path the slash-command takes when typed by the user. |
-| `persona` | `.agent-src.uncondensed/personas/<ref>.md` | Sets `roles.active_role` for the next dependent step; does not produce its own output. |
-| `subagent` | `subagent-orchestration` mode name | Spawned per [`subagent-orchestration`](../../.agent-src.uncondensed/skills/subagent-orchestration/SKILL.md). |
-
-## Interpolation
-
-Two namespaces only:
-
-```
-${{ inputs.<input-id> }}
-${{ steps.<step-id>.output }}
-```
-
-Unknown namespaces hard-fail at lint time. The interpolation engine
-does string substitution — there are no expressions, no arithmetic,
-no shell-out.
-
-## Linter contract
-
-`scripts/lint_orchestration_dsl.py` hard-fails on:
-
-- missing or malformed top-level keys (`schema_version`, `name`,
-  `description`, `steps`)
-- `schema_version != 1`
-- `name` not matching `[a-z][a-z0-9-]*` or not matching the filename
-- duplicate `steps[].id`
-- `steps[].kind` outside the enum
-- `steps[].ref` pointing at a non-existent skill / command / persona
-- `${{ ... }}` reference to an unknown input or step id
-- `steps[]` length > 32 or < 1
-- `outputs` referencing an unknown step
-
-Exit codes mirror [`lint_hook_manifest.py`](../../src/scripts/lint_hook_manifest.py): `0` clean, `1` failure, `2` schema-load error.
-
-## Privacy floor
-
-Pipeline files are committed artifacts. They MUST NOT contain:
-
-- Secrets, tokens, environment values.
-- Conversation bodies or transcripts.
-- File contents (only paths and refs).
-
-## Stability
-
-Beta. Breaking changes between v1 and v2 are allowed in a minor
-release if the change appears in `CHANGELOG.md` under a `### Breaking`
-heading. Engines MUST gate on `schema_version` and refuse unknown
-majors.
-
-## Cross-references
-
-- Command surface: [`/orchestrate`](../../.agent-src.uncondensed/commands/orchestrate.md).
-- Linter: [`lint_orchestration_dsl.py`](../../src/scripts/lint_orchestration_dsl.py).
-- Runtime dispatcher precedent: [`implement-ticket-flow.md`](implement-ticket-flow.md).
-- Subagent runtime: [`subagent-orchestration`](../../.agent-src.uncondensed/skills/subagent-orchestration/SKILL.md).

package/docs/contracts/package-self-orientation.md

@@ -1,163 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-12
----
-
-# Package Self-Orientation
-
-> **Beta.** Outboard target for the package-root `AGENTS.md` Thin-Root
-> refactor (Phase 6.4 of `road-to-augment-limit-fit`). Holds the
-> deep-detail prose that used to live inline.
-
-## What this repo is
-
-A **governed skill suite** for two cognition clusters — engineering
-depth (Wing 1) and senior cross-department cognition (Wings 2–4).
-**Depth over breadth, decisions over boilerplate, under a shared
-Iron-Law floor** (`commit-policy`, `non-destructive-by-default`,
-`language-and-tone`, `skill-quality`, `direct-answers`).
-
-`type: library` distribution package — published to Composer and npm
-as `event4u/agent-config` / `@event4u/agent-config`. No application
-runtime. Installed via `scripts/install.sh` (Bash) and
-`scripts/install.py` (Python bridge).
-
-## Authoring-time vs. runtime — the scope line
-
-The package is an **authoring-time orchestration toolkit, not an agent
-runtime.** This single distinction decides what belongs in the package
-and what is out of charter — cite it instead of re-deriving the boundary
-per proposal.
-
-- **Authoring-time (in scope).** Code that runs during prompt
-  construction or in response to an explicit user command, assembling
-  context / skills for the agent to *review* — e.g. `compile_router.py`
-  (deploy-time routing table) and `work_engine` (assembles directives
-  when the user types `/work`; the **agent**, not the engine, decides
-  whether to execute the next step — there is no `while not
-  task_complete:` LLM loop in `dispatcher.py`).
-- **Runtime (out of scope).** Code that executes autonomously *during
-  agent operation*, making decisions or LLM calls without per-step human
-  approval — auto-retry loops, autonomous tool-calling, self-modifying
-  skill selection.
-
-When a proposal (a competitor surface, an external-LLM suggestion, a new
-skill idea) would require the package to *run* an agent loop, it crosses
-this line and is rejected on scope, not on merit. Durable application:
-`road-to-capability-discoverability.md` (disposition of "fable-feedback-3").
-
-## The four wings
-
-Four wings compose via [`cross-wing-handoff.md`](cross-wing-handoff.md)
-(beta). Per-wing plates live under `agents/roadmaps/` and `agents/settings/contexts/`.
-
-| Wing | Cognition cluster |
-|---|---|
-| **1 — Engineering** | Code craft, debugging, refactoring, release discipline; depth-first |
-| **2 — Product + Foundation** | Roles cluster (PM, designer, QA, EM); product discovery, prioritization, delivery shape |
-| **3 — GTM + Growth** | CMO + marketing + sales + lifecycle; channel-agnostic positioning + funnel cognition |
-| **4 — Money + Strategy + Ops** | CFO + COO + board-level strategy, valuation, org-design; stage-agnostic financial + operational cognition |
-
-## Tech stack
-
-Bash (install scripts) · Python 3.10+ (linters, condensation, pytest) ·
-Markdown (all content) · Taskfile (`task ci/sync/test`) · GitHub
-Actions (`.github/workflows/`). Non-text inputs (PDF, DOCX, XLSX,
-images, audio) route through the
-[`markitdown`](../../dist/agent-src/skills/markitdown/SKILL.md) skill.
-Wings 2–4 enforce a cognition-only floor (no SaaS auth, no vendor
-SDKs) — `skill_linter.py` enforces it mechanically. Distribution
-mechanics deep-dive: [`agents-md-tech-stack.md`](agents-md-tech-stack.md) (beta).
-
-## Source of truth
-
-| Directory | Purpose | Editable? |
-|---|---|---|
-| `.agent-src.uncondensed/` | Authoring layer — full verbose content | ✅ Yes — edit here |
-| `dist/agent-src/` | Condensed output — shipped in the package, consumed by agents | ❌ No — regenerated |
-| `.augment/` | Local projection of `dist/agent-src/` for Augment Code (gitignored) | ❌ No — regenerated |
-| `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` | Tool-specific projections | ❌ No — regenerated |
-| `agents/` | Package's own roadmaps, contexts, sessions | ✅ Yes |
-
-**Never edit `dist/agent-src/` or `.augment/` directly.** Edit
-`.agent-src.uncondensed/` and run `task sync` (or `task ci`) to
-condense + regenerate the tool directories.
-
-## Repository layout
-
-```
-.agent-src.uncondensed/      ← edit here
-  skills/       (150 skills)
-  rules/        (58 rules)
-  commands/     (103 commands)
-  personas/     (7 personas)
-  templates/    (AGENTS.md, copilot-instructions.md, skill.md, …)
-  contexts/
-
-docs/guidelines/            (47 guidelines — reference material, not packaged)
-docs/contracts/             (kernel-membership, rule-router, rule-classification, …)
-docs/decisions/             (ADRs — kernel overrides, scope decisions)
-dist/agent-src/                 ← condensed output shipped in the package
-dist/agent-src/router.json      ← compiled router manifest (consumed at runtime)
-.augment/                   ← local projection for Augment Code (gitignored)
-scripts/                    ← install.sh, install.py, condense.py, linters
-tests/                      ← pytest (324 tests) + test_install.sh
-agents/                     ← this package's own roadmaps / sessions / contexts
-.github/workflows/          ← CI
-```
-
-## Key rules for agents editing this repo
-
-| Rule | File |
-|---|---|
-| `dist/agent-src/` must stay project-agnostic — no project names, domains, stacks | [`augment-portability`](../../dist/agent-src/rules/augment-portability.md) |
-| Root AGENTS.md + copilot-instructions.md must stay project-agnostic too | [`augment-portability`](../../dist/agent-src/rules/augment-portability.md) |
-| Edit `.agent-src.uncondensed/`, never `dist/agent-src/` or `.augment/` | [`source-of-truth`](../../dist/agent-src/rules/source-of-truth.md) |
-| Skills must declare frontmatter, be self-contained, pass the linter | [`skill-quality`](../../dist/agent-src/rules/skill-quality.md) |
-| Size budgets for skills, rules, commands | [`size-enforcement`](../../dist/agent-src/rules/size-enforcement.md) |
-| Keep `dist/agent-src/` / `agents/` cross-refs in sync on add/rename/delete | [`docs-sync`](../../dist/agent-src/rules/docs-sync.md) |
-| Creating a new skill/rule/command/guideline runs Understand → Research → Draft | [`artifact-drafting-protocol`](../../dist/agent-src/rules/artifact-drafting-protocol.md) |
-
-## Maintainer telemetry (opt-in)
-
-Default-off. `telemetry.artifact_engagement.enabled: true` in
-`.agent-settings.yml` enables local-only JSONL logging. Redaction
-floor + pipeline:
-[`artifact-engagement-flow.md`](../../.agent-src.uncondensed/contexts/contracts/artifact-engagement-flow.md)
-(beta). Rule:
-[`artifact-engagement-recording`](../../dist/agent-src/rules/artifact-engagement-recording.md).
-
-## Context-aware command suggestion
-
-When a free-form prompt matches a command's purpose, the agent
-surfaces matches as numbered options with a "run as-is" escape;
-**nothing auto-executes**. Engine: `scripts/command_suggester/`.
-Rule: [`command-suggestion-policy`](../../dist/agent-src/rules/command-suggestion-policy.md).
-Eligibility + scoring + hardening:
-[`adr-command-suggestion.md`](adr-command-suggestion.md) and
-[`command-suggestion-flow.md`](../../.agent-src.uncondensed/contexts/contracts/command-suggestion-flow.md)
-(beta).
-
-## Multi-agent tool support
-
-`task generate-tools` projects `dist/agent-src/` into Augment Code, Claude
-Code (Agent Skills standard), Cursor, Cline, Windsurf, Gemini CLI,
-and Claude.ai cloud bundles. Skills follow
-[agentskills.io](https://agentskills.io); commands are converted to
-Claude Code Skills with `disable-model-invocation: true`. Per-tool
-layout + cloud-bundle pipeline:
-[`docs/architecture.md`](../architecture.md#cloud-bundle-pipeline).
-
-## Contributing
-
-1. Edit inside `.agent-src.uncondensed/` or `scripts/` or `tests/` —
-   never in `dist/agent-src/`, `.augment/`, `.claude/`, `.cursor/`, etc.
-2. Run `task ci` locally. It must exit 0.
-3. Commit in logical chunks with Conventional Commits.
-4. Open a PR against `main`.
-
-Per-pack safety posture (default-install / consent / council / disclaimer /
-risk_class): [`capability-boundary.md`](capability-boundary.md).
-
-User-facing story: [`README.md`](../../README.md). Architecture
-deep-dive: [`docs/architecture.md`](../architecture.md).

package/docs/contracts/pilot/agent-authority.md

@@ -1,24 +0,0 @@
----
-type: "always"
-tier: "3"
-description: "Priority Index for the four authority rules — Hard Floor → Permission Gate → Commit Default → Trivial-vs-Blocking; read first, route to canonical rule"
-alwaysApply: true
-source: package
----
-
-# Agent Authority — Priority Index
-
-Four rules answer **"may the agent do this autonomously?"** Higher band wins.
-
-| Band | Trigger | Canonical rule |
-|---|---|---|
-| **1. Hard Floor** | Prod-trunk merge · deploy · push · prod data/infra · whimsical bulk deletion · bulk-deletion or infra commit | [`non-destructive-by-default`](non-destructive-by-default.md) |
-| **2. Permission Gate** | Git op · branch / PR / tag · architectural or library change · scope expansion | [`scope-control`](scope-control.md) |
-| **3. Commit Default** | About to commit — never, unless one of four exceptions fires | [`commit-policy`](commit-policy.md) |
-| **4. Trivial-vs-Blocking** | Routine workflow question — act or ask | [`autonomous-execution`](autonomous-execution.md) |
-
-## Rules
-
-- Hard Floor wins, always — autonomy / roadmap / standing instruction never lift.
-- Higher band wins on conflict — commit exception ≠ Hard Floor override; scope permission ≠ commit override.
-- Unsure → [`ask-when-uncertain`](ask-when-uncertain.md).

package/docs/contracts/pilot/direct-answers.md

@@ -1,70 +0,0 @@
----
-type: "always"
-tier: "3"
-description: "Always — direct, unembellished answers. No flattery, no invented facts (verify load-bearing claims, otherwise ask). Emojis only as functional markers. Brevity is the default."
-alwaysApply: true
-source: package
----
-
-# Direct Answers
-
-Three Iron Laws govern every reply.
-
-## Iron Law 1 — No Flattery
-
-```
-NEVER OPEN WITH "GREAT QUESTION", "FASCINATING", "EXCELLENT POINT".
-NEVER PRAISE THE USER'S IDEA TO MAKE THEM HAPPY.
-ANSWER THE SUBSTANCE. SHIP THE TRUTH.
-```
-
-- No positive-adjective opener about user / question / idea / work.
-- No subjective judgment on user code unless evaluation was asked.
-- "Good catch" / "you're right" only when literally true.
-- Mistakes — one-sentence acknowledge, switch behavior, no apology theatre.
-
-## Iron Law 2 — No Invented Facts (severity-tiered)
-
-```
-DO NOT CLAIM WHAT YOU HAVEN'T VERIFIED.
-THE MORE LOAD-BEARING THE CLAIM, THE HARDER YOU VERIFY.
-WHEN VERIFICATION IS NOT WORTH THE COST → ASK.
-```
-
-| Severity | Action |
-|---|---|
-| **High** — load-bearing (paths, signatures, versions, security, "this passes") | Verify with `view` / `grep` / `codebase-retrieval` / fresh output. Too expensive → ask. |
-| **Medium** — project-shape (conventions, file location) | One-tool-call verify, else hedge: *"I'd guess X — not checked"*. |
-| **Low** — well-known idioms | Inference OK; mark as inference if not 100% sure. |
-
-Override: "just guess" / "rough estimate" / "skip verify" → drop to Low for that turn.
-Examples + hedge patterns: [`asking-and-brevity-examples § severity`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#direct-answers--severity-tiered-claim-examples).
-
-## Iron Law 3 — Brevity by Default
-
-```
-THE SHORTEST REPLY THAT FULLY ANSWERS THE QUESTION IS THE RIGHT REPLY.
-LONG ANSWERS ARE A FAILURE MODE, NOT A SIGN OF EFFORT.
-```
-
-- Skip restating the question; skip "Let me…" intent announcements.
-- Skip explaining tool use — the call result speaks.
-- Skip post-hoc summary unless rechecking a decision.
-- Multi-step → bullets. One-true-answer → one sentence.
-
-Never overrides `user-interaction` (numbered options stay) or command-mandated steps.
-
-## Emoji Scope — functional markers only
-
-**Whitelist:** mode markers (`role-mode-adherence`); CLI status `❌` / `✅` / `⚠️`; roadmap checkboxes `[x]` / `[~]` / `[-]`.
-**Blacklist:** opening flair (✨, 🚀, 🎉, 💡, 🔥, 👍); empathy (❤️, 🤗, 😊); section dividers; reaction emojis. Unsure → blacklist.
-
-## Failure modes & examples
-
-Trigger phrases + correction pattern: [`asking-and-brevity-examples § failure-modes`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#direct-answers--failure-modes-the-user-will-call-out).
-Pattern Memory (wrong / right / why): [`direct-answers-demos`](../../docs/guidelines/agent-infra/direct-answers-demos.md).
-Outcome baseline: [`tests/golden/outcomes/direct_answers.json`](../../tests/golden/outcomes/direct_answers.json).
-
-## Interactions
-
-`language-and-tone` · `ask-when-uncertain` · `think-before-action` · `verify-before-complete` · `token-efficiency` · `user-interaction` (overrides brevity).

package/docs/contracts/pilot/language-and-tone.md

@@ -1,63 +0,0 @@
----
-type: "always"
-tier: "3"
-description: "Language and tone — informal German Du, English code comments, .md files always English"
-alwaysApply: true
-source: package
----
-
-# Language and Tone
-
-## Iron Law — mirror the user's language, ALWAYS
-
-```
-MIRROR THE LANGUAGE OF THE USER'S LAST/CURRENT MESSAGE. ALWAYS.
-THE FIRST TOKEN OF EVERY REPLY MUST BE IN THAT LANGUAGE.
-EVERY USER-VISIBLE TOKEN MUST BE IN THAT LANGUAGE — NO EXCEPTIONS.
-A REPLY IN THE WRONG LANGUAGE IS A RULE VIOLATION, NOT A SLIP.
-NO MOMENTUM EXCEPTION. NO TECHNICAL-CONTEXT EXCEPTION.
-NO "SWITCH MID-PARAGRAPH". NO "LAST 20 TURNS WERE ENGLISH".
-NO "INTER-TOOL COMMENT IS JUST A NOTE" EXCEPTION.
-```
-
-Trigger = user's last **chat message**. Not turn count, open file, roadmap, ticket, codebase, tool output, prior reply, or files just edited. Short German (`3`, `weiter`, `mach das`) after many English turns flips the reply to German.
-
-## User-visible prose — every token mirrors
-
-Applies to opening / closing line, **inter-tool commentary** (`Found it`, `Let me check`, `OK`, `Alright`, `Here's`, `So`), section headings, table headers and cells, bullet text, blockquote text, status lines, and the `Recommendation:` / `Empfehlung:` label under numbered-options blocks (per [`user-interaction`](user-interaction.md) Iron Law 1). Wrong label = violation.
-
-Stays in source language: code blocks, command output, file contents, quoted tool output, frontmatter keys, file paths, identifier names, log lines.
-
-## Pre-send gate — MANDATORY
-
-1. **Detect** — language of user's last chat message. Mixed → dominant; tie → German.
-2. **Scan** — every user-visible token per catalog above.
-3. **Rewrite** — wrong-language token → rewrite the whole reply.
-4. **Confirm** — first sentence in target language; recommendation label matches; no English filler-phrase opener (`Let me`, `Now`, `Found`, `Confirmed`, `OK`, `Alright`, `Here's`, `So`) when target is German; no German opener (`Lass mich`, `Jetzt`, `Gefunden`, `Bestätigt`) when target is English.
-
-## Spelled out
-
-- German → informal "Du" (never "Sie"); capitalized at sentence start, lowercase otherwise.
-- Code blocks / command output / file contents / quoted tool output stay native; only surrounding prose mirrors.
-- Numbered options — `.md` source English; rendered reply translated at runtime.
-
-## Slip handling
-
-Acknowledge **once** in the correct language ("Entschuldigung" / "Sorry"). Switch on the same reply. No re-explain in wrong language; no "from now on" promise.
-
-Examples + wrong-vs-correct: [`language-and-tone-examples`](../../docs/guidelines/agent-infra/language-and-tone-examples.md).
-
-## Other language rules
-
-- Code comments in English.
-- `.md` files in English (see below). Translate existing German `.md` files when touched.
-- Two spaces after `❌`, `✅`, `⚠️` in CLI; one space for other icons.
-- One blank line max; no double/triple blanks. File ends with exactly one newline.
-
-## `.md` files — ALWAYS English
-
-Every text inside `.md` under `.augment/`, `dist/agent-src/`, `.agent-src.uncondensed/`, `agents/`: headings, paragraphs, bullets, option labels, prompts, placeholders, ASCII labels, table headers / content. Agent translates at runtime.
-
-**Labeled-anchor exception** — quoting German inside English prose is forbidden. Either translate, OR use a labeled `DE: … · EN: …` anchor block (only allowed location for German prose).
-
-**Detection heuristic** before saving: scan for umlauts (`ä`, `ö`, `ü`, `Ä`, `Ö`, `Ü`, `ß`) outside fenced code / paths / anchor blocks; German function words (`für`, `nicht`, `dass`, `wenn`, `sollte`, `werden`, `arbeite`, `selbstständig`, `jetzt`, `einfach`, `weiter`, `lösche`, `frag`, `schreib`, `mach`); non-English quoted phrases in body text. Hit → translate or move to `DE: … · EN: …` block.

package/docs/contracts/plain-language-surface.md

@@ -1,117 +0,0 @@
----
-stability: beta
-keep-beta-until: 2026-08-26
-roadmap_ref: road-to-frictionless-employee-workspace.md
----
-
-# Plain-Language Surface Contract
-
-> **Status** · v0 / beta · 2026-05-26. Defines the user-facing
-> relabel matrix for non-developer audiences. Phase C of
-> `road-to-frictionless-employee-workspace.md`. The matrix is the
-> single source of truth; lint enforcement lives in
-> `scripts/lint_role_experiences.py --plain-language`.
-
-## What this is
-
-A relabel matrix between the package's **technical vocabulary**
-(council, trust, packs, orchestration, contracts, advisory, …) and
-the **plain-language labels** non-developer audiences (galabau owner,
-sales rep, support agent, team leader, content creator, consultant)
-expect to read.
-
-The matrix does **not** rename the technical vocabulary in
-developer-facing artefacts (`SKILL.md`, rule files, ADRs,
-`docs/contracts/`, `docs/decisions/`, `agents/contexts/`, scripts).
-The technical vocabulary earned its place there. The matrix only
-governs three user-facing surfaces:
-
-1. **Workspace UI strings** (`src/ui/pages/WorkspacePage.tsx` and its
-   child components — buttons, headings, tooltips, banner text).
-2. **`docs/getting-started-by-role.md`** — the non-developer entry
-   surface. Engineering-lead and developer sections keep the
-   technical vocabulary.
-3. **Role experience `index.md` bodies** (`agents/roles/<slug>/index.md`)
-   — the one-paragraph identity + first-task descriptions. The
-   `skills.yml` files are link-targets, not user prose, and keep
-   the skill IDs verbatim.
-
-## Why
-
-The 9.3/10 feedback round (2026-05-25) caught six jargon terms a
-sales rep / galabau owner / support agent does not parse on first
-read: `council`, `trust level`, `pack`, `orchestration`, `contract`,
-`advisory`. Replacing them in the non-developer surface lifts the
-"Daily workspace UX" score from 5.5/10 toward the ≥ 7.5/10 acceptance
-gate; the technical vocabulary survives in the developer-facing
-artefacts where reviewers, contributors, and agents continue to read
-them.
-
-## Matrix
-
-| Technical term | Plain-language label | Applies to surface |
-|---|---|---|
-| `council` | `second-opinion check` | Workspace UI · role indices · getting-started |
-| `trust level` | `reliability score` | Workspace UI · role indices · getting-started |
-| `pack` | `ready-made setup` | Workspace UI · role indices · getting-started |
-| `orchestration` | `multi-step workflow` | Workspace UI · role indices · getting-started |
-| `contract` | `guarantee` | Workspace UI · role indices · getting-started |
-| `advisory` | `recommendation` | Workspace UI · role indices · getting-started |
-
-## Carve-outs — surfaces that keep the technical vocabulary
-
-The matrix MUST NOT apply to:
-
-- `.agent-src.uncondensed/`, `dist/agent-src/`, `.augment/`, `.claude/`,
-  `.cursor/`, `.windsurf/`, `.clinerules/` — all skill / rule /
-  command / persona artefacts.
-- `docs/contracts/`, `docs/decisions/`, `docs/architecture.md`,
-  `docs/getting-started-laravel.md`, every other developer-facing
-  doc.
-- `agents/contexts/`, `agents/roadmaps/`, `scripts/`, source code,
-  test fixtures, golden output files.
-- The developer / engineering-lead sections inside
-  `docs/getting-started-by-role.md` — those readers are the audience
-  for the technical vocabulary.
-- `agents/roles/<slug>/skills.yml` — the skill IDs are URL slugs,
-  not user prose. The `why:` strings stay neutral so the launcher's
-  shortlist rail is informative; both audiences read them.
-
-## Lint enforcement
-
-`scripts/lint_role_experiences.py --plain-language` scans every
-`agents/roles/<slug>/index.md` body for the six jargon terms.
-Frontmatter and fenced code blocks are excluded. Any hit fails the
-lint with a pointer back to this contract. Phase C Step 5 wires the
-flag into `task ci`.
-
-## Tone scaffold
-
-When a relabel feels awkward, default to the role's own language:
-the galabau owner does not call something a "second-opinion check"
-verbatim either, but they understand it instantly. Compare:
-
-- **Technical:** "the council ruled this trust level is `community`."
-- **Plain:** "the second-opinion check rated this reliability score
-  as community-built (less reviewed than core)."
-
-The plain version is longer; that is the cost of readability for
-non-developer audiences. Workspace UI strings stay short by carrying
-the relabel without the explanation (the explanation lives in the
-plain-explain right-rail toggle).
-
-## Re-audit cadence
-
-Re-audit on each of:
-- A new jargon term entering the user-facing surface (caught either
-  by lint or by a feedback round).
-- A role experience adding a section the matrix does not cover.
-- A reviewer round (recruit-session) that names a relabel the matrix
-  missed.
-
-## See also
-
-- [`docs/getting-started-by-role.md`](../getting-started-by-role.md) — the entry surface.
-- [`docs/contracts/role-experience.md`](role-experience.md) — role artefact shape.
-- [`scripts/lint_role_experiences.py`](../../src/scripts/lint_role_experiences.py) — lint enforcement.
-- `road-to-frictionless-employee-workspace.md` § Phase C — the roadmap step.