@event4u/agent-config 14.10.0 → 14.12.0

package/dist/agent-src/skills/alerting-doctrine/SKILL.md

@@ -0,0 +1,225 @@
+---
+model_tier: medium
+name: alerting-doctrine
+description: "Use when deciding what earns a page — the page, action and info classes stated provider-neutrally, and the rule that a page without an owner, a runbook and a first diagnostic step is malformed."
+domain: devops
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# alerting-doctrine
+
+## When to use
+
+Use when classifying an alert, reviewing an alert set, or deciding whether a
+condition should wake a human. Provider-neutral: the classes below hold whichever
+tool evaluates the rule.
+
+Do NOT use when:
+- Establishing which signals exist at all (use `logging-monitoring` first — you
+  cannot alert on a signal the project does not have)
+- Adjudicating a go/no-go verdict (use `operational-readiness`)
+- Running an incident once it has started (use `incident-commander`)
+- Building the dashboard the alert links to (use `dashboard-design`, `grafana`)
+
+## The three classes
+
+Every alert is exactly one of these. The class is decided by **what the recipient
+must do**, never by how alarming the condition sounds.
+
+| Class | Condition that earns it | Destination | Latency of response |
+|---|---|---|---|
+| `page` | A human must act **now** or the damage grows | Wakes a named human | Minutes |
+| `action` | A human must act, but the next working day is soon enough | Ticket or queue | Hours to days |
+| `info` | Nobody must act; it is context for when something else fires | Log, channel, dashboard | Never |
+
+**What earns a `page`** — all three, as a condition rather than a preference:
+
+1. **User-visible or irreversible.** Users are affected now, or damage
+   accumulates while nobody looks (data loss, budget burn, a queue filling
+   toward a ceiling).
+2. **Actionable now.** A named human can do something about it at 3am. "The
+   upstream provider is down" is not actionable unless failover is manual.
+3. **Not self-clearing.** A condition that resolves itself before a human can
+   log in is an `info` with a trend, not a page.
+
+Fail any one → it is `action` or `info`.
+
+**What a misclassification costs.** Too eager: alert fatigue, and the page that
+mattered arrives in a stream of pages that did not. Fatigue is not an
+inconvenience — it is the mechanism by which a real outage is missed, and it is
+caused by pages that were never actionable. Too shy: the condition sits in a
+channel nobody reads until a user reports it. The asymmetry is real but bounded
+in both directions, which is why the three conditions above are stated as a test
+and not as taste.
+
+## A page is malformed without all three fields
+
+```
+A PAGE THAT CANNOT NAME AN OWNER, A RUNBOOK AND A FIRST DIAGNOSTIC STEP
+IS A CONFIGURATION DEFECT, NOT A JUDGEMENT CALL.
+```
+
+| Field | What it must carry | Why it is mandatory |
+|---|---|---|
+| **owner** | A named human or an on-call rotation that resolves to one | An alert owned by "the team" is owned by nobody at 3am |
+| **runbook** | A pointer to the procedure — see the contract below | Waking someone with no procedure transfers the whole diagnosis to the least-prepared moment |
+| **first diagnostic step** | The single concrete first action | The most expensive minutes of an incident are the ones spent deciding where to look |
+
+This is checkable from the alert definition alone, which is what makes it a
+defect rather than an opinion. `action` and `info` alerts do not carry the
+obligation — nobody is being woken.
+
+## The runbook contract — deliberately lean
+
+A runbook worth paging into carries five things. More than this and it rots
+faster than the system changes; fewer and it is a link that wastes the minutes it
+was supposed to save.
+
+1. **What this alert means** — one sentence, in terms of user impact.
+2. **First diagnostic step** — the one command, query or dashboard to open. The
+   same value the alert definition carries, so the two cannot drift.
+3. **The two or three most common causes**, each with how to confirm it.
+4. **Mitigation vs fix** — how to stop the bleeding, marked separately from how
+   to repair the cause. Under a page, mitigation is the goal.
+5. **Escalation** — who is next, and the condition that triggers going to them.
+
+Explicitly **not** in a runbook: architecture background, a full topology
+diagram, anything the reader could get later. A runbook is read under time
+pressure by someone who was asleep.
+
+→ Once an incident is open, `incident-commander` owns the roles, the update
+cadence and the post-mortem obligation. This skill stops at the moment the page
+fires.
+
+## Procedure: Classify and validate an alert
+
+1. **Confirm the signal exists.** An alert on a signal `logging-monitoring`
+   scored `unavailable` or `unknown` cannot fire meaningfully. Fix the signal
+   first.
+2. **Apply the three page conditions.** User-visible or irreversible, actionable
+   now, not self-clearing. All three → `page`. Otherwise → `action` if a human
+   must eventually act, else `info`.
+3. **For a `page`, check the three mandatory fields.** Any missing → verdict
+   `malformed-alert: missing-<field>`. Do not downgrade the class to dodge the
+   obligation; a page whose fields cannot be named is either a defect to fix or
+   was never a page.
+4. **For a `page`, check the runbook against the five-item contract**, and
+   confirm its first diagnostic step matches the alert's.
+5. **Record the verdict per alert** — `valid-page-alert`, `valid-action-alert`,
+   `valid-info-alert`, or `malformed-alert: <reason>`.
+
+### Validate
+
+- Verify every `page` names an owner resolving to a single human.
+- Verify every `page` links a runbook that exists.
+- Verify every `page` carries a first diagnostic step identical to its runbook's.
+- Confirm no alert was reclassified downward purely to avoid the three fields.
+- Confirm every alert's underlying signal is `present`, not `unknown`.
+- Confirm the alert set contains no `page` that is self-clearing.
+
+## Output format
+
+1. One row per alert — name, class, verdict.
+2. For each `malformed-alert`, the missing field named explicitly.
+3. The pages, with owner, runbook pointer and first diagnostic step.
+
+## Examples
+
+Contract fixtures. Three pairs, one per mandatory field; each pair differs
+**only** in the field under test, and each case states the verdict it must
+produce. Contract evidence for review, not an executable suite.
+
+### Missing owner — malformed vs clean
+
+```yaml
+# malformed
+alert: checkout_error_rate_high
+class: page
+runbook: docs/runbooks/checkout-errors.md
+first_diagnostic_step: "open the checkout error-rate panel, last 30m"
+verdict: "malformed-alert: missing-owner"
+```
+
+```yaml
+# clean — only the owner is added
+alert: checkout_error_rate_high
+class: page
+owner: payments-on-call
+runbook: docs/runbooks/checkout-errors.md
+first_diagnostic_step: "open the checkout error-rate panel, last 30m"
+verdict: valid-page-alert
+```
+
+### Missing runbook — malformed vs clean
+
+```yaml
+# malformed
+alert: db_pool_saturation
+class: page
+owner: platform-on-call
+first_diagnostic_step: "check db_pool_in_use / db_pool_size"
+verdict: "malformed-alert: missing-runbook"
+```
+
+```yaml
+# clean — only the runbook is added
+alert: db_pool_saturation
+class: page
+owner: platform-on-call
+runbook: docs/runbooks/db-pool.md
+first_diagnostic_step: "check db_pool_in_use / db_pool_size"
+verdict: valid-page-alert
+```
+
+### Missing first diagnostic step — malformed vs clean
+
+```yaml
+# malformed
+alert: queue_wait_time_high
+class: page
+owner: platform-on-call
+runbook: docs/runbooks/queue-wait.md
+verdict: "malformed-alert: missing-diagnostic-step"
+```
+
+```yaml
+# clean — only the first diagnostic step is added
+alert: queue_wait_time_high
+class: page
+owner: platform-on-call
+runbook: docs/runbooks/queue-wait.md
+first_diagnostic_step: "open the queue wait-time panel; compare to enqueue rate"
+verdict: valid-page-alert
+```
+
+## Gotcha
+
+- Severity labels are not classes. `critical` in a tool's own vocabulary says
+  nothing about whether a human must act now.
+- A page nobody can action is the fastest route to ignoring all pages.
+- Reclassifying a page to `action` because the owner is unknown hides the defect
+  instead of fixing it.
+- An alert on a threshold with `proposed` provenance is alerting on a guess —
+  see `logging-monitoring`.
+- Queue depth alerts fire late; queue wait time fires in time.
+
+## Do NOT
+
+- Do NOT ship a `page` without an owner, a runbook and a first diagnostic step.
+- Do NOT page on a self-clearing condition.
+- Do NOT page on a signal scored `unknown`.
+- Do NOT put architecture background in a runbook — it is read under pressure.
+- Do NOT let the alert's first diagnostic step and the runbook's disagree.
+
+## Auto-trigger keywords
+
+- alert
+- alerting
+- page
+- on-call
+- runbook
+- alert fatigue
+- what earns a page

package/dist/agent-src/skills/authz-review/SKILL.md

@@ -261,7 +261,6 @@ Runtime confirmation (e.g. *"reproduce the cross-tenant read against staging"*,
   — rubric for "minimum control" recommendations.
   [csrc.nist.gov/projects/risk-management/sp800-53-controls](https://csrc.nist.gov/projects/risk-management/sp800-53-controls/release-search#!/800-53)
 - [`threat-modeling`](../threat-modeling/SKILL.md),
-  [`data-exposure-review`](../data-exposure-review/SKILL.md),
   [`judge-security-auditor`](../judge-security-auditor/SKILL.md),
   [`security`](../security/SKILL.md),
   [`security-audit`](../security-audit/SKILL.md) — sibling review / implementation skills.

package/dist/agent-src/skills/blast-radius-analyzer/SKILL.md

@@ -182,6 +182,38 @@ does not execute code, run tests, or touch the network**.
 * NEVER claim a dependency without a file:line citation from grep output
 * NEVER chase dependencies past 2nd order without explicit scope approval — flag and stop
 
+## Monorepo
+
+In a workspace repository the reach of an edit does not stop at the workspace
+that contains it. A file under `packages/ui` that three apps import has a blast
+radius of four workspaces, and the grep sweep above will not find the edge —
+the importing code says `@org/ui`, not a path.
+
+**Before editing a file in a workspace other workspaces depend on, name the
+affected set.** Ask the task runner, which computes it from the real graph:
+
+```bash
+# Turborepo — everything affected by the working tree vs the previous commit
+npx turbo run test --filter=...[HEAD^1]
+
+# Nx
+npx nx affected -t test
+```
+
+`...[HEAD^1]` is the dependents form: `...` ahead of the selector means "and
+everything that depends on it". Without it you get the changed package alone,
+which is the answer that looks right and misses the point.
+
+**With no runner installed**, walk it in reverse from the manifests: find the
+edited file's owning workspace `name`, then grep every other workspace's
+`package.json` for that name. Those are the first-order dependents; repeat once
+for second order, and stop there per the 2nd-order rule above.
+[`monorepo-workspace`](../monorepo-workspace/SKILL.md) § 4 prints that graph.
+
+Report the affected set as workspace names with the manifest that declares each
+edge, exactly as the reach table above reports file:line — an affected set
+without its citing edge is the same unverifiable claim in coarser units.
+
 ## References
 
 - **Martin Fowler — "Refactoring: Improving the Design of Existing Code"** (2018)

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

@@ -13,6 +13,9 @@ trust:
   level: professional
 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/brand-asset-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
 ---

package/dist/agent-src/skills/brand-audit/SKILL.md

@@ -13,6 +13,9 @@ trust:
   level: professional
 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/brand-identity/SKILL.md

@@ -13,6 +13,9 @@ trust:
   level: professional
 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/brand-strategy/SKILL.md

@@ -13,6 +13,9 @@ trust:
   level: professional
 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/brand-to-tokens/SKILL.md

@@ -12,6 +12,9 @@ trust:
   level: professional
 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/check-refs/SKILL.md

@@ -3,6 +3,9 @@ model_tier: medium
 name: check-refs
 description: "Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions."
 domain: process
+scope:
+  write: []
+  verification_reason: "the declared command is a read-only checker: grep -c 'writeFileSync|mkdirSync|appendFileSync' src/scripts/check_references.ts returns 2 and both sit inside its own --self-test tmpdir. Absence of a write is not something a command can prove, so the derivation is stated instead."
 execution:
   type: assisted
   handler: shell

package/dist/agent-src/skills/code-refactoring/SKILL.md

@@ -28,8 +28,51 @@ Do NOT use when:
 2. **Understand the scope** — what exactly needs to change and why?
 3. **Find ALL references** — use `codebase-retrieval` and `view` with `search_query_regex` to find every
    caller, implementation, test, and configuration that references the code being changed.
+   **If the change is to a closed set** — an enum, union, literal type, state
+   machine, role or permission set — identifier search is not enough: the
+   consumers that break are the ones that never name the type. Search by shape as
+   well (`switch` / `match` / if-chains over it, lookup tables keyed by it,
+   validators, serializers, schemas, fixtures, translation keys) and classify each
+   as exhaustive, deliberate fallback, or missing case. Procedure:
+   [`downstream-changes-mechanics`](../../../docs/guidelines/agent-infra/downstream-changes-mechanics.md).
 4. **Map the impact** — create a list of all files that will need changes.
-5. **Present the plan** — show the user what will be affected before starting.
+5. **Decide the verdict, if the refactor is a de-duplication** — see the
+   safe-abstraction gate below. An extraction with no recorded verdict is a
+   guess about whether two things are the same thing.
+6. **Present the plan** — show the user what will be affected before starting.
+
+### Safe-abstraction gate — before merging two things into one
+
+This skill performs extractions; it is therefore the place that decides
+whether one should happen. A wrong abstraction costs more than the
+duplication it replaced, because the duplication is visible and the wrong
+abstraction grows caller flags until nobody can remove it. Ask, before
+moving any code:
+
+1. Is this the same knowledge, or two facts that currently look alike?
+2. Would both copies change for the same reason?
+3. Is there one honest domain name that fits **every** call site?
+4. Can the common core stay free of caller-specific flags and modes?
+5. Are public contracts preserved, and do tests prove behavioural equivalence?
+6. **If the two copies diverged tomorrow, would that be a defect or
+   legitimate evolution?**
+
+A "legitimate evolution" answer to the last question is decisive: stop, and
+record the verdict `keep-duplicated`. That closes the refactor **successfully**
+— so does `de-abstract`, splitting a shared unit that has grown modes back
+apart. Neither is a failure to act, and neither needs an apology in the
+output. Textual similarity is not evidence of shared knowledge: copies that
+read identically can encode different assumptions, and merging them changes
+behaviour silently.
+
+The class names and the full verdict list are in
+[`redundancy-taxonomy`](../../../docs/guidelines/redundancy-taxonomy.md).
+
+When the refactor goes the other way and **creates** a new unit, the reuse
+question comes first: does an existing class or component already cover this, and
+what does composing or extending it cost against a new one? Thresholds per
+artifact class:
+[`component-oriented-and-oop-development`](../../../docs/guidelines/component-oriented-and-oop-development.md).
 
 ## Procedure: Refactor code
 
@@ -140,6 +183,7 @@ After the code changes are verified, update all affected documentation:
 1. Find all usages → update all usages → update docs → run the static analyser → run tests.
 
 ### Extract method / class
+0. Run the safe-abstraction gate above — a `keep-duplicated` verdict ends it here.
 1. Create the new method/class → move logic → update caller → update docs → run the static analyser → run tests.
 
 ### Move class to different namespace

package/dist/agent-src/skills/code-review/SKILL.md

@@ -37,11 +37,70 @@ Use this skill when:
 2. **Detect the change-type + depth** — route to the right checklist and pick the review depth (below).
 3. **Architecture** — does the approach make sense? Right layer? Right pattern?
 4. **Correctness** — does it actually work? Edge cases? Error handling?
-5. **Quality** — types, naming, readability, DRY, SOLID?
-6. **Security** — input validation, authorization, injection?
-7. **Performance** — N+1 queries, missing indexes, unbounded queries?
-8. **Tests** — are new paths covered? Are existing tests still valid?
-9. **Conventions** — does it follow project standards?
+5. **Quality** — types, naming, readability, SOLID?
+6. **Redundancy** — see below; a verdict, not a "this looks duplicated".
+7. **Propagation** — did a changed concept reach every occurrence? see below.
+8. **Security** — input validation, authorization, injection?
+9. **Performance** — N+1 queries, missing indexes, unbounded queries?
+10. **Tests** — are new paths covered? Are existing tests still valid?
+11. **Conventions** — does it follow project standards?
+
+## The redundancy dimension
+
+`DRY` as a checklist word produced findings nobody could act on: it names a
+principle, not a decision, and it has no answer for the case where two copies
+should stay. Replace it with a verdict.
+
+Classify the finding against
+[`redundancy-taxonomy`](../../../docs/guidelines/redundancy-taxonomy.md) —
+implementation, knowledge, or representation — and record one verdict from that
+document's list. `keep-duplicated` and `de-abstract` are successful outcomes; a
+finding with no recorded verdict stays open. Knowledge, policy, contract and
+delivery-authority duplication outrank clone percentage: two copies of a
+*decision* diverge into a bug, two copies of a loop usually do not.
+
+**Diff-aware, always.** The finding is duplication this change **introduces**,
+or duplication on a surface it touches. Pre-existing duplication is baseline —
+it is named once if the reviewer thinks it matters and it never fails an
+unrelated change. A review that reds a diff against debt it did not create is a
+review nobody will run twice.
+
+For comments, labels, tooltips, placeholders and empty states, run the
+Information Delta Test from the same document rather than judging text volume.
+A reduction that removes an accessibility name is a defect, not a cleanup.
+
+Naming is the same dimension pointed the other way: a diff that introduces a
+second term for a concept the tree already names is the finding, and an existing
+split is baseline. The classes and the `canonicalize-term` / `keep-distinct`
+verdicts are in the same document.
+
+## The propagation dimension
+
+A change is complete when the **concept** changed everywhere, not when the named
+file compiles. Two shapes to check, both of which the file-level review misses:
+
+**A closed set gained or lost a member** (enum, union, literal type, state
+machine, role or permission set, schema `enum`, DB check constraint). List the
+consumers and their status — every `switch` / `match` / if-chain over the type,
+every lookup table keyed by it, every validator, serializer, schema, fixture and
+translation key. A `default` branch that silently absorbs the new member is a
+missing case, not a handled one. Procedure:
+[`downstream-changes-mechanics`](../../../docs/guidelines/agent-infra/downstream-changes-mechanics.md).
+
+**A shared behaviour moved and its siblings did not.** A defect fixed in one
+place is presumed to recur until searched: name the exact wrong construct, grep
+the tree, and report the count — zero is a real answer and worth stating, because
+it distinguishes "this was unique" from "nobody looked".
+
+Diff-aware on the same terms as redundancy: the finding is a concept **this
+change** left half-migrated. Pre-existing incompleteness elsewhere is baseline.
+
+When the diff **creates** a class, component, service or hook rather than
+changing one, the question is whether it needed to exist: what was searched,
+what was found, and why composing or extending the incumbent was rejected. An
+answer, not a ceremony — and the thresholds for when repetition actually earns
+an abstraction are in
+[`component-oriented-and-oop-development`](../../../docs/guidelines/component-oriented-and-oop-development.md).
 
 ## Change-type routing — load only the checklist the diff needs
 
@@ -109,6 +168,17 @@ coverage reads as full coverage.
   shuffled file order (deterministic seed per session, logged for replay) so
   a fixed order does not correlate their blind spots. Single-reviewer → no shuffle.
 
+**MEASURED, and the result is a null — 2026-08-23.** This control is prose and nothing in
+the package implements it. That is now true for a recorded reason rather than by
+omission: the pre-registered question — does rotating reviewer order change the finding set
+on a frozen corpus, by more than 15 % — **cannot be answered from the corpus that exists**.
+`agents/evidence/reviews/` holds 123 findings artifacts, and none of them records the file
+order it was produced under, so the counterfactual is not recoverable; re-running reviewers
+produces fresh judgements in which ordering is confounded with run-to-run variance. Full
+null, with its reopening condition: `agents/evidence/review-rotation-prereg-and-null.md`.
+A reduced-power crossover was considered and refused — it would risk a false closure on a
+control this paragraph still specifies.
+
 ## Before creating a PR
 
 1. When `quality.local_auto_run: true`: run the project's quality pipeline (see the stack carve-out for the exact commands — PHP: `quality-tools`) and tests via the project's runner (`make test`, `npm test`, `pytest`, `go test ./...`, or the project's wrapper script). Under the default (`false` / missing): skip both — remote CI on the PR is the gate.

package/dist/agent-src/skills/command-routing/SKILL.md

@@ -3,6 +3,9 @@ model_tier: inherit
 name: command-routing
 description: "Use when the user invokes a slash command like /create-pr, /commit, /fix-ci, or pastes command file content — routes to the right command with context inference and GitHub API patterns."
 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
@@ -23,6 +26,9 @@ Triggered when user invokes a slash command. The `slash-command-routing-policy`
 
 1. **Match command** — Find the command file in `.augment/commands/` or `agents/overrides/commands/`.
 2. **Infer inputs** — Before asking the user, try to infer values (see table below).
+2b. **List a matching playbook in the preamble.** If a playbook's `task` matches the
+   command's name, name it before the steps run — it is this repository's own procedure and
+   outranks a shipped one ([`playbook-precedence`](../../rules/playbook-precedence.md)).
 3. **Execute steps** — Follow the command steps in exact order.
 4. **Verify output** — Confirm expected result was produced (commit, PR, file change, etc.).
 

package/dist/agent-src/skills/command-writing/SKILL.md

@@ -305,6 +305,41 @@ Bad description (vague, no outcome):
 
 > "PR command"
 
+## The `## Examples` section on a user-facing command
+
+Stated once, here — never repeated per command.
+
+A command whose `visibility` is `visible` or `advanced` carries an
+`## Examples` section: **1-3 filled invocations** in a fence, then **exactly
+one Why line**. Filled means a real path, a real ticket key, a real flag — a
+placeholder teaches nothing about what to type.
+
+The Why line uses one of two literals, `**Why it works:**` or a
+`### Why it works` heading, and cites **exactly one** pattern id from
+[`prompt-patterns.yml`](../../config/discovery/prompt-patterns.yml):
+`outcome-not-steps` · `self-check-loop` · `measurable-target` ·
+`give-the-artifact` · `point-at-reference` · `say-the-format`. One id, because
+the Why line's job is the part that transfers to a command the reader has not
+seen, and a line naming three patterns names none of them.
+
+~~~
+## Examples
+
+```
+/work fix the failing login test under tests/feature/auth
+```
+
+**Why it works:** measurable-target — it names the file instead of the symptom.
+~~~
+
+Enforced by `check_command_examples`, forward-only: the 23 in-scope commands as
+of 2026-08-24 are grandfathered in a frozen set inside the gate, and a command
+**added or promoted into `visible`/`advanced`** after that must comply. Two
+things the gate checks that are easy to miss — an invocation must resolve to
+the command's own `name:` (a rename otherwise leaves stale examples behind), and
+a flag used in an example must be documented in the body **outside** the
+section.
+
 ## Encode usage policy in the description
 
 Workflow sequencing, preconditions, ID/output provenance ("copy ids verbatim,

package/dist/agent-src/skills/condense-memory/SKILL.md

@@ -3,6 +3,9 @@ model_tier: inherit
 name: condense-memory
 description: "When shrinking always-loaded memory files (AGENTS.md, CLAUDE.md, .cursorrules) exceeding ~150 lines or ~4,000 chars — telegraph grammar, refuses sensitive paths, .original.md round-trip."
 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/context-authoring/SKILL.md

@@ -39,7 +39,7 @@ Do NOT use when:
 |---|---|---|
 | `auth-model.md` | Roles, permission model, impersonation, known exceptions | `authz-review`, `judge-security-auditor`, `threat-modeling` |
 | `tenant-boundaries.md` | Tenancy type, scope propagation, known cross-tenant paths | `multi-tenant-boundary-review`, `blast-radius-analyzer`, `judge-security-auditor` |
-| `data-sensitivity.md` | Field classification, masking rules, log-safe types | `data-exposure-review`, `data-flow-mapper`, logging reviewers |
+| `data-sensitivity.md` | Field classification, masking rules, log-safe types | `data-flow-mapper`, logging reviewers |
 | `deployment-order.md` | Migration strategy, feature flags, rollback plan | `migration-safety`, `judge-bug-hunter`, release reviewers |
 | `observability.md` | Error tracking, log channels, metrics, known alerts | deploy reviewers, `bug-analyzer`, incident mode |
 

package/dist/agent-src/skills/conventional-commits-writing/SKILL.md

@@ -3,6 +3,9 @@ model_tier: medium
 name: conventional-commits-writing
 description: "When writing commit messages or squash-merge titles — `feat:`, `fix:`, `chore:`, scopes, breaking changes — even when the user just says 'commit this' without naming Conventional Commits."
 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/copilot-agents-optimization/SKILL.md

@@ -3,6 +3,9 @@ model_tier: medium
 name: copilot-agents-optimization
 description: "Use when optimizing AGENTS.md or copilot-instructions.md — deduplicates against .augment/ content, enforces line budgets, and focuses each file on its audience."
 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
@@ -37,6 +40,13 @@ Before changing anything, read and understand:
 1. **Read `AGENTS.md`** — current content, line count, what's duplicated vs. unique.
 2. **Read `.github/copilot-instructions.md`** — same analysis.
 3. **Scan `.augment/`** — which skills, rules, and guidelines already cover topics from the files above.
+3b. **Scan the playbooks too, not only `.augment/`.** A `packages/<n>/AGENTS.md` may
+   duplicate a **playbook** rather than a shipped rule, and dedup against `.augment/` alone
+   misses it entirely — the content is not in `.augment/` at all. Run
+   `findRestatedSteps` (`src/scripts/derive_playbooks.ts`) over each workspace file: a line
+   carrying a playbook's `invokes` id outside a link is a restatement to replace with a
+   pointer. The same id **inside** a link label is the shape the contract wants — see
+   [`agents-md-thin-root` § Workspace files](../agents-md-thin-root/SKILL.md).
 4. **Identify duplication** — what content exists in both AGENTS.md and `.augment/`?
 
 Only after this analysis, proceed with optimization.

package/dist/agent-src/skills/corpus-grounding/SKILL.md

@@ -11,6 +11,9 @@ trust:
   level: professional
 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/design-intelligence/SKILL.md

@@ -14,6 +14,9 @@ trust:
   level: professional
 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
 ---