@event4u/agent-config 9.6.0 → 9.8.0

package/README.md

@@ -4,17 +4,17 @@
 
 [![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config)
 
-[![Skills](https://img.shields.io/badge/Skills-278-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-105-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-190-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-101-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
-
-> **Choose your experience — developer · founder · content · agency · finance · ops. Add packs. Get a focused command set, not a 500-artefact dump.** Bring your own AI provider.
-
 **Try it in 30 seconds** — drop one read-only subagent into any repo and watch it gate "done": `@production-validator check this branch is actually done`. No wizard, no lock-in, nothing else installed — the [30-second wedge ↓](#quickstart) is the whole first step. Start at the proof, not the catalog: **[event4u-app.github.io/agent-config/proof/](https://event4u-app.github.io/agent-config/proof/)**.
 
 ![The trust surface running green — every "verify it yourself" command from a real, CI-re-executed run](docs/media/proof-demo.gif)
 
 **Every public claim in this README is machine-checked — [verify it yourself](docs/proof.md).** In a market that runs on unbacked headline numbers, this one binds each claim to resolvable evidence or fails its own build.
 
-**A deep library of skills, commands, and governed rules** — plus a capability router that loads the right skill on intent, and multi-agent orchestration with consensus review. The whole layer is compiled into 7+ host agents (Claude Code, Cursor, Augment, Cline, Windsurf, Copilot, Gemini) with **zero runtime daemon**.<!-- claim:no-runtime-daemon --> Six role-shaped entry paths sit on top, so any host becomes a reliable team member — without locking you to a single model or vendor.
+> **Choose your experience — developer · founder · content · agency · finance · ops. Add packs. Get a focused command set, not a 500-artefact dump.** Bring your own AI provider.
+
+[![Skills](https://img.shields.io/badge/Skills-281-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-107-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-190-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-101-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-29-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
+
+**A deep library of skills, commands and governed rules** — plus a capability router that loads the right skill on intent and multi-agent orchestration with consensus review. The whole layer is compiled into **20 host agents** — of 23 detected, 3 being export-only<!-- claim:host-agent-count --> (Claude Code, Cursor, Augment, Cline, Windsurf, Copilot, Gemini CLI, Codex, Continue, Zed, JetBrains, Aider and more) — with **zero runtime daemon**.<!-- claim:no-runtime-daemon --> Six role-shaped entry paths sit on top, so any host becomes a reliable team member — without locking you to a single model or vendor.
 
 ### What's different
 
@@ -27,13 +27,13 @@ It is both deep **and** disciplined — and honest about what it deliberately is
 
 **What it deliberately is *not*** — a content + governance layer, not a runtime: **no background daemon, no separate state database, no self-rewriting memory, no auto-build pipeline.** The host agent runs the loop; every learned change is human-reviewed; the same layer stays portable across tools. Capability without a process to babysit.
 
-> **Where this comes from (honest provenance).** The skills, rules, and personas
+> **Where this comes from (honest provenance).** The skills, rules and personas
 > are distilled from real production work on TypeScript and PHP codebases. The
 > governance mechanics are stack-agnostic, but the domain heuristics are richest
 > where they were forged — treat coverage on other stacks as promising, not
-> proven, and tell us where it falls short.
+> proven and tell us where it falls short.
 
-See exactly [what works on which host](docs/capability-matrix.md), or jump to [things you can do in a minute](docs/cookbook.md).
+See exactly [what works on which host](docs/capability-matrix.md) or jump to [things you can do in a minute](docs/cookbook.md).
 
 ### Pick your profile — six entry paths
 
@@ -100,14 +100,14 @@ is platform operation, not a user-work flow.)
 
 > **Creative Pack — cinematic AI video.** script → character-locked image → motion+audio prompt → provider render → stitched clip, with `AIV_DRYRUN=true` as the cost-safety default. A first-class capability inside the **content / creator** experience — no longer the package's headline. See [`/video:from-script`](.augment/commands/video/from-script.md).
 
-> **Legal Pack — not legal advice.** The EU/DE legal pack (contract/NDA/DPA review, triage) is a **research-and-drafting aid only** — it does not provide legal advice, does not replace a qualified lawyer, and must not be relied on for any concrete matter. It produces general information and general templates, never individual-case examination. Read [`LEGAL_NOTICE.md`](LEGAL_NOTICE.md) before use.
+> **Legal Pack — not legal advice.** The EU/DE legal pack (contract/NDA/DPA review, triage) is a **research-and-drafting aid only** — it does not provide legal advice, does not replace a qualified lawyer and must not be relied on for any concrete matter. It produces general information and general templates, never individual-case examination. Read [`LEGAL_NOTICE.md`](LEGAL_NOTICE.md) before use.
 
 > Full catalog — every skill, rule, command, guideline: [`docs/catalog.md`](docs/catalog.md). The headline is the **experience** (profile + packs) **and** the depth behind it.
 
 ## Use it in your project
 
 Run from a consumer repo — bootstrap via `npx`, the agent picks up
-your stack, and you ship work end-to-end. New install? Start with the
+your stack and you ship work end-to-end. New install? Start with the
 [Quickstart](#quickstart). Already installed? [Supported tools](#supported-tools)
 shows the wired AIs; [`docs/featured-commands.md`](docs/featured-commands.md)
 lists the end-to-end workflows (`/implement-ticket`, `/work`,
@@ -119,8 +119,8 @@ lists the end-to-end workflows (`/implement-ticket`, `/work`,
 
 Don't take the claims on trust — **verify them.** [`docs/proof.md`](docs/proof.md)
 is generated from source: a claim→evidence table (every public claim binds to a
-resolvable pointer, or CI fails), honest-null benchmarks *including the runs where
-the package changed nothing*, and a "verify it yourself" block you run on a fresh
+resolvable pointer or CI fails), honest-null benchmarks *including the runs where
+the package changed nothing* and a "verify it yourself" block you run on a fresh
 checkout. The proof page fails CI if it drifts from its sources — reproducibility
 is the proof. Browse it on the deployed docs site — the proof page is the primary entry:
 [event4u-app.github.io/agent-config/proof/](https://event4u-app.github.io/agent-config/proof/).
@@ -132,7 +132,7 @@ find-replace re-skin PRs here runs on your catalog too —
 [`docs/anti-reskin-gate.md`](docs/anti-reskin-gate.md).
 
 Audit-disciplined by construction — every memory consult, decision
-key, and hook concern lands in `agents/runtime/state/` so you can replay it.
+key and hook concern lands in `agents/runtime/state/` so you can replay it.
 [Core principles](#core-principles) names the four invariants;
 [What `agent-config` is — and what it isn't](#what-agent-config-is--and-what-it-isnt)
 draws the scope boundary.
@@ -207,7 +207,7 @@ Migrating from a v1.x install? `npx @event4u/agent-config migrate` — full note
 
 A **content layer** — skills, rules, commands, guidelines, personas — distributed via npm and projected into every supported AI tool's native config format. It follows the [Agent Skills open standard](https://agentskills.io).
 
-It is **not** an agent runtime. The agent loop, the LLM dispatcher, and tool orchestration stay with the host tool (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI, Copilot). Think of it as a playbook and style guide for those tools — not a replacement.
+It is **not** an agent runtime. The agent loop, the LLM dispatcher and tool orchestration stay with the host tool (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI, Copilot). Think of it as a playbook and style guide for those tools — not a replacement.
 
 | In scope | Out of scope |
 |---|---|
@@ -254,7 +254,7 @@ refine → memory → analyze → plan → implement → test → verify → rep
 - **Reviews** the diff through four judges (bugs, security, tests, code quality).
 - **Reports** changes, verdicts, follow-ups — then stops. `/commit` and `/pr:create` are suggestions, never auto-run.
 
-Any ambiguity halts the flow with numbered options — never a silent guess. Persona comes from `.agent-settings.yml` (`roles.active_role`): `senior-engineer` (default), `qa`, or `advisory` (plan-only).
+Any ambiguity halts the flow with numbered options — never a silent guess. Persona comes from `.agent-settings.yml` (`roles.active_role`): `senior-engineer` (default), `qa` or `advisory` (plan-only).
 
 → [Command reference](dist/agent-src/commands/implement-ticket.md) · [Flow contract](docs/contracts/implement-ticket-flow.md)
 
@@ -316,7 +316,7 @@ Create the user file interactively: `/agents user init` ([schema](docs/contracts
 
 ### Self-hosted MCP on Cloudflare — zero local install
 
-Skills, commands, rules, and guidelines can be served as an MCP endpoint from your own Cloudflare Worker — any MCP client (Claude Desktop, Claude Code, Cursor, Zed, Continue, hosted agents) talks to it over HTTP. Two auth modes: `public` (default, OSS read-only deploys) and `bearer-auth` (operator opt-in, `MCP-Token` Wrangler secret).
+Skills, commands, rules and guidelines can be served as an MCP endpoint from your own Cloudflare Worker — any MCP client (Claude Desktop, Claude Code, Cursor, Zed, Continue, hosted agents) talks to it over HTTP. Two auth modes: `public` (default, OSS read-only deploys) and `bearer-auth` (operator opt-in, `MCP-Token` Wrangler secret).
 
 ```bash
 task mcp:cloud:login         # one-time, opens browser
@@ -340,13 +340,13 @@ task mcp:cloud:secret-put    # opt in to bearer-auth (recommended for private de
 
 The Hard Floor on organization-mode features (SSO, central policy, OAuth connectors, team-context) is preserved by design — they stay cancelled until a real first customer + funded security audit lifts them. The small-team recipe is the supported path in the meantime.
 
-> *The 9.3/10 feedback round (2026-05-25) re-asked for OAuth knowledge connectors, IAM / org governance, and organization-shared memory. Each is a stable cancellation row in [`team-deployment-posture`](docs/deploy/team-deployment-posture.md) under the same three release gates — recruited team customer · funded audit · maintainer ADR.*
+> *The 9.3/10 feedback round (2026-05-25) re-asked for OAuth knowledge connectors, IAM / org governance and organization-shared memory. Each is a stable cancellation row in [`team-deployment-posture`](docs/deploy/team-deployment-posture.md) under the same three release gates — recruited team customer · funded audit · maintainer ADR.*
 
 ---
 
 ## Harness expectations
 
-Three classes of install/runtime behaviour look like package bugs but are host-harness behaviour the package cannot control — sibling-plugin namespaces (`codex:*`, `cc-gemini-plugin:*`), deferred tools surfaced via `ToolSearch`, and cross-scope skill drift (real bug, fixed in the distribution-channels track). Diagnostics + the package's response: [`docs/contracts/harness-expectations.md`](docs/contracts/harness-expectations.md). First step when a skill appears twice: `task probe:skills`.
+Three classes of install/runtime behaviour look like package bugs but are host-harness behaviour the package cannot control — sibling-plugin namespaces (`codex:*`, `cc-gemini-plugin:*`), deferred tools surfaced via `ToolSearch` and cross-scope skill drift (real bug, fixed in the distribution-channels track). Diagnostics + the package's response: [`docs/contracts/harness-expectations.md`](docs/contracts/harness-expectations.md). First step when a skill appears twice: `task probe:skills`.
 
 ## Supported tools
 
@@ -477,7 +477,7 @@ Browse content: [all commands](dist/agent-src/commands/) · [skills catalog](doc
 ## Troubleshooting
 
 First stop for any install problem: `agent-config doctor` — it flags a
-missing-from-`PATH` binary, binary↔plugin version drift, stale orphans, and
+missing-from-`PATH` binary, binary↔plugin version drift, stale orphans and
 manifest issues, each with a one-line fix hint.
 
 ### A new command / skill is missing in Claude Code after an upgrade
@@ -486,7 +486,7 @@ Under the single-surface model, `agent-config upgrade` refreshes the
 `~/.claude/` file projection — that IS the content surface, so a fresh
 session picks the new commands up directly. If commands are still missing,
 the usual cause is a leftover **marketplace plugin**: it is a git-SHA
-snapshot that never moves with the npm upgrade, and it shadows nothing —
+snapshot that never moves with the npm upgrade and it shadows nothing —
 it just lists everything twice while lagging behind. Remove it:
 
 ```bash
@@ -521,7 +521,7 @@ Only the initial `npm install -g` hard-aborts an upgrade. Every later step
 (global re-deploy with hook registration, settings sync, wrapper + git-hook
 refresh) runs independently — a single failed step is reported in the
 end-of-run summary instead of silently skipping the rest. Re-run
-`agent-config upgrade` to converge, and use `agent-config doctor` to name
+`agent-config upgrade` to converge and use `agent-config doctor` to name
 anything left in a mixed state.
 
 ### `agent-config: command not found` / hooks stopped firing

package/dist/agent-src/README.md

@@ -1,8 +1,8 @@
 # Agent Infrastructure
 
 > **⚠️ DO NOT edit files in `dist/agent-src/` or `.augment/` directly.**
-> The source of truth is `.agent-src.uncondensed/`. Edit there, then run `task sync`.
-> See `.agent-src.uncondensed/commands/condense.md` for the full workflow.
+> The source of truth is `src/` (`src/skills/`, `src/rules/`, `src/agent-src/`). Edit there, then run `task sync`.
+> See the `source-of-truth` rule and the `/condense` command for the full workflow.
 
 This directory contains the shared agent infrastructure: skills, commands, rules, guidelines,
 templates, and contexts that power the AI coding assistant across all projects.

package/dist/agent-src/commands/commit/in-chunks.md

@@ -70,6 +70,14 @@ Splitting rules:
 
 Generate commit messages per [`commit-conventions`](../../rules/commit-conventions.md).
 
+### 3b. Secret-leak pre-flight — MANDATORY, not autonomy-lifted
+
+Run `./scripts-run src/scripts/check_secret_leak`. A high-confidence hit is a
+safety surface: **STOP even under this autonomous flow** (autonomy never lifts
+it), hand to [`secret-vcs-guard`](../../rules/secret-vcs-guard.md) — show the
+match, ask, offer the alternative. Never auto-commit a secret; never silently
+strip one.
+
 ### 4. Validate, then commit immediately
 
 Before staging anything, run the same `preview-on-error` validator as

package/dist/agent-src/commands/commit.md

@@ -79,6 +79,23 @@ If there are no uncommitted changes (staged or unstaged), report "Nothing to com
   - Are purely stylistic/formatting changes (separate from logic changes)
   - Are unrelated to the main change (e.g. config fix, unrelated typo)
 
+### 3b. Secret-leak pre-flight
+
+Before planning any commit, scan the changed set for credentials:
+
+```
+./scripts-run src/scripts/check_secret_leak
+```
+
+If it exits non-zero (a high-confidence secret in the diff or an untracked file),
+**STOP** — do not stage or commit. Hand control to the
+`.augment/rules/secret-vcs-guard.md` rule: show the match, ask via numbered
+options, and offer the tiered alternative (see
+`.augment/skills/secrets-management/SKILL.md`). Only proceed
+once the user resolves it (move to a store, or add an audited
+`# secret-allow` / `.secret-allow` entry for a confirmed false positive). Never
+silently commit a secret; never silently strip one.
+
 ### 4. Plan the commits
 
 For each logical group, determine the commit message following the commit conventions rule

package/dist/agent-src/commands/pr/create.md

@@ -53,6 +53,10 @@ Uses `/create-pr:description-only` to generate the PR content, then creates the
 - Verify the current branch is NOT the default branch (`main` / `master`).
 - Run `git status` — warn if there are uncommitted changes.
 - Run `git log origin/{default}..HEAD --oneline` to verify there are commits to push.
+- **Secret-leak pre-flight (MANDATORY before push):** run
+  `./scripts-run src/scripts/check_secret_leak`. On a high-confidence hit, STOP —
+  do not push; hand to `.augment/rules/secret-vcs-guard.md` (show, ask, offer the
+  alternative, rotate-first if already in history). Pushing publishes the secret.
 - If the branch has not been pushed yet, ask the user (in their language) whether to push.
 
 ### 1b. Freshness gate — MANDATORY before opening any PR

package/dist/agent-src/contexts/override-system.md

@@ -19,12 +19,58 @@ When an agent loads any skill, rule, command, guideline, or template:
 ```
 1. Load original from .augment/{type}/{name}
 2. Check agents/overrides/{type}/{name} exists?
-   ├── YES → Read Mode header
-   │   ├── extend  → Apply original FIRST, then layer override on top
-   │   └── replace → Skip original entirely, use override only
+   ├── YES → Is the target a KERNEL or safety-floor rule?
+   │   ├── YES → replace → REFUSE. Report it. Keep the original.
+   │   │         extend  → allowed ONLY with a registered exception (below)
+   │   └── NO  → Read Mode header
+   │             ├── extend  → Apply original FIRST, then layer override on top
+   │             └── replace → Skip original entirely, use override only
    └── NO  → Use original unchanged
 ```
 
+## The non-overridable class
+
+```
+A KERNEL OR SAFETY-FLOOR RULE MAY BE TIGHTENED, NEVER REPLACED OR RELAXED.
+A `replace`-MODE OVERRIDE ON ONE IS REFUSED AND REPORTED — NEVER SILENTLY APPLIED.
+AN `extend` ON ONE REQUIRES A REGISTERED, JUSTIFIED EXCEPTION.
+```
+
+The nine kernel rules — `agent-authority`, `ask-when-uncertain`, `commit-policy`,
+`direct-answers`, `language-and-tone`, `no-cheap-questions`,
+`non-destructive-by-default`, `scope-control`, `verify-before-complete` — plus
+anything carrying `tier: safety-floor`, are not replaceable. Dropping an empty
+file at `agents/overrides/rules/non-destructive-by-default.md` must not remove
+the Hard Floor.
+
+**Why not a blanket ban.** Legitimate tightening exists, and this package does
+it: its own `verify-before-complete` override adds a mandatory-Playwright clause
+for UI changes. Banning the name would forbid a change that makes the floor
+*stronger*. So direction matters, not identity — and since no linter can prove
+"relaxes" versus "legitimately narrows" from prose, `extend` is the machine-
+checkable proxy for tightening and the registry carries the human judgement.
+
+**The exception registry.** An `extend` override on a kernel or safety-floor rule
+requires an entry in `agents/overrides/kernel-exceptions.yml`:
+
+```yaml
+exceptions:
+  - rule: verify-before-complete
+    mode: extend
+    justification: "Ships a browser UI; code-only tests cannot prove what renders."
+    approved_by: maintainer
+```
+
+**Honest limit — read this before trusting the class.** This is a norm with a
+partial gate, and saying so is the point. The override layer is resolved by the
+*agent reading these instructions*, not by a loader, so an `extend` block that
+says "ignore everything above" is not mechanically detectable — and nothing here
+stops a consumer relaxing a rule through another channel (a persona file,
+host-level config, a direct instruction). What the gate does cover is this
+package's own authoring surface: a `replace`-mode kernel override, or an
+unregistered kernel exception, fails deterministically. Everything else is
+reported, not claimed as enforced.
+
 ## Directory Mapping
 
 ```
@@ -93,7 +139,9 @@ The original is loaded first. The override adds, modifies, or removes specific p
 
 ## Mode: replace
 
-The original is completely ignored. The override is the sole source of truth.
+The original is completely ignored. The override is the sole source of truth —
+**except for kernel and safety-floor rules, where `replace` is refused outright**
+(see "The non-overridable class" above).
 
 **Use when:**
 - The shared skill/rule fundamentally doesn't fit the project
@@ -101,6 +149,24 @@ The original is completely ignored. The override is the sole source of truth.
 
 **Best practice:** Must be self-contained and complete. No references to the original.
 
+**Note the update cost.** A whole-file replacement freezes that file at the
+version you forked it from: later fixes to the original — including security
+fixes — stop reaching you, silently, because your copy wins on name match
+forever. Prefer `extend`, which keeps the rest of the original in the update
+flow. This is the same silent-drift failure the deploy-tiering discussion names.
+
+## Citation obligation
+
+Every override carries, directly under its Mode header, one line naming what it
+overrides and why:
+
+```markdown
+> Overrides: verify-before-complete §Turn-completion — ships a browser UI; code-only tests cannot prove what renders.
+```
+
+Without it the layer is usable but not auditable: a reviewer six months later
+cannot tell an intentional narrowing from an accident. No reason, no override.
+
 ## Agent Behavior
 
 Agents **must** check for overrides before applying any shared resource:
@@ -111,6 +177,10 @@ Agents **must** check for overrides before applying any shared resource:
 4. Before reading a guideline → check `agents/overrides/guidelines/{lang}-{name}.md`
 5. Before using a template → check `agents/overrides/templates/{name}.md`
 
+**Before honouring an override on a rule, check the non-overridable class
+first.** A `replace` on a kernel or safety-floor rule is refused and reported to
+the user — it is never silently dropped and never silently applied.
+
 ## When to Create vs. When to Fix
 
 | Situation | Action |
@@ -155,7 +225,7 @@ When a project using this package wants to **optimize** a shared rule or skill:
 
 ### Anti-patterns
 
-- Keeping the override after upstream merge → → drift
+- Keeping the override after upstream merge → causes drift
 - Submitting only the condensed version → breaks source-of-truth workflow
 - Submitting project-specific behavior as universal improvement
 - Forgetting to create the PR → improvement stays siloed

package/dist/agent-src/rules/context-hygiene.md

@@ -12,6 +12,8 @@ routes_to:
   - "guideline:agent-infra/context-hygiene-mechanics"
 workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
 packs: [meta]
+enforced_by:
+  - "hook:context-hygiene"
 ---
 
 # Context Hygiene

package/dist/agent-src/rules/doc-screenshot-hygiene.md

@@ -0,0 +1,97 @@
+---
+type: "auto"
+tier: "2a"
+description: "Screenshots for docs — anonymize sensitive data before shipping; data-bearing shots are human-gated (published egress); terminal/CLI/IDE screenshots forbidden"
+triggers:
+  - keyword: "screenshot"
+  - keyword: "screenshots"
+  - keyword: "screen capture"
+  - keyword: "screen grab"
+  - keyword: "admin panel screenshot"
+  - keyword: "dashboard screenshot"
+  - keyword: "docs site"
+  - keyword: "Starlight"
+  - phrase: "add a screenshot"
+  - phrase: "screenshot for the docs"
+  - phrase: "screenshot in the readme"
+  - phrase: "embed an image in the docs"
+  - phrase: "put a screenshot"
+  - phrase: "generate a docs site"
+  - phrase: "capture the ui"
+  - path_prefix: "docs/media/"
+routes_to:
+  - "skill:screenshot-hygiene"
+applies_to_user_types:
+  - "all"
+workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
+packs: [meta]
+---
+
+# Doc-Screenshot Hygiene
+
+Agents may create screenshots for documentation when genuinely useful (a docs
+site, feature docs, a README visual) and embed them. But a screenshot is an
+opaque artifact that can carry **real PII, secrets, or revealing local paths**
+straight into shipped, hosted, committed docs — an irreversible published egress.
+This rule governs the anonymization discipline before any screenshot ships. Full
+workflow: [`screenshot-hygiene`](../skills/screenshot-hygiene/SKILL.md).
+
+## The Iron Law
+
+```
+A SHIPPED SCREENSHOT WITH UNREDACTED SENSITIVE DATA IS AN
+IRREVERSIBLE PUBLISHED EGRESS. NEVER SHIP ONE.
+ANONYMIZE BEFORE IT SHIPS — REAL NAMES, ADDRESSES, BIRTHDATES, TOKENS,
+SECRETS, REAL EMAILS, IDENTITY-REVEALING LOCAL PATHS.
+DETECTION IS A HELPER, NEVER A CLEARANCE. THE GATE IS HUMAN CONFIRMATION.
+A DATA-BEARING SCREENSHOT EMBED IS GATED PER non-destructive-by-default
+(THIS-TURN CONFIRMATION). TERMINAL / CLI / IDE SCREENSHOTS ARE FORBIDDEN.
+WHEN UNCERTAIN → REDACT OR REFUSE. NEVER SHIP-AND-HOPE.
+```
+
+## The anonymization taxonomy
+
+**Always redact / refuse (sensitive):** real person's name, postal address,
+birthdate, phone; passwords, API tokens, secrets, cookies, bearer tokens,
+private keys; real email addresses (anything not `@example.{com,org,net}` / a
+fake-data domain); absolute local paths revealing a real identity
+(`/Users/<realname>/…`); client / customer / project identifiers; internal
+hostnames (`*.internal`); anything GDPR-sensitive; aggregate counts or data
+tells that reveal real users.
+
+**Allowed (no redaction):** well-known fake data (Max Mustermann, Musterstraße,
+`@example.com`); the maintainer's OWN public handle shown as a username (e.g.
+a handle in an admin panel — it is already public), and a path rooted at that
+public handle. The maintainer's **real name is never allowed**, even co-located
+with the handle. The safe set is `screenshots.identity_allowlist` (default
+empty → every identity is human-decided).
+
+## Risk tiers — symmetric friction
+
+- **Illustrative / no data** (architecture diagrams, logos, icons, wireframes,
+  placeholder-only UI): embed with a one-line justification. Low friction.
+- **Data-bearing** (dashboards, admin panels, forms/lists with content, anything
+  showing real-looking data): run the hygiene workflow, then **this-turn human
+  confirmation before embed** (per [`non-destructive-by-default`](non-destructive-by-default.md)).
+- **Terminal / CLI / IDE output**: **forbidden** as screenshots (highest leak
+  vector — absolute paths, env tokens). Use a text code block with text
+  redaction. Set `screenshots.forbid_terminal_capture` (default `true`).
+
+## When it fires — and when NOT
+
+**Fires** when creating/embedding a screenshot into documentation (docs site,
+README, feature docs) or when a screenshot lands under `docs/media/`.
+
+**Does NOT fire** on: image *generation* (see `media-governance-routing`,
+`image-likeness-and-rights`); a user-supplied screenshot used only as a design
+spec to compare against (see `design-fidelity`, `cross-source-consistency`);
+non-doc surfaces.
+
+## See also
+
+- [`screenshot-hygiene`](../skills/screenshot-hygiene/SKILL.md) — the decide → capture → detect → redact → audit → embed workflow + the human-gate checklist.
+- [`non-destructive-by-default`](non-destructive-by-default.md) — the published-egress Hard Floor a data-bearing embed routes into.
+- [`domain-safety-pii`](domain-safety-pii.md) — the sibling PII rule for text surfaces (drafts / logs / exports); screenshots are the visual surface.
+- [`lethal-trifecta-guard`](lethal-trifecta-guard.md) — a screenshot is the private-data + egress legs; the human gate is the egress control.
+- [`readme-writing`](../skills/readme-writing/SKILL.md) — flags unrequested data-bearing screenshots.
+- [`image-analyser`](../skills/image-analyser/SKILL.md), [`image-editing`](../skills/image-editing/SKILL.md) — the OCR-detect / region-redact helpers.

package/dist/agent-src/rules/domain-safety-pii.md

@@ -164,3 +164,4 @@ PreToolUse hook — see `agents/settings/contexts/legal-privilege-probe.md`.
 - `skill:logging-monitoring`, `skill:secrets-management` — technical surfaces.
 - `domain-safety-disclaimer` — companion advisory rule.
 - `domain-safety-retention` — companion retention rule.
+- `doc-screenshot-hygiene` — the visual sibling: PII inside a **screenshot** shipped into docs (this rule covers text drafts / logs / exports, not images).

package/dist/agent-src/rules/downstream-changes.md

@@ -45,7 +45,36 @@ After editing any file, search for **all** of these:
 | **Config / bindings** | Search service providers, config files | Update class references in DI bindings |
 | **API schemas / OpenAPI** | Check controller attributes | Update if response structure changed |
 | **Routes** | Search `routes/` for controller references | Update after controller rename/move |
-| **Documentation** | Search `agents/`, `docs/` for references | Update if behavior or API changed |
+| **Documentation** | Search `agents/`, `docs/`, `README`, examples for references | Update the doc that **describes** the changed surface — see Doc-Impact below |
+
+## Doc-Impact — docs follow code (same change)
+
+```
+A CHANGE TO A PUBLIC SURFACE IS INCOMPLETE UNTIL THE DOC THAT
+DESCRIBES IT IS UPDATED IN THE SAME CHANGE. A DOC MAKING A CLAIM
+THE CODE NOW CONTRADICTS IS A BROKEN CHANGE, NOT A STYLE NIT.
+```
+
+**Public surfaces** whose change triggers a doc update: HTTP route /
+endpoint · exported function / class signature · CLI command or flag ·
+config / settings key · env var · DB schema or migration · event
+payload. Update the doc that describes it — README, API / OpenAPI docs,
+AGENTS.md, code examples, CHANGELOG — in the same commit.
+
+**Drift = a falsifiable-claim contradiction**, not incompleteness. Fire
+when a reader following the doc would be misled: an endpoint that no
+longer exists, a wrong return type, a renamed key, a broken example. Do
+**not** fire on "the doc could be more detailed" — completeness is a
+quality nit, not drift.
+
+**Escape hatch** (no false-positive fatigue): refactor-only / no
+public-surface change → no doc obligation. If a surface changed but
+genuinely needs no doc edit, state the one-line reason instead of
+editing a doc to satisfy the rule.
+
+Detection + the framework-agnostic surface→doc map (Laravel / Symfony /
+Next.js / Python / Go) live in [`agent-docs-writing`](../skills/agent-docs-writing/SKILL.md)
+§ Doc-Impact — run it after every code change.
 
 ## Breaking changes
 
@@ -78,3 +107,4 @@ After completing all downstream changes:
 3. **No broken types / signatures** — project's type-checker (PHPStan / Psalm, TypeScript, mypy / pyright, `go vet`, `cargo check`).
 4. **No stale references** — grep for the old name / namespace / import path to confirm zero results.
 5. **No own-orphans** — the same sweep applied to the new diff: identifiers whose last reference disappeared in a file this diff touched are removed in the same diff (see [`minimal-safe-diff § Own-orphan cleanup`](minimal-safe-diff.md#own-orphan-cleanup)); pre-existing dead code stays.
+6. **No doc drift** — a public surface changed this diff has its describing doc updated (or the one-line no-doc-needed reason stated), per Doc-Impact above.

package/dist/agent-src/rules/external-code-graph-interop.md

@@ -23,15 +23,20 @@ packs: [meta]
 Some repos commit a pre-built code-intelligence index — a `graph.json`-shaped
 artifact or a SCIP index (`index.scip`, `*.scip`). When one exists, it already
 answers "who calls X", "where is Y used", "what does this import" far more
-precisely than a fresh `grep`. This suite is an **orchestrator, not a
-competitor**: query the existing index first.
+precisely than a fresh `grep`. This suite is an **orchestrator first, owner
+where it wins** (ADR-124): query a consumer-shipped index when it is present
+and fresh; where none is shipped or ours is measurably better, the suite's own
+native code-graph engine (default-off, benchmark-gated) covers the gap. Either
+way — query first, grep as fallback, and name which source answered.
 
 ## The rule
 
 ```
 REPO SHIPS A CODE-GRAPH INDEX (graph.json-shaped OR a SCIP index)
 → QUERY IT FIRST FOR CODEBASE-STRUCTURE QUESTIONS. GREP IS THE FALLBACK,
-NOT THE FIRST MOVE. NEVER REBUILD WHAT THE INDEX ALREADY ANSWERS.
+NOT THE FIRST MOVE. NEVER REBUILD A FRESH CONSUMER-SHIPPED INDEX.
+NO FRESH INDEX SHIPPED → THE NATIVE ENGINE MAY BUILD ONE (ADR-124); STILL
+GREP-FALLBACK FOR WHAT THE GRAPH DOES NOT ANSWER, AND SAY WHICH SOURCE ANSWERED.
 ```
 
 ## When it fires
@@ -58,6 +63,11 @@ AND the repo contains a detectable index:
 
 ## See also
 
+- [`code-intelligence`](../skills/code-intelligence/SKILL.md) — the executable
+  routing skill: `code_graph detect|query|affected|path` over the native engine
+  or a consumer-shipped index, grep as the stated fallback. On hook-capable
+  hosts the PreToolUse `code-graph` nudge surfaces this once per session; on
+  instruction-file hosts this rule is the surface.
 - [`discovery_graph`](../scripts/discovery_graph.ts) — this suite's OWN artefact
   relation-graph (`affected`/`explain`); the external code-graph is the
   *source-code* analogue this rule defers to for code questions.

package/dist/agent-src/rules/framework-neutrality-in-generic-skills.md

@@ -32,6 +32,8 @@ routes_to:
   - "guideline:agent-infra/framework-neutrality-patterns"
 workspaces: [agent-config-maintainer]
 packs: [meta]
+enforced_by:
+  - "validator:src/scripts/lint_framework_leakage.ts"
 ---
 
 # framework-neutrality-in-generic-skills

package/dist/agent-src/rules/git-history-discipline.md

@@ -28,6 +28,8 @@ routes_to:
   - "skill:git-workflow"
 workspaces: [engineering]
 packs: [engineering-base]
+enforced_by:
+  - "hook:block-no-verify"
 ---
 
 # Git History Discipline

package/dist/agent-src/rules/language-and-tone.md

@@ -9,6 +9,8 @@ validator_ignore:
     reason: "Rule scopes the .md-English mandate to the authoring tree."
 workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
 packs: [meta]
+enforced_by:
+  - "validator:src/scripts/check_md_language.ts"
 ---
 
 # Language and Tone

package/dist/agent-src/rules/lethal-trifecta-guard.md

@@ -14,6 +14,8 @@ triggers:
   - phrase: "read the file and post"
 workspaces: [engineering]
 packs: [engineering-base]
+enforced_by:
+  - "validator:src/scripts/lint_skill_frontmatter_safety.ts"
 ---
 
 # Lethal-Trifecta Guard
@@ -84,3 +86,4 @@ backstop.
 - [`non-destructive-by-default`](non-destructive-by-default.md) — the human-in-the-loop egress floor.
 - [`threat-modeling`](../skills/threat-modeling/SKILL.md) — abuse-case enumeration.
 - [`domain-safety-pii`](domain-safety-pii.md) § Surface 4 — legal privilege markers extend this egress gate (legal pack); a privileged document on an outbound path is blocked pending explicit confirmation.
+- [`doc-screenshot-hygiene`](doc-screenshot-hygiene.md) — a screenshot embedded into shipped docs is private-data + egress on one path; the human gate on a data-bearing embed is the egress control.

package/dist/agent-src/rules/media-governance-routing.md

@@ -28,6 +28,8 @@ validator_ignore:
     reason: "Rule contrasts project-local placement with the .agent-src.uncondensed/rules/ alternative — mentioning the path is the argument."
 workspaces: [agent-config-maintainer, engineering, gtm]
 packs: [ai-image, ai-video]
+enforced_by:
+  - "validator:src/scripts/lint_media_policy_linkage.ts"
 ---
 
 # Media Governance Routing

package/dist/agent-src/rules/minimal-safe-diff.md

@@ -13,6 +13,8 @@ routes_to:
   - "guideline:agent-infra/minimal-safe-diff-mechanics"
 workspaces: [engineering]
 packs: [engineering-base]
+enforced_by:
+  - "hook:minimal-safe-diff"
 ---
 
 # Minimal Safe Diff

package/dist/agent-src/rules/no-roadmap-references.md

@@ -19,6 +19,9 @@ validator_ignore:
     reason: "Rule contrasts the authoring tree with transient layers."
 workspaces: [agent-config-maintainer]
 packs: [meta]
+enforced_by:
+  - "validator:src/scripts/check_no_roadmap_refs.ts"
+  - "validator:src/scripts/check_council_references.ts"
 ---
 
 # No Transient References from Stable Artifacts

package/dist/agent-src/rules/non-destructive-by-default.md

@@ -7,6 +7,8 @@ load_context:
   - ../contexts/authority/destructive-mechanics.md
 workspaces: [engineering]
 packs: [engineering-base]
+enforced_by:
+  - "none"
 ---
 
 # Non-Destructive by Default
@@ -57,3 +59,21 @@ Applies on every surface — web, Skills API, any cloud agent. No "cloud overrid
 ## See also
 
 [`autonomous-execution`](autonomous-execution.md) · [`commit-policy`](commit-policy.md) · [`scope-control`](scope-control.md) · [`user-interaction`](user-interaction.md).
+
+## Enforcement — stated honestly (`enforced_by: none`)
+
+This floor has **no mechanical backstop**, and pretending otherwise would be the
+failure it exists to prevent. No script can enforce "ask before you deploy" — the
+obligation is to pause and surface, and the only thing that observes it is the
+human in the loop. Adjacent hooks (`block-no-verify`) guard hook-bypass, not
+destructive intent; claiming them here would inflate coverage, so they are not
+claimed.
+
+So this rule is load-bearing **and** unenforced. It is carried by the model
+honouring it — which is why it is a kernel rule, why it is short, and why it is
+counted as uncovered in the enforcement-coverage report rather than excluded
+from it.
+
+## See also
+
+[`autonomous-execution`](autonomous-execution.md) · [`commit-policy`](commit-policy.md) · [`scope-control`](scope-control.md) · [`user-interaction`](user-interaction.md).