@event4u/agent-config 14.10.0 → 14.12.0

package/dist/agent-src/skills/server-hardening/SKILL.md

@@ -0,0 +1,159 @@
+---
+model_tier: medium
+name: server-hardening
+description: "Use when hardening a Linux host you operate — SSH posture, a default-deny firewall baseline, and unattended security upgrades, each verified on the box rather than assumed from a config file."
+domain: devops
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# server-hardening
+
+## When to use
+
+Use when a host is yours to operate — a VPS, a bare-metal box, a long-lived VM —
+and its own security posture is the question. Three surfaces: who may log in, what
+may reach the network, and how patches arrive.
+
+Do NOT use when:
+- The workload runs on a managed runtime with no host you control — there is no
+  host posture to set, and `operational-readiness` records that as `unavailable`
+  with that reason
+- Auditing application code for vulnerabilities (use `security-audit`)
+- Application-level auth and authorization (use `security`, `authz-review`)
+- Provisioning cloud infrastructure (use `terraform`, `aws-infrastructure`)
+- Container image hardening (use `docker`)
+
+## The three surfaces
+
+### 1. SSH posture
+
+The one remote-entry door. Harden in this order, and **keep an open session while
+you change it** — a mistake here locks you out of the machine you are fixing.
+
+| Setting | Target | Why |
+|---|---|---|
+| `PasswordAuthentication` | `no` | Ends credential-stuffing against the host outright |
+| `PubkeyAuthentication` | `yes` | The replacement must work before passwords are removed |
+| `PermitRootLogin` | `no` (or `prohibit-password`) | Forces an audit trail through a named account |
+| `AllowUsers` / `AllowGroups` | Explicit allow-list | Default is every account on the box |
+| Port | Non-default is optional | Cuts log noise, not risk — never the primary control |
+
+Verify from a **second** connection before closing the first:
+
+```bash
+sudo sshd -t                                  # config parses; do this before reload
+sudo systemctl reload ssh                     # or sshd, per distro
+sudo sshd -T | grep -Ei 'passwordauth|permitrootlogin|pubkeyauth'
+```
+
+`sshd -T` prints the **effective** configuration. A file under
+`sshd_config.d/` or a `Match` block can override what you just edited, so the
+file you wrote is not evidence — the effective dump is.
+
+### 2. Firewall baseline
+
+Default-deny inbound, allow-list outbound where the workload permits.
+
+```bash
+sudo ufw default deny incoming
+sudo ufw default allow outgoing
+sudo ufw allow OpenSSH                        # before enabling, or you are locked out
+sudo ufw enable
+sudo ufw status verbose                       # the verification, not the intent
+```
+
+Two traps worth naming. A container runtime can write its own forwarding rules
+that bypass the host firewall entirely — check the actual rule table
+(`sudo iptables -S` / `sudo nft list ruleset`), not just the friendly front-end.
+And a cloud security group sits *in front* of the host: both must agree, and the
+narrower one is the effective policy.
+
+Optionally add an SSH brute-force throttle (`fail2ban` or equivalent). It is
+noise reduction and a small real gain once password auth is already off — never
+a substitute for it.
+
+### 3. Unattended security upgrades
+
+Patches that require a human are patches that arrive late.
+
+```bash
+sudo apt install unattended-upgrades          # Debian/Ubuntu family
+sudo dpkg-reconfigure -plow unattended-upgrades
+sudo unattended-upgrade --dry-run --debug     # proves it would act
+```
+
+Decide and record two things, because the default is silence: whether the host
+**reboots automatically** when a patch needs it, and where the **failure
+notification** goes. An upgrade timer that has been failing for six weeks is
+indistinguishable from one that is working, unless something reports it.
+
+Security patches only. Automatic *feature* upgrades change behaviour under you,
+which is a different risk with a different owner.
+
+## Procedure: Harden a host
+
+1. **Confirm the host is yours to harden.** Managed runtime with no shell → stop;
+   there is no posture here, and that is a recordable `unavailable`.
+2. **Open a second session and keep it open** for the whole SSH and firewall
+   work. This is the entire rollback mechanism.
+3. **Set the SSH posture**, then verify with `sshd -T` from the second session —
+   effective config, not the file.
+4. **Set the firewall baseline**, allowing SSH *before* enabling. Verify with
+   `ufw status verbose` and against the raw rule table.
+5. **Enable unattended security upgrades**, then prove with `--dry-run` that it
+   would act. Record the reboot policy and the failure destination.
+6. **Re-verify from a fresh connection.** Close every old session and reconnect.
+   A posture that only holds inside an already-authenticated session is
+   unverified.
+7. **Report each surface as met, unmet or uninspected.** Uninspected is not met —
+   `operational-readiness` reads an uninspected host posture as a red.
+
+### Validate
+
+- Verify `sshd -T` reports `passwordauthentication no`.
+- Verify `sshd -T` reports `permitrootlogin no` or `prohibit-password`.
+- Verify a key-based login succeeds from a **fresh** connection.
+- Verify the firewall default is deny-inbound and SSH is explicitly allowed.
+- Verify the raw rule table agrees with the front-end.
+- Verify `unattended-upgrade --dry-run` reports it would act.
+- Confirm the reboot policy and the failure-notification destination are recorded.
+
+## Output format
+
+1. One row per surface — SSH, firewall, unattended upgrades — with met / unmet /
+   uninspected and the verifying command's output.
+2. The reboot policy and where upgrade failures are reported.
+3. Anything left unmet, with what would close it.
+
+## Gotcha
+
+- Changing SSH without a second open session is how a host becomes unreachable.
+- The config file is not the posture. `sshd -T` is; a drop-in or `Match` block
+  silently wins.
+- Enabling a firewall before allowing SSH locks you out immediately.
+- A container runtime's own rules can bypass the host firewall.
+- A cloud security group and the host firewall must both allow a port; the
+  narrower wins.
+- A silently failing upgrade timer looks exactly like a working one.
+- A non-default SSH port reduces log volume, not risk.
+
+## Do NOT
+
+- Do NOT disable password authentication before a key login is proven to work.
+- Do NOT enable the firewall before allowing SSH.
+- Do NOT enable automatic feature upgrades — security patches only.
+- Do NOT treat an installed package as an enabled control; prove it acts.
+- Do NOT report an uninspected surface as met.
+- Do NOT rely on a non-default port as a control.
+
+## Auto-trigger keywords
+
+- server hardening
+- host hardening
+- ssh hardening
+- firewall baseline
+- unattended upgrades
+- fail2ban

package/dist/agent-src/skills/skill-improvement-pipeline/SKILL.md

@@ -3,6 +3,9 @@ model_tier: inherit
 name: skill-improvement-pipeline
 description: "Run the skill-improvement pipeline after a learning was detected — capture, classify, create, validate, apply; explicit request only."
 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/skill-management/SKILL.md

@@ -4,6 +4,9 @@ name: skill-management
 description: "Use when condensing, decondenseing, refactoring, or improving existing skills. Covers the full skill lifecycle from verbose → sharp → maintained."
 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/skill-reviewer/SKILL.md

@@ -3,6 +3,9 @@ model_tier: high
 name: skill-reviewer
 description: "Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations."
 domain: quality
+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/skill-writing/SKILL.md

@@ -229,6 +229,12 @@ to every skill you author.
 - Per the post-action summary suppression, the example output ships
   the artifact, not a wrapping `## Status` / `## Summary` block.
 
+**Scope-exclusion clause.** A skill can shed assumed-knowledge prose without
+losing correctness by naming what it does NOT cover: "this skill covers only
+`<X>`; standard `<Y>` is assumed". One sentence replaces the paragraph that
+would otherwise re-teach `<Y>`, and it is stronger than silence — a reader who
+does not have `<Y>` learns that from the clause instead of from a wrong result.
+
 **Pre-save self-check:**
 1. Does any procedure step open with "Let me", "Now I will", "Found
    it", "OK", or "Alright"?

package/dist/agent-src/skills/skill-writing/references/procedure.md

@@ -22,8 +22,9 @@ rule. Skip only on explicit *"just do it"* bypass or trivial edits
 ### 0b. Skill-growth gate (new skill only)
 
 The skill count keeps climbing; nothing forces *"should this be a new skill at
-all?"*. Before creating a **new** skill, answer these in the PR body — a new
-skill that cannot answer them is a merge / guideline / no-op in disguise:
+all?"*. Before creating a **new** skill, answer these **in the ledger**,
+`agents/decisions/skill-admissions.jsonl` — a new skill that cannot answer them
+is a merge / guideline / no-op in disguise:
 
 1. **Family** — which capability family does it join? (engineering, product, …)
 2. **Capability** — what does it do that no existing skill does? Name the gap.
@@ -31,6 +32,27 @@ skill that cannot answer them is a merge / guideline / no-op in disguise:
 4. **Why not a guideline** — is this executable workflow (skill) or reference material (guideline)? Guideline-shaped content does not become a skill.
 5. **Visibility tier** — `core` or `lab`? Which pack?
 
+**The answers go in the ledger, not in the PR body.** That used to say PR body,
+and `check_finding_dispositions.ts:11` rejects that exact surface for findings in
+its own words — a comment is *"mutable and unaudited; it is transport, not a
+record"*. The consequence was measurable: **+8 skills landed in one release with
+no visible "no"**, because a refusal kept in a PR body is a refusal nobody can
+grep. One line, appended:
+
+```json
+{"skill":"<name>","decision":"admitted","date":"YYYY-MM-DD","family":"…","capability":"…","why_not_extend":"…","why_not_a_guideline":"…","visibility":"…"}
+```
+
+`check_skill_admissions` is forward-only: it requires a row only for skills added
+since the base ref, so nothing existing needs backfilling. It rejects an answer
+under 12 characters, because a one-word answer is the boilerplate the gate exists
+to catch rather than an answer.
+
+**A refusal is a row too**, and that is the half the PR body lost:
+`{"skill":"…","decision":"rejected","date":"…","instead":"…"}`. A rejected row may
+not name a skill that exists — a record saying a capability was refused while it
+ships is worse than no record.
+
 **Surface overlap before deciding** — run `./scripts-run src/scripts/skill_overlap`
 (or `audit_skill_overlap`) and read the nearest matches; a high-overlap hit is a
 merge signal, not a green light. This gate is the authoring-time companion to the

package/dist/agent-src/skills/spreadsheet-authoring/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/storybook-workshop/SKILL.md

@@ -0,0 +1,203 @@
+---
+model_tier: medium
+name: storybook-workshop
+description: "Use when a component library needs a workshop — one story per concept, JSDoc summaries the manifest can carry, stories run as tests, and an opt-in MCP channel that replaces guessing with querying."
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# storybook-workshop
+
+A story is not a demo. It is the component's **executable documentation**: the artefact an
+agent reads to learn what the component accepts, and the harness that catches a contrast or
+focus defect while the component is still in isolation. Stack-agnostic — the tool is
+Storybook, the discipline is not.
+
+Lifted out of [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) § Component workshop, which
+keeps a pointer here rather than a copy.
+
+## The Iron Law
+
+```
+ONE CONCEPT PER STORY. NEVER A "SizesAndVariants" STORY.
+EVERY COMPONENT EXPORT AND EVERY STORY CARRIES A JSDoc @summary.
+A STORY THAT SHOWS AN ANTI-PATTERN IS TAGGED `!manifest` OR THE AGENT LEARNS FROM IT.
+STORIES RUN. A STORY NOBODY RUNS IS A SCREENSHOT WITH EXTRA STEPS.
+```
+
+## When to use
+
+A shared component library exists or is being started, and one of: stories are being added,
+an agent needs an inventory of what the library already offers, an a11y regression should be
+caught in isolation rather than on a screen, or a Storybook MCP channel is available and
+nobody has decided whether to use it.
+
+**Skip it** for a handful of one-off components with a single consumer — the setup and
+upkeep outweigh the return, and that judgement belongs to the reader rather than to this
+skill.
+
+## The story set — one concept per story
+
+The state-coverage rows every reusable component owes become **story names**:
+`Default`, `Loading`, `Empty`, `Error`, `Disabled`, `Dark`. One concept each.
+
+A combined story — the canonical anti-pattern is `SizesAndVariants` — fails at both jobs it
+has: a human cannot tell which knob caused what, and an agent reading it cannot learn a
+single prop's effect because every value is co-present. Split it, one axis per story
+(Storybook's own guidance on writing effective stories).
+
+Stories render under the **same semantic tokens** as the app and the `.dark` class; a
+hardcoded preview theme makes the workshop lie about what the component looks like in place.
+
+## JSDoc `@summary` is required, and the reason is mechanical
+
+The manifest an agent reads **truncates descriptions**. A component whose summary is a
+paragraph arrives as a fragment, and the agent then infers the rest. So:
+
+```ts
+/** @summary A single-action button. Owns its own focus ring; never wrap in an anchor. */
+export const Button = …
+
+/** @summary Disabled — the click handler is not attached, not merely ignored. */
+export const Disabled: StoryObj<typeof Button> = …
+```
+
+One sentence, front-loaded with the fact that changes a caller's decision.
+
+## Before authoring — review what the library already has
+
+The first step is not a story, it is an inventory. A library large enough to want a workshop
+is large enough that the component being asked for already exists under another name, and a
+second `Badge` is the failure this skill's own § Do NOT is trying to prevent elsewhere.
+
+Read the existing stories — via the MCP channel below when it is available, by reading the
+files otherwise — and only then decide whether anything needs writing.
+
+## Procedure
+
+1. **Inspect the existing story set before authoring anything.** Read what the library
+   already has — via the MCP channel below when it is available, otherwise by reading the
+   story files — and check the component against it by name and by shape.
+   - **Source of truth:** the story files, or `list-all-documentation` over a running Storybook.
+   - **Verify:** the component you are about to write does not already exist under another name.
+2. **One story per concept**, named from the state set above.
+   - **Verify:** no story name joins two axes with `And`.
+3. **Write the `@summary` on the export and on each story.**
+   - **Verify:** every export in the file has one, and each is a single sentence.
+4. **Tag what must not be learned from** — see § Do NOT.
+   - **Verify:** every anti-pattern or deprecated story carries `tags: ['!manifest']`.
+5. **Run them** — § Validate.
+   - **Verify:** the run reports pass/fail per story, and a11y findings land in the shape below.
+
+## Validate — stories are tests
+
+Run the project's story test command (the Vitest addon's `storybook test`, or whatever
+`package.json` declares — read it, do not assume a name), then read the a11y result.
+
+Write findings into `state.ui_review.a11y` in the shape
+[`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) § Review pass already defines:
+
+```
+{violations: [{rule, selector, severity}, …], severity_floor?, accepted_violations?}
+```
+
+**Use that shape exactly.** The engine de-duplicates on it, so a finding written in a
+different shape is not a differently-formatted finding — it is a finding the engine counts
+twice.
+
+Browser tooling stays a **consumer dependency**, the same posture as `react-shadcn-ui`: this
+package installs no browser and runs none. Absent the tooling, say the a11y half did not run
+rather than reporting zero violations — an unrun check and a clean check produce the same
+number and mean opposite things.
+
+**One finding is decidable without a browser**, and it ships beside this skill:
+`scripts/story_contrast_floor.ts` computes the WCAG 2.1 contrast ratio between two colours a
+story *declares in its own args* and emits the same `(rule, selector, severity)` shape. It is
+**not axe** and not a substitute for § Validate — it sees no rendered page, so role, focus,
+and computed-style defects are all outside it, and a colour arriving through a token
+indirection is invisible to it. It exists because "we cannot run axe here" is not a reason to
+check nothing, and a declared colour pair is decidable from the file.
+
+## Security constraints
+
+`scripts/story_contrast_floor.ts` reads story files and computes arithmetic. No network, no
+subprocess, no writes, and it never evaluates the story it reads — it matches declared literals
+with a regex rather than importing the module, so running it over an untrusted repository
+executes none of that repository's code. Importing a story to inspect its args would run
+that file, which is the one thing a static checker must not start doing.
+
+## MCP path — opt-in channel, never a dependency
+
+**"Opt-in" is about the agent connecting, not about installing.** A 2026-08-24
+`npx storybook@latest init --yes` scaffold ships `@storybook/addon-mcp` *and*
+`@storybook/addon-a11y` in `devDependencies` by default — recorded verbatim in
+`tests/fixtures/stack/storybook-current/`, which is also the only source any
+Storybook major stated here may come from (`storybook@^10.5.10`). So the addon
+usually already exists; what stays optional is whether an agent reaches a
+running instance. The same scaffold prints *"installed but is not entirely set
+up yet"*, so its presence is not evidence the channel works.
+
+When the project has `@storybook/addon-mcp` **and** a running Storybook,
+[`existing-ui-audit`](../existing-ui-audit/SKILL.md) prefers the live tools —
+`list-all-documentation`, then `get-documentation` for the components that matter — over the
+hand-read inventory. **The live read wins; the file read is the fallback**, and the fallback
+is never removed: an agent that cannot reach a running Storybook must still be able to
+inventory the library.
+
+**React-only while in preview.** Storybook's own MCP FAQ (docs 10.5) states the documentation
+toolset supports React only during preview, so Vue, Angular, and Web Components take the
+file-read path. Stated here rather than discovered at runtime.
+
+Two operative rules, restated from Storybook's suggested agent instructions rather than
+copied verbatim:
+
+- **Never use an undocumented prop.** If the manifest does not carry it, it is not part of
+  the component's surface — reading it out of the implementation is how a private prop
+  becomes a de-facto API.
+- **Fetch the story instructions before writing a story.** The project's own conventions
+  live there; writing first and reconciling later produces a story that matches nothing.
+
+## Output format
+
+1. Name the inventory source used — MCP or file read — and why.
+2. List the stories authored or changed, one line each, with their concept.
+3. Report the story-test result, and the a11y findings in the `(rule, selector, severity)`
+   shape.
+4. State explicitly what did not run (no browser tooling, no running Storybook, non-React
+   renderer).
+
+## Gotchas
+
+- **`SizesAndVariants` looks efficient and destroys both jobs** — a human cannot attribute
+  the effect, and an agent cannot learn a single prop from it.
+- **A truncated description reads as a complete one.** The manifest cuts the tail without
+  marking it, so a paragraph-long summary arrives as a confident fragment.
+- **A stale story is worse than no story.** It props-drills values the component no longer
+  accepts and documents an API that does not exist; keep stories beside the component and
+  change them in the same commit.
+- **An unrun a11y check reports zero violations** — the same number a clean run reports.
+  Say which one happened.
+- **The MCP channel disappearing is normal**, not an error: no running Storybook is the
+  fallback's whole purpose.
+
+## Do NOT
+
+- Do NOT combine two axes in one story.
+- Do NOT ship a component export or a story without a `@summary`.
+- Do NOT leave an anti-pattern or deprecated story untagged: it carries
+  `tags: ['!manifest']` so it is excluded from the manifest and the agent never learns from
+  it (Storybook's own tag mechanism for curating what the manifest exposes).
+- Do NOT hardcode a preview theme in a story.
+- Do NOT make the MCP channel required, and do NOT remove the file-read fallback.
+- Do NOT report zero a11y violations when the a11y tooling did not run.
+
+## See also
+
+- [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) — the React stack lane, and the `(rule, selector, severity)` shape § Validate writes into.
+- [`existing-ui-audit`](../existing-ui-audit/SKILL.md) — the inventory the MCP path accelerates.
+- [`js-library-packaging`](../js-library-packaging/SKILL.md) — the package around the workshop.
+- [`accessibility-auditor`](../accessibility-auditor/SKILL.md) — the WCAG depth behind the a11y half.
+- [`fe-design`](../fe-design/SKILL.md) § Component Architecture — the stack-agnostic isolate-and-document principle.

package/dist/agent-src/skills/storybook-workshop/scripts/story_contrast_floor.ts

@@ -0,0 +1,134 @@
+/**
+ * story_contrast_floor — the one a11y finding a story can yield WITHOUT a browser.
+ *
+ * Scope, stated first because overclaiming here would be the whole defect: this is **not**
+ * axe and it is not the § Validate path. It computes the WCAG 2.1 contrast ratio between two
+ * colours a story DECLARES in its own args, and emits a finding in the
+ * `(rule, selector, severity)` shape the engine de-duplicates on. It sees no rendered page,
+ * so it cannot find a role, focus, or computed-style defect — which is most of what axe finds.
+ *
+ * It exists because the browser tooling is a consumer dependency this package does not
+ * install, and "we cannot run axe" is not a reason to check nothing. A declared colour pair
+ * is decidable from the file.
+ *
+ * Usage:
+ *   story_contrast_floor <story-file> [<story-file> …]
+ *   story_contrast_floor --self-test
+ */
+
+import * as fs from 'node:fs';
+
+/** WCAG AA floor for normal-size body text. */
+export const AA_NORMAL = 4.5;
+/** WCAG AA floor for large text (>= 18.66px bold, or >= 24px). */
+export const AA_LARGE = 3;
+
+export interface Violation {
+    readonly rule: string;
+    readonly selector: string;
+    readonly severity: 'error' | 'warning';
+    /** The measured ratio, so a reader can see how far off it is rather than only that it failed. */
+    readonly ratio: number;
+}
+
+const clamp01 = (n: number): number => (n < 0 ? 0 : n > 1 ? 1 : n);
+
+/** sRGB → relative luminance, per WCAG 2.1 § relative luminance. */
+export const luminance = (hex: string): number | null => {
+    const m = /^#?([0-9a-f]{6}|[0-9a-f]{3})$/i.exec(hex.trim());
+    if (m === null) return null;
+    let h = m[1] as string;
+    if (h.length === 3) h = h.split('').map((c) => `${c}${c}`).join('');
+    const channel = (pair: string): number => {
+        const v = clamp01(parseInt(pair, 16) / 255);
+        return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+    };
+    const r = channel(h.slice(0, 2));
+    const g = channel(h.slice(2, 4));
+    const b = channel(h.slice(4, 6));
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+
+/** WCAG contrast ratio. Returns null when either colour is unreadable. */
+export const contrastRatio = (fg: string, bg: string): number | null => {
+    const a = luminance(fg);
+    const b = luminance(bg);
+    if (a === null || b === null) return null;
+    const [hi, lo] = a >= b ? [a, b] : [b, a];
+    return (hi + 0.05) / (lo + 0.05);
+};
+
+/**
+ * Colour pairs a story declares in its args, as `(storyName, fg, bg)`.
+ *
+ * Reads only DECLARED literals. A colour arriving through a token indirection is invisible
+ * here, and pretending otherwise would be worse than the gap: the caller would believe the
+ * story was checked.
+ */
+export const declaredPairs = (source: string): Array<{ story: string; fg: string; bg: string }> => {
+    const out: Array<{ story: string; fg: string; bg: string }> = [];
+    // `export const Name: StoryObj<…> = { args: { … } }` — one story per export.
+    const exportRe = /export\s+const\s+([A-Za-z0-9_]+)\s*:[^=]*=\s*\{([\s\S]*?)\n\};/g;
+    for (const m of source.matchAll(exportRe)) {
+        const story = m[1] as string;
+        const body = m[2] as string;
+        const fg = /(?:color|fg|foreground)\s*:\s*['"](#[0-9a-fA-F]{3,6})['"]/.exec(body);
+        const bg = /(?:background|bg|backgroundColor)\s*:\s*['"](#[0-9a-fA-F]{3,6})['"]/.exec(body);
+        if (fg?.[1] !== undefined && bg?.[1] !== undefined) {
+            out.push({ story, fg: fg[1], bg: bg[1] });
+        }
+    }
+    return out;
+};
+
+export const checkStoryFile = (file: string, floor: number = AA_NORMAL): Violation[] => {
+    let source = '';
+    try {
+        source = fs.readFileSync(file, 'utf8');
+    } catch {
+        return [];
+    }
+    const out: Violation[] = [];
+    for (const { story, fg, bg } of declaredPairs(source)) {
+        const ratio = contrastRatio(fg, bg);
+        if (ratio === null || ratio >= floor) continue;
+        out.push({
+            rule: 'color-contrast',
+            // The story is the addressable unit here — there is no DOM to select into.
+            selector: `story:${story}`,
+            severity: 'error',
+            ratio: Math.round(ratio * 100) / 100,
+        });
+    }
+    return out;
+};
+
+const selfTest = (): number => {
+    let failed = 0;
+    const check = (label: string, cond: boolean): void => {
+        if (!cond) {
+            process.stderr.write(`❌  ${label}\n`);
+            failed += 1;
+        }
+    };
+    const r = contrastRatio('#000000', '#ffffff');
+    check('black on white is the maximum 21:1', r !== null && Math.abs(r - 21) < 0.01);
+    check('a colour on itself is 1:1', Math.abs((contrastRatio('#777777', '#777777') ?? 0) - 1) < 0.01);
+    check('an unreadable colour is null, not 0', contrastRatio('nope', '#fff') === null);
+    check('shorthand hex is expanded', contrastRatio('#000', '#fff') !== null);
+    process.stdout.write(failed === 0 ? '✅  story_contrast_floor: 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 files = argv.filter((a) => !a.startsWith('--'));
+    const violations = files.flatMap((f) => checkStoryFile(f));
+    process.stdout.write(`${JSON.stringify({ violations }, null, 2)}\n`);
+    return violations.length > 0 ? 1 : 0;
+};
+
+if (process.argv[1] !== undefined && process.argv[1].includes('story_contrast_floor')) {
+    process.exit(main());
+}

package/dist/agent-src/skills/subagent-orchestration/SKILL.md

@@ -385,5 +385,5 @@ Skip emit when `emergency.orchestration_halt` is set or `spawn_count == 0`
 | Standalone judge on an existing diff | Inline — see judge prompt in [`prompts/do-and-judge.md`](prompts/do-and-judge.md) |
 | External / networked second opinion  | [`ai-council`](../ai-council/SKILL.md) |
 | Cross-model review WITH repo access   | [`/team`](../../domains/meta/team/command.md) (collaborative; subagents are in-session same-weights) |
-| Verifying completeness               | [`verify-before-complete`](../verify-before-complete/SKILL.md) |
+| Verifying completeness               | [`verify-completion-evidence`](../verify-completion-evidence/SKILL.md) |
 | What a subagent owns vs never owns   | [`subagent-boundary`](../../../docs/contracts/subagent-boundary.md) |

package/dist/agent-src/skills/subagent-orchestration/prompts/README.md

@@ -106,3 +106,28 @@ Every dispatchable mode named in `SKILL.md` § *The nine modes* maps to a
 prompt file in the table above (mode 8 is gated/experimental — its
 live-app rubric lives in the `subagent-modes-detail` context, not here);
 each prompt mentions all four status enum values.
+
+## The implementer envelope: hand it to a judge, never to a fresh reviewer
+
+Several templates here carry an `IMPLEMENTER ENVELOPE:` line — `do-and-judge.md:70` and
+`do-and-judge-two-stage.md:72` among them. **That is correct, and it is correct for a
+specific reason:** a judge is validating a *claim*. It needs to know what the implementer
+said it did, because the question is whether the diff supports the claim. Withholding the
+envelope from a judge makes it guess at the claim it is meant to test.
+
+**It is wrong for a fresh reviewer**, and the asymmetry is the whole point of that role. A
+fresh reviewer's value is a negative property: it has **no implementation context**, so it
+cannot inherit the author's framing of what the change is for or what counts as done.
+Handing it the envelope destroys exactly the property it was dispatched for — and it does
+so invisibly, because the output still looks like a review.
+
+So, for the next author of a template in this directory:
+
+```
+COPYING THE ENVELOPE LINE INTO A FRESH-REVIEWER TEMPLATE SILENTLY REMOVES
+THE ONE PROPERTY THAT MADE IT WORTH A SEPARATE DISPATCH.
+JUDGE -> ENVELOPE. FRESH REVIEWER -> DIFF AND SCOPE ONLY.
+```
+
+Recorded here rather than only in the route that consumes it (`/review:changes` § 4b-fresh)
+because the line is copied from *these* files, so this is where a reader meets it.

package/dist/agent-src/skills/supply-chain-intake/SKILL.md

@@ -97,6 +97,18 @@ rg -n 'curl[^|]*\|\s*(bash|sh)|wget[^|]*\|\s*(bash|sh)' .
 - A package that exists but was published this week with 12 downloads is a slopsquat candidate, not a safe dep — weigh age + usage, not just existence.
 - Lockfile integrity is part of the threat model: an unhashed or floating entry can pull a freshly-poisoned release even when a lockfile is "present".
 
+## Known pitfalls
+
+- **Name-similarity is not provenance.** An organisation whose name is
+  near-identical to a widely used tool's, whose site ranks for that tool's
+  queries, and whose "download" button points at a third-party page is not that
+  tool — and may ship no code at all. Observed while harvesting an external
+  reference on 2026-08-22: the lookalike existed only as an SEO surface. The
+  registry entry, the repository URL and the publisher are the provenance; the
+  name, the ranking and the visual resemblance are not. Resolve the package
+  through the registry and follow the declared repository, never through a search
+  result that merely looks right.
+
 ## Do NOT
 
 - Do NOT run an install command for a package you have not existence-checked this session.

package/dist/agent-src/skills/systematic-debugging/SKILL.md

@@ -352,7 +352,7 @@ emit the `context_stale` event above it for the consolidation pass.
 * Playwright / E2E test failures → [`playwright-testing`](../playwright-testing/SKILL.md)
 * PHPStan / Rector / ECS output → [`quality-tools`](../quality-tools/SKILL.md)
 * Verifying the fix is complete before claiming done →
-  [`verify-before-complete`](../verify-before-complete/SKILL.md)
+  [`verify-completion-evidence`](../verify-completion-evidence/SKILL.md)
 
 ## Validation checklist