@event4u/agent-config 14.10.0 → 14.12.0

package/dist/agent-src/skills/js-library-packaging/scripts/check_package_surface.ts

@@ -0,0 +1,270 @@
+/**
+ * check_package_surface — read a JavaScript library's PACKAGE SURFACE and report what its
+ * own `package.json` says, without compiling anything.
+ *
+ * Scope, stated because the boundary is what keeps this useful: the subject is
+ * `package.json` **semantics** — the exports map, peer-dependency placement, the files
+ * allow-list, publish intent. It is NOT a build, not a type-check, and not proof that any
+ * bundler can produce the declared layout. A checker that grew a parser would start
+ * reporting compile errors as packaging errors, and the two have different fixes.
+ *
+ * The classification (`source-consumed` vs `built-surface`) is read from the DECLARED
+ * EXPORT TARGETS, never from the directory name. A fixture called `ui-lib-vite` is not
+ * evidence about Vite, and a directory called `buildable` is not evidence that anything
+ * builds — both council reviewers named that inference as the thing to avoid.
+ *
+ * Output is JSON on stdout. No network, no subprocess.
+ *
+ * Usage:
+ *   check_package_surface <library-root> [<library-root> …]
+ *   check_package_surface --self-test
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export type Severity = 'error' | 'warn';
+
+export interface Finding {
+    readonly code: string;
+    readonly severity: Severity;
+    readonly message: string;
+}
+
+export type Classification = 'source-consumed' | 'built-surface' | 'undeclared';
+
+export interface SurfaceReport {
+    readonly root: string;
+    readonly name: string | null;
+    readonly classification: Classification;
+    readonly findings: readonly Finding[];
+}
+
+/** Peer-only packages: a library that bundles these ships a second copy of them. */
+const PEER_ONLY = ['react', 'react-dom'] as const;
+
+const asRecord = (v: unknown): Record<string, unknown> =>
+    v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+
+/** Every string target reachable in an exports map, at any nesting depth. */
+export const exportTargets = (exportsField: unknown): string[] => {
+    const out: string[] = [];
+    const walk = (node: unknown): void => {
+        if (typeof node === 'string') {
+            out.push(node);
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (const n of node) walk(n);
+            return;
+        }
+        for (const v of Object.values(asRecord(node))) walk(v);
+    };
+    walk(exportsField);
+    return out;
+};
+
+/**
+ * Classify from the declared targets.
+ *
+ * A package whose targets all point into a source directory is source-consumed; one whose
+ * targets point at build output is a built surface. **Mixed is `undeclared`, not a guess** —
+ * a package that declares both is making a statement this check cannot resolve, and picking
+ * one silently would hide exactly the ambiguity worth reporting.
+ */
+export const classify = (targets: readonly string[]): Classification => {
+    if (targets.length === 0) return 'undeclared';
+    const built = targets.filter((t) => /(^|\/)(dist|build|lib|out)\//.test(t));
+    if (built.length === targets.length) return 'built-surface';
+    if (built.length === 0) return 'source-consumed';
+    return 'undeclared';
+};
+
+export const checkPackage = (root: string): SurfaceReport => {
+    const manifestPath = path.join(root, 'package.json');
+    let manifest: Record<string, unknown> = {};
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as Record<string, unknown>;
+    } catch {
+        return {
+            root,
+            name: null,
+            classification: 'undeclared',
+            findings: [{ code: 'no-manifest', severity: 'error', message: `no readable package.json at ${manifestPath}` }],
+        };
+    }
+
+    const findings: Finding[] = [];
+    const deps = asRecord(manifest['dependencies']);
+    const peers = asRecord(manifest['peerDependencies']);
+    const exportsField = manifest['exports'];
+    const targets = exportTargets(exportsField);
+
+    // (a) — the "invalid hook call" failure. Two copies of React in one tree break hooks at
+    // runtime with an error that names neither package, which is why this is an error and
+    // not a warning.
+    for (const p of PEER_ONLY) {
+        if (Object.prototype.hasOwnProperty.call(deps, p)) {
+            findings.push({
+                code: 'peer-as-dependency',
+                severity: 'error',
+                message: `\`${p}\` is in dependencies; a library must declare it as a peerDependency or the consumer gets two copies (the "invalid hook call" failure)`,
+            });
+        }
+    }
+
+    // (b) — legacy entry fields with no exports map: the resolution the consumer gets then
+    // depends on their bundler rather than on this manifest.
+    const hasLegacy = ['main', 'module', 'browser'].some((k) => typeof manifest[k] === 'string');
+    if (exportsField === undefined && hasLegacy) {
+        findings.push({
+            code: 'no-exports-map',
+            severity: 'warn',
+            message: 'main/module present without an exports map — the entry point resolves by bundler convention, not by declaration',
+        });
+    }
+
+    // (c) — `types` must be the FIRST key of a conditions object. Conditional exports are
+    // matched in declaration order, so a `types` key placed after `import` is skipped by
+    // resolvers that match `import` first, and the package silently ships untyped.
+    const walkConditions = (node: unknown, at: string): void => {
+        const rec = asRecord(node);
+        const keys = Object.keys(rec);
+        if (keys.includes('types') && keys[0] !== 'types') {
+            findings.push({
+                code: 'types-not-first',
+                severity: 'warn',
+                message: `\`types\` is not the first condition at \`${at}\` (order matters: a resolver matching \`${keys[0] ?? ''}\` first never sees it)`,
+            });
+        }
+        for (const [k, v] of Object.entries(rec)) {
+            if (typeof v === 'object' && v !== null) walkConditions(v, `${at}${k}/`);
+        }
+    };
+    if (exportsField !== undefined) walkConditions(exportsField, 'exports.');
+
+    // (d) — a `workspace:` range only resolves inside the workspace. Published with no
+    // `private: true` and no publishConfig, the consumer's install fails on a protocol
+    // their registry has never heard of.
+    const allDeps = { ...deps, ...asRecord(manifest['devDependencies']), ...peers };
+    const workspaceRanges = Object.entries(allDeps).filter(([, v]) => typeof v === 'string' && v.startsWith('workspace:'));
+    if (
+        workspaceRanges.length > 0 &&
+        manifest['private'] !== true &&
+        manifest['publishConfig'] === undefined
+    ) {
+        findings.push({
+            code: 'workspace-range-publishable',
+            severity: 'warn',
+            message: `${String(workspaceRanges.length)} \`workspace:\` range(s) in a package that is neither private nor carrying publishConfig — the protocol does not resolve outside the workspace`,
+        });
+    }
+
+    // A declared target that is not in the tree is the drift the whole surface rests on.
+    for (const t of targets) {
+        if (!t.startsWith('.')) continue;
+        if (!fs.existsSync(path.join(root, t))) {
+            findings.push({
+                code: 'export-target-missing',
+                severity: 'error',
+                message: `exports target \`${t}\` does not exist in the package`,
+            });
+        }
+    }
+
+    const name = typeof manifest['name'] === 'string' ? manifest['name'] : null;
+    return { root, name, classification: classify(targets), findings };
+};
+
+/** Registry item types deprecated in v4 — writing one produces an item the CLI cannot read. */
+const DEPRECATED_ITEM_TYPES = ['registry:build', 'registry:mcp'] as const;
+
+/**
+ * Check a `registry.json` (or a single `registry-item.json`) published by a library.
+ *
+ * Same subject as the manifest checks: what the file DECLARES. A registry item that lists
+ * `react` in `dependencies` reproduces the two-copies-of-React failure one layer up — the
+ * consumer's app already has React, and the item installs a second.
+ */
+export const checkRegistry = (file: string): Finding[] => {
+    let doc: Record<string, unknown> = {};
+    try {
+        doc = JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>;
+    } catch {
+        return [{ code: 'no-registry', severity: 'error', message: `no readable registry JSON at ${file}` }];
+    }
+    // Both shapes are legal: an index with `items`, or a single item.
+    const items = Array.isArray(doc['items']) ? (doc['items'] as unknown[]) : [doc];
+    const findings: Finding[] = [];
+    for (const raw of items) {
+        const item = asRecord(raw);
+        const name = typeof item['name'] === 'string' ? item['name'] : '(unnamed)';
+        const deps = Array.isArray(item['dependencies']) ? (item['dependencies'] as unknown[]) : [];
+        for (const d of deps) {
+            const dep = String(d).split('@')[0];
+            if (PEER_ONLY.includes(dep as (typeof PEER_ONLY)[number])) {
+                findings.push({
+                    code: 'registry-item-bundles-peer',
+                    severity: 'error',
+                    message: `registry item \`${name}\` lists \`${dep}\` in dependencies; the consuming app already has it, and installing a second copy is the same "invalid hook call" failure one layer up`,
+                });
+            }
+        }
+        const type = typeof item['type'] === 'string' ? item['type'] : '';
+        if (DEPRECATED_ITEM_TYPES.includes(type as (typeof DEPRECATED_ITEM_TYPES)[number])) {
+            findings.push({
+                code: 'registry-item-deprecated-type',
+                severity: 'error',
+                message: `registry item \`${name}\` uses \`${type}\`, deprecated in v4 — use \`registry:base\` or \`registry:font\``,
+            });
+        }
+    }
+    return findings;
+};
+
+const selfTest = (): number => {
+    let failed = 0;
+    const check = (label: string, cond: boolean): void => {
+        if (!cond) {
+            process.stderr.write(`❌  ${label}\n`);
+            failed += 1;
+        }
+    };
+
+    check('a source target classifies as source-consumed', classify(['./src/index.ts']) === 'source-consumed');
+    check('a dist target classifies as built-surface', classify(['./dist/index.js']) === 'built-surface');
+    check('a MIXED declaration is undeclared, never guessed', classify(['./src/index.ts', './dist/index.js']) === 'undeclared');
+    check('no targets is undeclared', classify([]) === 'undeclared');
+    check(
+        'nested conditions are all collected',
+        exportTargets({ '.': { types: './a.d.ts', import: './b.js' } }).length === 2,
+    );
+
+    process.stdout.write(
+        failed === 0 ? '✅  check_package_surface: self-test passed\n' : `❌  ${String(failed)} failure(s)\n`,
+    );
+    return failed === 0 ? 0 : 1;
+};
+
+const main = (): number => {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--self-test')) return selfTest();
+    const roots = argv.filter((a) => !a.startsWith('--'));
+    if (roots.length === 0) {
+        process.stderr.write('usage: check_package_surface <library-root> [...]\n');
+        return 2;
+    }
+    // A path ending in a registry file is checked as a registry, not as a package root —
+    // otherwise the caller has to know which of two checkers to reach for.
+    const reports = roots.map((r) =>
+        /registry(-item)?\.json$/.test(r)
+            ? { root: r, name: null, classification: 'undeclared' as Classification, findings: checkRegistry(r) }
+            : checkPackage(r),
+    );
+    process.stdout.write(`${JSON.stringify({ reports }, null, 2)}\n`);
+    return reports.some((r) => r.findings.some((f) => f.severity === 'error')) ? 1 : 0;
+};
+
+if (process.argv[1] !== undefined && process.argv[1].includes('check_package_surface')) {
+    process.exit(main());
+}

package/dist/agent-src/skills/laravel-migration/SKILL.md

@@ -13,6 +13,9 @@ trust:
 install:
   default: false
   removable: true
+triggers:
+  - phrase: "make:migration"
+  - phrase: "laravel migration"
 ---
 
 # laravel-migration

package/dist/agent-src/skills/learning-to-rule-or-skill/SKILL.md

@@ -4,6 +4,9 @@ name: learning-to-rule-or-skill
 description: "Use when a repeated learning, mistake, or successful pattern should be turned into a new rule or skill. Also use after completing a task to capture learnings from the work."
 source: project
 domain: process
+scope:
+  write: []
+  verification_reason: "execution.handler is internal, so this skill spawns no subprocess — writes happen through the agent's declared allowed_tools. No command can prove a scope the skill never executes."
 execution:
   type: assisted
   handler: internal

package/dist/agent-src/skills/lint-skills/SKILL.md

@@ -3,6 +3,9 @@ model_tier: medium
 name: lint-skills
 description: "Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata."
 domain: process
+scope:
+  write: []
+  verification_reason: "the declared command is a read-only linter: grep -c 'writeFileSync|mkdirSync|appendFileSync' src/scripts/skill_linter.ts returns 0. Absence of a write is not something a command can prove."
 execution:
   type: assisted
   handler: shell

package/dist/agent-src/skills/llm-provider-knowledge/SKILL.md

@@ -18,6 +18,9 @@ trust:
   level: experimental
 install:
   removable: true
+scope:
+  write: []
+  verification_reason: "execution declares no handler, so this skill runs nothing of its own — every write is the calling agent's, under the rules that govern it. No command can prove a scope the skill never executes."
 execution:
   type: manual
 ---

package/dist/agent-src/skills/logging-monitoring/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: medium
 name: logging-monitoring
-description: "Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers."
+description: "Use when establishing what observability a project actually has — the four Golden Signals, required signal to detected implementation to evidence, and SLI/SLO provenance."
 domain: devops
 workspaces:
   - engineering
@@ -13,93 +13,276 @@ packs:
 
 ## When to use
 
-Use when adding logging, configuring monitoring stack, or integrating Sentry/Grafana/Loki.
+Use when answering **"what does this project actually have"** for observability:
+which required signal exists, what implements it, and what evidence says so. Also
+when adding logging or wiring a monitoring stack — but the posture question comes
+first, because you cannot add the missing signal until you know which one is
+missing.
 
 Do NOT use when:
-- Creating Grafana dashboards (use `grafana` skill)
-- Dashboard design decisions (use `dashboard-design` skill)
+- Classifying an alert or writing a runbook (use `alerting-doctrine`)
+- Adjudicating a go/no-go readiness verdict (use `operational-readiness`)
+- Creating Grafana dashboards or queries (use `grafana`)
+- Dashboard layout and visualization decisions (use `dashboard-design`)
+- Hardening the host itself (use `server-hardening`)
 
-## Procedure: Add logging or monitoring
+## Golden Signals
 
-1. Read the framework's logging config for available channels (`config/logging.php` in Laravel, `LOGGING` in Django, winston/pino in Node).
-2. Check for Grafana module: `app/Modules/Grafana/`.
-3. Read `agents/` docs for module-specific logging.
+Four signals. The family is named in many places; these are the definitions.
+A posture report covers all four or records why it cannot — never four minus the
+inconvenient ones.
 
-## Monitoring stack
+### Golden Signal: Latency
 
-| Tool | Purpose | Integration |
-|---|---|---|
-| **Sentry** | Error tracking | `sentry/sentry-laravel`, `MonitoringHelper` |
-| **Grafana** | Dashboards | Connected to Loki |
-| **Loki** | Log aggregation | `itspire/monolog-loki` via Monolog |
-| **Slack** | Alert notifications | Webhook for error-level |
+**Measures** how long a served request takes, split by outcome — successful and
+failed latency are different distributions, and averaging them hides both. Read
+it as percentiles (p50 / p95 / p99), never as a mean.
 
-## Log channels
+**A missing one costs** the ability to see degradation that is not yet an outage.
+The system is up, users are leaving, and every error-rate panel is green.
 
-| Channel | Purpose |
-|---|---|
-| `stack_without_slack` | Daily file + errorlog (no Slack) |
-| `slack` | Error alerts to Slack |
-| `loki` | Send logs to Grafana Loki |
-| `loki_import_*` | Import-specific Loki with custom labels |
-| `daily` | Rotating file logs |
+**Typical detection paths** — APM transaction traces, a request-duration
+histogram, reverse-proxy or load-balancer access logs, a middleware timer.
 
-### Loki labels
+### Golden Signal: Traffic
 
-```php
-'globalLabels' => ['app' => '{project}', 'service' => '{service}', 'env' => $env],
-```
+**Measures** demand on the system — requests per second, jobs enqueued, messages
+consumed, active sessions. The denominator every other signal needs.
+
+**A missing one costs** all interpretation of the other three. Errors doubling is
+meaningless without knowing whether traffic doubled; a quiet incident and a quiet
+Sunday are indistinguishable.
+
+**Typical detection paths** — a request counter, access-log volume, queue depth
+and enqueue rate, a CDN or gateway request metric.
+
+### Golden Signal: Errors
+
+**Measures** the rate of requests that failed — explicitly (a 5xx, a raised
+exception, a dead-lettered job) or implicitly (a 200 carrying a wrong body, a
+policy-violating success). Rate, not count.
+
+**A missing one costs** the ability to distinguish a broken deploy from a slow
+one, and it is the signal most often mistaken for complete because an
+error-tracking SDK is installed. An exception tracker is not an error rate: it
+sees raised exceptions, not handled failures or wrong answers.
+
+**Typical detection paths** — error-tracking SDK events, HTTP status
+distribution, dead-letter queue depth, log-level counts at `error` and above.
+
+### Golden Signal: Saturation
+
+**Measures** how full the constrained resource is — the one that runs out first.
+Connection pool, worker slots, disk, memory, file descriptors, a third-party
+rate-limit budget. Expressed against its ceiling, which means the ceiling has to
+be known.
 
-The `service` label differentiates log types in Grafana queries.
+**A missing one costs** every early warning. Saturation is the only one of the
+four that is predictive: latency, traffic and errors report what already
+happened, saturation reports what is about to. It is also the signal most often
+absent entirely — see `scale-discipline` R-A12, which asks the finite-resource
+question at review time.
 
-### Config flags
+**Typical detection paths** — pool-utilisation gauges, queue wait time (not
+depth), host memory and disk metrics, rate-limit headers from an upstream
+provider.
 
-| Env Variable | Purpose | Default |
+## Evidence states — a threshold carries its provenance
+
+A number in a posture report is only as good as where it came from, and the
+failure this prevents is an agent-suggested SLO becoming a commitment nobody
+made. Provenance is part of the value, not a footnote.
+
+| Provenance | Meaning | May be rendered as operational |
 |---|---|---|
-| `LOG_CLIENT_SOFTWARE_REQUESTS` | Log incoming API requests to DB | `false` |
-| `LOG_EXTERNAL_API_REQUESTS` | Log outgoing external API requests | `true` |
-| `LOG_WEBHOOK_REQUESTS` | Log webhook requests to DB | `false` |
-| `LOG_CHANNEL_IMPORT` | Channel for import logs | `daily` |
+| `measured` | Observed in running telemetry | Yes |
+| `committed` | Stated in a doc, contract or SLA, not yet verified | Yes, marked unverified |
+| `proposed` | The agent suggested it | **Never** |
+| `unknown` | Inspection could not establish a result | **Never** |
+
+A `proposed` threshold stays `proposed` through every rendering. There is no
+promotion path — not "it looks right", not "the user did not object". Promotion
+requires a measurement or a stated commitment, which changes the provenance
+first and the rendering second.
 
-## Grafana/Loki dashboard rules
+Two absences that are not the same thing, and collapsing them is how a gap
+becomes invisible:
 
-- Hide Loki metadata columns: `labelTypes`, `traceID`, `traceID (field)`.
-- Use correct Loki service labels: `import_result` for final states, `import_snapshot` for cron.
-- Verify column names match data semantics.
+- **`unavailable`** — affirmatively established that the project cannot supply
+  this signal. Requires a **non-empty reason**. A recorded null.
+- **`unknown`** — nobody looked, or the look was inconclusive. Never counts as
+  compliant, never counts as green, and is not a null — it is unfinished work.
 
-## Conventions
+Reported signal count equals four minus the recorded `unavailable` nulls.
+`unknown` reduces nothing; it is an open question.
 
-→ See guideline `php/logging.md` for log levels, structured context, what to log, Sentry patterns.
+## Procedure: Establish the observability posture
+
+1. **Take the four signals as the requirement.** Latency, traffic, errors,
+   saturation. The list does not shrink to what the project happens to have.
+2. **Detect what implements each one.** Read the project rather than assuming a
+   stack: the logging config (`config/logging.php` in Laravel, `LOGGING` in
+   Django, `winston`/`pino` config in Node, `config/environments` in Rails),
+   then the metrics and APM wiring, then the dashboards and alert rules that
+   already exist. An installed SDK is evidence of a *capability*, never of a
+   *signal* — a Sentry integration does not give you latency percentiles.
+3. **Attach evidence to every claim.** One concrete artefact per signal —
+   `file:line`, a dashboard panel, a metric name, a config key. A signal with no
+   artefact is `unknown`, not present.
+4. **Record what is genuinely absent as `unavailable` plus a reason.** "No APM
+   configured, so no request-duration distribution exists" is a null. Silence is
+   not.
+5. **Mark every threshold's provenance** per the table above, before the report
+   is rendered rather than after.
+6. **Hand the normalized result on.** `alerting-doctrine` consumes it to decide
+   what earns a page; `operational-readiness` consumes it as one input to a
+   go/no-go verdict. Neither re-derives it.
 
 ### Validate
 
-- Verify log level matches severity (no `Log::error()` for info-level events).
+- Verify all four signals appear in the report — present, `unavailable` with a
+  reason, or `unknown`. Four rows, always.
+- Confirm every present signal cites a concrete artefact, not a stack guess.
+- Confirm no `proposed` or `unknown` threshold is rendered as operational.
+- Confirm `unavailable` rows carry a non-empty reason.
+- Verify log level matches severity (no `error` for handled conditions).
 - Confirm structured context is passed (not string interpolation).
 - Check that no sensitive data (passwords, tokens, PII) appears in log output.
-- Verify Sentry captures include relevant context for debugging.
 
 ## Output format
 
-1. Logging configuration or structured log statements
-2. Sentry integration with proper context and breadcrumbs
+1. A four-row signal table — signal, status, implementation, evidence artefact.
+2. Any threshold with its provenance marked.
+3. The `unavailable` nulls with their reasons, and the `unknown` rows as open
+   questions.
+
+## Examples
+
+Contract fixtures. Each pair differs **only** in the condition under test, and
+each case states the verdict it must produce. These are contract evidence for
+review, not an executable suite — no parser or runner reads them.
+
+### Missing signal — malformed vs clean
+
+```yaml
+# malformed — logs and error tracking, no saturation anywhere.
+# Scored as missing a signal, NOT as observable.
+signals:
+  latency:    { status: present, evidence: "APM: http.server.duration p95" }
+  traffic:    { status: present, evidence: "nginx access log rate" }
+  errors:     { status: present, evidence: "error-tracker project 41" }
+# saturation omitted entirely
+verdict: "missing-signal: saturation"
+reason: "no pool, memory, disk or rate-limit utilisation metric detected"
+```
+
+```yaml
+# clean — the same project with the one signal supplied.
+signals:
+  latency:    { status: present, evidence: "APM: http.server.duration p95" }
+  traffic:    { status: present, evidence: "nginx access log rate" }
+  errors:     { status: present, evidence: "error-tracker project 41" }
+  saturation: { status: present, evidence: "db_pool_in_use / db_pool_size gauge" }
+verdict: all-signals-detected
+```
+
+### Provenance — malformed vs clean
+
+```yaml
+# malformed — an agent-suggested number rendered as a commitment.
+slo:
+  name: checkout_availability
+  threshold: 99.9
+  provenance: proposed
+  operational: true      # <- promotion with no measurement and no commitment
+verdict: invalid-provenance
+```
+
+```yaml
+# clean — the suggestion stays a suggestion.
+slo:
+  name: checkout_availability
+  threshold: 99.9
+  provenance: proposed
+  operational: false
+verdict: valid-proposed-threshold
+```
+
+### Unavailable signal — malformed vs clean
+
+```yaml
+# malformed — a null with no reason is a silently dropped gap.
+signals:
+  saturation: { status: unavailable }
+verdict: invalid-unavailable-signal
+```
+
+```yaml
+# clean — the null carries why.
+signals:
+  saturation:
+    status: unavailable
+    reason: "managed runtime exposes no pool or host metrics on this plan"
+verdict: valid-unavailable-signal
+```
+
+## Detected implementation — stack-specific evidence
+
+Reached **after** detection, never before it. These are what a detected
+implementation looks like in one common stack; the neutral model above is what
+you reason from. Deep vendor material lives in the specialists, which this skill
+points at rather than absorbing.
+
+| Tool | Signal it can carry | Reached by |
+|---|---|---|
+| Error tracker (Sentry) | errors (raised only) | `sentry-integration` |
+| Grafana | any, if the metric exists | `grafana`, `dashboard-design` |
+| Loki | errors and traffic via log volume | `grafana` |
+| Slack webhook | none — a delivery channel | `alerting-doctrine` |
+
+A delivery channel is not a signal. Slack carrying error-level messages tells you
+notifications work, not that an error *rate* exists.
+
+A channel layout repeats across stacks whatever names it uses: a rotating file
+channel, an error-alert channel, an aggregation channel, and a composite that
+deliberately excludes the alert leg so a noisy job cannot page anyone. Aggregation
+labels carry app, service and environment; the **service** label is what separates
+log types in a query, and a workload needing its own labels gets its own scoped
+channel rather than a shared one. Which categories reach which channel is gated by
+config flags, not by call sites — so read the flags before concluding a category
+is unlogged.
+
+→ Log levels, structured context, what to log, and error-tracker patterns:
+guideline `php/logging.md`.
 
 ## Gotcha
 
-- Sentry has 200KB event size limit — large context gets truncated.
+- An installed SDK is a capability, not a signal — the commonest false green.
+- Queue **depth** is a traffic signal; queue **wait time** is the saturation one.
+- Saturation needs a ceiling. A utilisation number with no known limit is
+  `unknown`, not present.
+- Error trackers see raised exceptions, not handled failures or wrong answers.
+- Sentry has a 200KB event size limit — large context gets truncated.
 - Structured logging keys must be `snake_case`.
-- Don't create Loki channels without corresponding Grafana dashboard query.
+- Don't create a log channel without the query or dashboard that reads it.
 
 ## Do NOT
 
-- Do NOT use Sentry SDK directly — use `MonitoringHelper`.
-- Do NOT interpolate variables into log messages — use context array.
-- Do NOT log at `error` level for expected/handled conditions.
+- Do NOT report three signals because the fourth was inconvenient — record it as
+  `unavailable` with a reason, or as `unknown`.
+- Do NOT render a `proposed` or `unknown` threshold as operational.
+- Do NOT treat `unknown` as green, compliant, or "probably fine".
+- Do NOT infer a signal from an installed dependency.
+- Do NOT interpolate variables into log messages — use a context array.
+- Do NOT log at `error` level for expected, handled conditions.
 
 ## Auto-trigger keywords
 
 - logging
 - monitoring
-- Sentry
-- Grafana
+- observability
+- Golden Signals
+- SLI
+- SLO
 - structured logging
 - log levels

package/dist/agent-src/skills/logo-generation/SKILL.md

@@ -13,6 +13,9 @@ trust:
   level: experimental
 install:
   removable: true
+scope:
+  write: []
+  verification_reason: "execution declares no handler, so this skill runs nothing of its own — every write is the calling agent's, under the rules that govern it. No command can prove a scope the skill never executes."
 execution:
   type: manual
 ---