@event4u/agent-config 9.7.0 → 9.9.0

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/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: `agent-config 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/history-discipline.md

@@ -0,0 +1,80 @@
+---
+type: "auto"
+tier: "2a"
+description: "Change history done right — audit coverage, cheapest-sufficient tier (default: row-level audit log; event sourcing only by waiver), audit hygiene + privacy interlocks."
+triggers:
+  - keyword: "audit"
+  - keyword: "audit log"
+  - keyword: "activity log"
+  - keyword: "history"
+  - keyword: "event sourcing"
+  - keyword: "changelog"
+  - phrase: "who changed"
+  - phrase: "wer hat was"
+  - phrase: "track changes"
+  - phrase: "change history"
+routes_to:
+  - "skill:history-design"
+workspaces: [engineering]
+packs: [history-discipline]
+trust:
+  level: professional
+---
+
+# History Discipline
+
+Pack floor for the `history-discipline` pack (default-off; auto-activates
+when the pack is installed). Agents get history wrong in both directions:
+missing entirely on data that needs it, or over-built as event sourcing
+where a row-level log suffices — and audit tables that themselves grow
+without bound.
+
+## The Iron Law
+
+```
+MUTATIONS ON AUDIT-SCOPED DATA EMIT WHO / WHAT / WHEN. ALWAYS.
+THE MECHANISM IS THE CHEAPEST SUFFICIENT TIER — DEFAULT: ROW-LEVEL
+AUDIT LOG. EVENT SOURCING ONLY WITH AN EXPLICIT ARCHITECTURE WAIVER.
+THE AUDIT TABLE OBEYS THE SAME GROWTH BUDGET AS EVERY OTHER TABLE.
+AUDIT RECORDS INHERIT THE PRIVACY OBLIGATIONS OF THE DATA THEY DESCRIBE.
+A LOSSY AUDIT TRAIL IS WORSE THAN NONE.
+```
+
+## Rule surface
+
+- **R-B1 audit-coverage** — mutations on declared audit-scoped models
+  emit who/what/when (actor id, diff or event, timestamp, correlation
+  id) (F8; checked by `lint_persistence` against the declared scope).
+- **R-B2 history-tier-selection** — the tier matrix is normative
+  (Tier 0 `updated_by` columns → Tier 1 row-level audit log → Tier 2
+  temporal tables → Tier 3 event sourcing). **Default: Tier 1.** Tier 3
+  requires an explicit architecture waiver — never upgrade unprompted.
+  The matrix and interlock walkthrough live in
+  [`history-design`](../skills/history-design/SKILL.md).
+- **R-B3 audit-table-hygiene** — audit storage indexed on
+  `(auditable_type, auditable_id, created_at)`; JSON diffs, not full-row
+  copies, where a diff suffices.
+- **R-B4 privacy-interlock** — a GDPR Art. 17 deletion/anonymization path
+  must exist for audit records before the mechanism ships.
+- **R-B5 reliable-history-interlock** — audit capture is same-transaction
+  (Tier-1 default: observer + cheap single insert) OR outbox/afterCommit
+  with a durable queue when offloaded — per
+  [`scale-discipline`](scale-discipline.md) R-A10/R-A11.
+
+## When NOT to fire
+
+- Git/VCS history questions (that is `git-workflow` territory).
+- Retention-duration policy questions ("how long may we keep X") — route
+  to `domain-safety-retention`; this rule owns the capture mechanism,
+  not the legal floor.
+
+## See also
+
+- [`history-design`](../skills/history-design/SKILL.md) — the tier
+  matrix walkthrough + decision artifact.
+- [`scale-discipline`](scale-discipline.md) — R-A7 growth budget and
+  R-A10/R-A11 reliability primitives this pack builds on.
+- [`domain-safety-retention`](domain-safety-retention.md) — jurisdiction
+  retention floors the R-A7 policy must respect.
+- [`domain-safety-pii`](domain-safety-pii.md) — PII discipline for what
+  audit diffs may contain.

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
@@ -70,6 +73,6 @@ Trigger-set above activates this routing on demand, independent of the disciplin
 - [`roadmap-progress-sync`](roadmap-progress-sync.md) — sync dashboard
   on roadmap touch
 - [`source-of-truth`](source-of-truth.md) — edit
-  `.agent-src.uncondensed/`
+  `src/`
 - [`ai-council`](../skills/ai-council/SKILL.md) — output path
   convention and convergence-summary format

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).

package/dist/agent-src/rules/onboarding-gate.md

@@ -8,6 +8,8 @@ triggers:
   - path_prefix: ".agent-settings.yml"
 workspaces: [agent-config-maintainer, construction, engineering, finance, founder, gtm, legal-review-prep, ops, product, small-business]
 packs: [meta]
+enforced_by:
+  - "hook:onboarding-gate"
 ---
 
 # Onboarding Gate

package/dist/agent-src/rules/output-discipline.md

@@ -10,6 +10,8 @@ triggers:
   - phrase: "similar pattern"
 workspaces: [engineering]
 packs: [engineering-base]
+enforced_by:
+  - "validator:src/scripts/lint_output_slop.ts"
 ---
 
 # Output Discipline

package/dist/agent-src/rules/persona-governance.md

@@ -25,6 +25,8 @@ validator_ignore:
     reason: "Rule documents the persona authoring tree (.agent-src.uncondensed/personas/) as the deprecation-path operand."
 workspaces: [agent-config-maintainer]
 packs: [meta]
+enforced_by:
+  - "validator:src/scripts/lint_persona_governance.ts"
 ---
 
 # Persona Governance

package/dist/agent-src/rules/php-coding.md

@@ -10,6 +10,7 @@ routes_to:
   - "guideline:php/php-coding-patterns"
 workspaces: [engineering]
 packs: [php]
+roles: [developer, reviewer]
 trust:
   level: professional
 install:

package/dist/agent-src/rules/preservation-guard.md

@@ -14,6 +14,9 @@ validator_ignore:
     reason: "Rule references the authoring tree as the operand of condensation/preservation."
 workspaces: [agent-config-maintainer]
 packs: [meta]
+enforced_by:
+  - "validator:src/scripts/check_condensation.ts"
+  - "validator:src/scripts/skill_linter.ts"
 ---
 
 # Preservation Guard

package/dist/agent-src/rules/reviewer-awareness.md

@@ -12,6 +12,7 @@ routes_to:
   - "skill:review-routing"
 workspaces: [agent-config-maintainer, engineering]
 packs: [meta]
+roles: [reviewer]
 ---
 
 # Reviewer Awareness

package/dist/agent-src/rules/roadmap-ci-steps-policy.md

@@ -26,6 +26,7 @@ validator_ignore:
     reason: "Rule reads quality.local_auto_run from .agent-settings.yml; naming the file is the contract."
 workspaces: [agent-config-maintainer, engineering]
 packs: [meta]
+roles: [planner]
 ---
 
 # Roadmap CI-Steps Policy

package/dist/agent-src/rules/roadmap-progress-sync.md

@@ -11,6 +11,9 @@ routes_to:
   - "guideline:agent-infra/roadmap-progress-mechanics"
 workspaces: [agent-config-maintainer, engineering]
 packs: [meta]
+roles: [planner]
+enforced_by:
+  - "hook:roadmap-progress"
 ---
 
 # Roadmap Progress Sync
@@ -73,6 +76,12 @@ Before sending any reply that landed roadmap work:
 
 1. Did this reply land a step (code/doc saved + verification passed)?
 2. Is its checkbox flipped to `[x]` / `[~]` / `[-]` in `agents/roadmaps/<file>.md`? If no → flip, then continue.
+2b. Roadmap created/updated from an `agents/tmp/` inbox file this reply? If
+   yes → `mv` it to `agents/tmp.old/` NOW, same reply (per
+   `agents-layout § User Inbox Workflow`); point the Source line at
+   `agents/tmp.old/<name>`. Consumed inbox file left in `agents/tmp/` = rule
+   violation, not tidiness. Move ONLY the explicitly named input file(s) —
+   never sweep the rest of the inbox.
 3. Is regen due now per `roadmap.dashboard_regen_cadence`?
    - `per_step` → yes, always.
    - `every_5_steps` → yes when this is the 5th, 10th, … closed step in the run, or the last step of the reply.

package/dist/agent-src/rules/scale-discipline.md

@@ -0,0 +1,92 @@
+---
+type: "auto"
+tier: "2a"
+description: "Scale-safe persistence — indexes with the queries, bounded reads, safe migrations, growth budgets, thin request path, durable async. Pattern lints gate; heuristics advise."
+triggers:
+  - keyword: "migration"
+  - keyword: "index"
+  - keyword: "N+1"
+  - keyword: "eager load"
+  - keyword: "pagination"
+  - keyword: "queue"
+  - keyword: "job"
+  - keyword: "retention"
+  - keyword: "schema"
+  - keyword: "SELECT *"
+  - phrase: "will this scale"
+  - phrase: "review this migration"
+  - phrase: "add a table"
+  - phrase: "send an email on"
+routes_to:
+  - "skill:schema-review"
+workspaces: [engineering]
+packs: [scale-discipline]
+trust:
+  level: professional
+---
+
+# Scale Discipline
+
+Pack floor for the `scale-discipline` pack (default-off; auto-activates
+when the pack is installed). AI agents produce functionally correct but
+scale-hostile persistence code — this rule binds the failure classes to
+deterministic pattern lints where possible and to review advice where not.
+
+## The Iron Law
+
+```
+INDEXES SHIP WITH THE QUERIES THAT NEED THEM. READS ARE BOUNDED.
+MIGRATIONS ARE REVERSIBLE. APPEND-ONLY TABLES DECLARE RETENTION.
+THE SYNC HANDLER DOES ONLY: VALIDATE → PERSIST → DISPATCH → RESPOND.
+MUST-NOT-LOSE WORK GOES THROUGH A DURABLE QUEUE, AFTER COMMIT.
+A HEURISTIC FINDING IS ADVICE, NEVER A CI FAILURE.
+EVERY WAIVER CARRIES A NON-EMPTY REASON.
+```
+
+## Rule surface (tier per the spike-verdict record: `lint_persistence` gates where a spike PASSED; unspiked rules — R-A4, R-A9, R-A11 — are advice/normative only)
+
+- **R-A1 query-shape** — no query calls inside iteration over query
+  results; batch/eager-load instead (F1).
+- **R-A2 index-parity** — every FK and every WHERE/ORDER BY column has an
+  index or an explicit `// no-index: <reason>` waiver (F2).
+- **R-A3 bounded-reads** — list endpoints paginate or declare a bound; no
+  `SELECT *` on production paths (F3).
+- **R-A4 reference-over-copy** — new columns duplicating FK-reachable data
+  need a waiver (F4) — *advice tier*.
+- **R-A6 migration-safety** — reversible; NOT NULL needs a default;
+  concurrent index creation where the driver supports it; no destructive
+  op without a waivered reason (F6).
+- **R-A7 growth-budget** — append-only tables declare retention: TTL,
+  pruning job, partition rotation, or archive path (F7).
+- **R-A8 thin-request-path** — offloadable-catalog calls (mail, PDF/media,
+  third-party HTTP, bulk mutations, ML inference, outbound webhooks)
+  inside a request handler fail lint unless waived
+  `// sync-required: <reason>` (F9). The catalog is a positive list of
+  expensive call classes — a single indexed insert never needs a job.
+- **R-A9 event-decoupling** — side effects react to domain events or
+  observers via (queued) listeners; the mutating call site does not
+  enumerate its consumers (F10) — *advice tier*.
+- **R-A10 durable-async** — must-not-lose work (promised emails, billing,
+  audit fan-out) goes through a durable queue with retry/backoff and a
+  dead-letter path — never in-process fire-and-forget. No broker? Use a
+  DB-backed queue driver or a documented `// accepted-loss: <reason>`
+  waiver — never a silent in-process fallback (F11).
+- **R-A11 commit-ordering** — async dispatch that reads mutated state
+  fires after commit (Laravel `afterCommit` / `ShouldDispatchAfterCommit`;
+  generic: transactional outbox).
+
+## When NOT to fire
+
+- No persistence surface in the change (docs, UI-only, config).
+- Runtime performance analysis of live traffic — that is APM territory,
+  not artifact linting.
+
+## See also
+
+- [`schema-review`](../skills/schema-review/SKILL.md) — runs the linter,
+  emits the gap table + neutral waiver-density report.
+- [`history-discipline`](history-discipline.md) — sibling pack floor;
+  audit tables fall under R-A7 here.
+- [`architecture`](architecture.md) — thin handlers; this rule is its
+  persistence-shaped enforcement.
+- `src/scripts/lint_persistence.ts` — the deterministic backstop.

package/dist/agent-src/rules/secret-vcs-guard.md

@@ -0,0 +1,106 @@
+---
+type: "auto"
+tier: "2a"
+alwaysApply: false
+description: "About to write a credential into a tracked file or stage/commit one in any VCS (git/svn/hg) — STOP, show the match, ask, offer alternatives; never silently commit, never silently strip"
+triggers:
+  - intent: "writing a credential or API key into a file"
+  - intent: "committing or staging changes that may contain a secret"
+  - keyword: "secret"
+  - keyword: "password"
+  - keyword: "credential"
+  - keyword: "api key"
+  - keyword: "token"
+  - keyword: ".env"
+  - keyword: "commit"
+  - keyword: "git add"
+  - keyword: "svn commit"
+  - keyword: "hg commit"
+  - keyword: "push"
+routes_to:
+  - "skill:secrets-management"
+validator_ignore:
+  - type: "substring"
+    pattern: "../../docs/"
+    reason: "See-also routes to docs/threat-model.md — the canonical attack-surface doc lives there by design."
+workspaces: [engineering]
+packs: [engineering-base]
+enforced_by:
+  - "validator:src/scripts/check_secret_leak.ts"
+---
+
+# Secret-in-VCS Guard
+
+A committed secret is a leaked secret. Once it reaches version control it is in
+the history, in every clone and fork, and — on a public remote — scraped by bots
+within minutes. `git rm` does not un-leak it; only rotation does. The cheapest
+moment to stop it is **before** the write. The agent is upstream of the commit,
+so the agent is the earliest gate.
+
+## The Iron Law
+
+```
+NEVER WRITE A CREDENTIAL INTO A TRACKED (OR TO-BE-TRACKED) FILE, AND NEVER
+STAGE / COMMIT CONTENT CONTAINING ONE — IN ANY VCS (git · svn · hg) —
+WITHOUT STOPPING FIRST.
+DETECT → SHOW THE MATCH (file:line · kind · why risky) → ASK → OFFER ALTERNATIVES.
+NEVER SILENTLY COMMIT A SECRET. NEVER SILENTLY STRIP ONE.
+ALREADY IN HISTORY → ROTATE FIRST. git rm DOES NOT UN-LEAK.
+```
+
+## When it fires
+
+The agent is about to (a) write/edit a value that looks like a live credential
+into a tracked or soon-to-be-tracked file, or (b) `git add` / `git commit` /
+`svn commit` / `hg commit` / push content containing one. Detection uses the
+`secret_detector` library (regex rule pack + Shannon entropy + keyword context):
+AWS/GitHub/Stripe/Google/Slack keys, PEM private keys, JWTs, DB connection URLs
+with embedded credentials, and `password=` / `api_key=` style assignments.
+
+## What to do on a `high`-confidence hit
+
+1. **STOP** — do not write, stage, or commit.
+2. **Show** the match: `file:line`, the kind, a masked preview, and why it is
+   risky. Never echo the full secret back.
+3. **Ask** via numbered options (per [`non-destructive-by-default`](non-destructive-by-default.md) +
+   [`user-interaction`](user-interaction.md)) — e.g. *move it to a secret store
+   (recommended)* / *this is a false positive, add a narrow allow-marker* /
+   *commit anyway (I understand the risk)*. Never decide for the user; never
+   auto-strip.
+4. **Offer the alternative**, tiered to context (full table in
+   [`secrets-management`](../skills/secrets-management/SKILL.md)): solo/local →
+   gitignored `.env` + committed `.env.example`; team/prod → cloud secret manager
+   or Vault/Doppler; k8s/GitOps → SOPS / Sealed Secrets; CI → OIDC over stored
+   creds.
+
+## Already committed / pushed → rotate first
+
+If the secret is already in history, lead with **rotate/revoke the credential
+now** — that is the only action that actually stops the damage. State plainly
+that `git rm` and even a history rewrite do **not** un-leak an already-pushed
+secret; then, if the user wants, point to history purge (`git filter-repo` / BFG)
+plus force-push and collaborator re-clone. See
+[`secrets-management`](../skills/secrets-management/SKILL.md).
+
+## Honesty — one layer, not the whole defense
+
+The agent-side gate is one layer and only covers what the agent writes. Recommend
+the user also enable the non-bypassable nets: the repo's CI secret-scan
+(`check_secret_leak`) and, where available, the host's push-protection.
+
+## When NOT to fire
+
+- `.env.example` / `*.sample` / `*.example` files with placeholder values.
+- A line carrying an audited allow-marker (`# secret-allow` / `// secret-allow` /
+  `<!-- secret-allow -->`) or listed in the repo `.secret-allow` file.
+- Obvious placeholders (`xxxx`, `changeme`, `your-key-here`, `<...>`), test
+  fixtures explicitly marked as such, and non-credential high-entropy strings
+  (hashes, UUIDs, lockfile digests) with no credential keyword nearby.
+
+## See also
+
+- [`secrets-management`](../skills/secrets-management/SKILL.md) — store selection, tiered alternatives, rotation contract, remediation ordering.
+- [`security-sensitive-stop`](security-sensitive-stop.md) — threat-model before editing a secrets surface (fires first, broader).
+- [`tool-safety`](tool-safety.md) — "no hidden credentials" in shipped files.
+- [`non-destructive-by-default`](non-destructive-by-default.md) — the commit/push confirmation floor this builds on.
+- [`lethal-trifecta-guard`](lethal-trifecta-guard.md) — secrets are the private-data leg of the trifecta.

package/dist/agent-src/rules/security-sensitive-stop.md

@@ -16,6 +16,8 @@ validator_ignore:
     reason: "See-also routes to docs/threat-model.md — the canonical attack-surface doc lives there by design."
 workspaces: [engineering]
 packs: [engineering-base]
+enforced_by:
+  - "none"
 ---
 
 # Security-Sensitive Stop Rule
@@ -100,4 +102,12 @@ Authorization and tenancy bugs are often invisible in logs and fire silently
 until an auditor or attacker finds them. The cheapest moment to catch them
 is before the first edit — this rule makes that the default path.
 
-See also: `threat-modeling` · `authz-review` · `data-flow-mapper` · `minimal-safe-diff` · `think-before-action` · [`untrusted-input-defense`](untrusted-input-defense.md) · [`lethal-trifecta-guard`](lethal-trifecta-guard.md) · [`docs/threat-model.md`](../../docs/threat-model.md).
+## Enforcement — stated honestly (`enforced_by: none`)
+
+No script can enforce "threat-model before you edit": obligation is a pre-edit
+reasoning step only the model observes (ADR-135 classifies it HIGH —
+model-carried, honestly uncovered). Adjacent validators (`check_secret_leak`,
+`lint_agent_security`) cover neighbouring surfaces, not this stop — claiming
+them here would inflate coverage, so not claimed.
+
+See also: `threat-modeling` · `authz-review` · `data-flow-mapper` · `minimal-safe-diff` · `think-before-action` · [`untrusted-input-defense`](untrusted-input-defense.md) · [`lethal-trifecta-guard`](lethal-trifecta-guard.md) · [`secret-vcs-guard`](secret-vcs-guard.md) · [`docs/threat-model.md`](../../docs/threat-model.md).