@aegis-scan/skills 0.2.0 → 0.4.0

package/skills/foundation/aegis-native/aegis-module-builder/SKILL.md

@@ -0,0 +1,251 @@
+<!-- aegis-local: AEGIS-native skill, MIT-licensed; generic feature-dev workflow for AEGIS-bootstrapped repos. DB-migration -> API-route -> Service-Layer -> UI-Component -> Tests -> Optimistic-Updates with TDD-first discipline per spec hard-NICHTs. Single-file skill (no references), since the workflow generalises across stacks. -->
+---
+name: aegis-module-builder
+description: Generic feature-dev workflow for AEGIS-bootstrapped repos. TDD-first pipeline - Plan / Test-red / Implement-green / Verify (gates 1-4) / Polish / Commit. Wraps DB-migrations, API-routes (secureApiRoute + Zod-strict + requireRole), service-layer, UI-components, optimistic-updates. Trigger keywords - module, feature, db-migration, api-route, refactor, neue funktion, neue api, neues modul.
+model: sonnet
+license: MIT
+metadata:
+  required_tools: "shell-ops,file-ops,task-tracking"
+  required_audit_passes: "1"
+  enforced_quality_gates: "4"
+  pre_done_audit: "true"
+---
+
+# aegis-module-builder — Generic Feature-Dev Workflow
+
+The Foundation's TDD-first feature-dev skill. Wraps the canonical "DB-migration → API-route → Service-Layer → UI-Component → Tests → Optimistic-Update" pipeline with explicit Plan / Red / Green / Verify / Polish / Commit phases. Used for every non-customer-build dev task in an AEGIS-bootstrapped repo.
+
+---
+
+## HARD-CONSTRAINT — TDD-First, No Bypasses
+
+This skill MUST follow the TDD-first discipline:
+
+1. **Test before implementation, every time.** Phase 2 writes the failing test first. Phase 3 implements just enough code to make it green. No skipping Phase 2 "because I know what the code should look like".
+2. **No mocks for external dependencies that will be hit in production.** If the feature uses a database, the test uses a real (test-instance) database — not a mock. If the feature calls an external API, the test uses a recorded fixture (VCR-style) — not a hand-written mock that drifts from reality.
+3. **No `--no-verify` on commits.** Husky pre-commit runs `aegis-quality-gates --quick` (gates 1-4: build/tsc/lint/tests). Bypassing means the next commit pulls in a broken build. If a hook is firing falsely, fix the hook, don't bypass.
+4. **No "I'll add the test later" commits.** Either the test exists and passes, or the commit doesn't happen.
+5. **Pre-existing-tests stay green.** Running existing tests before starting + after each phase catches regressions early. If existing tests fail before any change — the workspace is broken; investigate before adding new code.
+6. **Reference `superpowers:test-driven-development`** for the TDD-mechanics (red-green-refactor cycle, test-shape patterns, when-to-skip-test escape-hatches). This skill is the AEGIS-foundation flavor of that pattern.
+
+If TDD-discipline can't be followed for a specific change (e.g., a one-line typo fix, a config file edit) — explicit `--no-tdd` flag with rationale documented in the commit message. Don't silent-skip.
+
+---
+
+## Mission
+
+Replace the failure-mode where "feature-dev" means "write code, hope it works, commit, see it break in CI" with a disciplined pipeline that catches regressions before commit. Be the canonical workflow for every non-customer-build dev task — DB-migration, API-route, service-extraction, UI-feature, refactor, bugfix.
+
+**Quality bar:** every commit from this skill leaves the build green per gates 1-4 (build / tsc / lint / tests). No exceptions.
+
+---
+
+## Triggers
+
+### Slash-commands
+
+- `/module` — start a module-build for a new feature
+- `/feature` — alias
+- `/refactor` — start a refactor with TDD-coverage
+
+### Auto-trigger keywords
+
+- module, feature, db-migration, api-route, refactor, neue funktion, neue api, neues modul, optimistic update
+
+### Required-input
+
+The skill needs a feature-spec. If invoked without one, ask:
+
+```
+What does this feature do?
+- User-story (1-2 sentences)
+- Inputs (request shape, params, files)
+- Outputs (response shape, side-effects)
+- Acceptance-criteria (3-5 bullet points)
+```
+
+Don't infer from chat-context. Demand the spec.
+
+---
+
+## Process
+
+| # | Phase | Time | Output |
+|---|---|---|---|
+| 1 | Plan | ~10 min | feature-spec.md + checklist |
+| 2 | Test (red) | ~15-30 min | failing test that asserts the feature |
+| 3 | Implement (green) | ~30-90 min | code that makes test pass |
+| 4 | Verify (gates 1-4) | ~5 min | all 4 gates green per `aegis-quality-gates --quick` |
+| 5 | Polish (optimistic-updates, edge-cases) | ~15-30 min | edge-case tests + UI polish |
+| 6 | Commit | ~5 min | atomic commit with conventional-commits message |
+
+### Phase 1: Plan
+
+Read the feature-spec. Decompose into testable units:
+
+- **DB layer**: any new tables / columns / indexes? Write migration first.
+- **API layer**: new endpoint? List inputs/outputs/auth-requirements.
+- **Service layer**: business-logic that lives between API and DB? Extract to a pure function.
+- **UI layer**: components that render the feature? Sketch component-tree.
+
+Write a `<feature>-spec.md` (or update an existing planning-doc) with:
+
+```markdown
+# Feature: <name>
+
+## User-story
+<1-2 sentences>
+
+## Acceptance criteria
+- [ ] AC1
+- [ ] AC2
+- [ ] AC3
+
+## Decomposition
+- DB: <new-table or "none">
+- API: <route + method + auth>
+- Service: <function-signature>
+- UI: <component-tree>
+
+## Test plan
+- Unit: <list>
+- Integration: <list>
+- E2E: <list>
+```
+
+### Phase 2: Test (red)
+
+For each layer (DB / API / Service / UI), write the failing test FIRST:
+
+```ts
+// __tests__/<feature>/api.test.ts
+import { describe, it, expect, beforeEach } from 'vitest';
+import { POST } from '@/app/api/<endpoint>/route';
+
+describe('POST /api/<endpoint>', () => {
+  it('returns 200 with valid input', async () => {
+    const req = new Request('http://localhost/api/<endpoint>', {
+      method: 'POST',
+      body: JSON.stringify({ /* valid input */ }),
+    });
+    const res = await POST(req);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toMatchObject({ /* expected shape */ });
+  });
+  
+  it('returns 400 on invalid input', async () => { /* ... */ });
+  it('returns 401 when unauthenticated', async () => { /* ... */ });
+  it('returns 429 after rate-limit', async () => { /* ... */ });
+});
+```
+
+Run the test — it MUST fail (red). If it passes accidentally — the test isn't testing the right thing; rewrite it.
+
+### Phase 3: Implement (green)
+
+For each test, write the minimum code to make it pass:
+
+- DB-migration: `pnpm db:migrate:create <feature>` + write the migration
+- API-route: `app/api/<endpoint>/route.ts` with `secureApiRoute` wrapper
+- Service-layer: pure function in `lib/services/<feature>.ts`
+- UI-component: `components/<feature>/<Component>.tsx`
+
+After each layer: run that layer's tests. They MUST go green. If they don't — fix the implementation, not the test (unless the test's expectation was wrong, which is rare).
+
+### Phase 4: Verify (gates 1-4)
+
+Run `aegis-quality-gates --quick`:
+
+```bash
+npx -y @aegis-scan/cli foundation verify --quick
+# OR (if foundation CLI not installed yet):
+pnpm run build && tsc --noEmit && pnpm run lint && pnpm test
+```
+
+All 4 must pass:
+
+| Gate | Threshold |
+|---|---|
+| build | exit 0 |
+| tsc | 0 errors |
+| lint | 0 errors |
+| tests | 100% pass (no regression in existing tests) |
+
+If any red — fix before Phase 5. Don't proceed with red gates.
+
+### Phase 5: Polish
+
+Add edge-case tests + UI polish:
+
+- **Optimistic-updates** (UI): if the feature mutates state, render the change immediately with a rollback if the API fails. Use TanStack Query / SWR mutation patterns or React useOptimistic.
+- **Loading + error states** (UI): every async-data UI needs both states tested.
+- **Empty-states** (UI): no data → friendly empty-state, not a blank panel.
+- **Accessibility**: keyboard-navigation, aria-labels, focus-management.
+- **Edge-cases** (logic): null inputs, max-length inputs, concurrent submissions.
+
+Add tests for each polish-item. They start as red (because the polish isn't there), then green.
+
+### Phase 6: Commit
+
+Atomic commit per logical unit. Conventional Commits format:
+
+```
+feat(api): add /api/<endpoint> with rate-limit + Zod validation
+
+- Migration: 0042_add_<feature>_table.sql
+- API-route: secureApiRoute + Zod-strict
+- Service-layer: <feature>Service.create(input)
+- UI: <Component> with optimistic update
+- Tests: 4 unit + 2 integration
+
+AC1: ✓ AC2: ✓ AC3: ✓ (per spec)
+```
+
+If the feature is large, split into multiple atomic commits per layer (1 for migration, 1 for API, 1 for service, 1 for UI). Each commit individually passes gates 1-4.
+
+---
+
+## Verification / Success Criteria
+
+Before declaring the module complete:
+
+- [ ] `<feature>-spec.md` written + acceptance-criteria checked
+- [ ] Phase 2 tests are present + were red before Phase 3
+- [ ] Phase 3 implementation makes Phase 2 tests green
+- [ ] Phase 4 gates 1-4 all pass via `aegis-quality-gates --quick`
+- [ ] Phase 5 polish-items addressed (optimistic / loading / error / empty / a11y / edge)
+- [ ] Phase 6 atomic commit(s) follow Conventional-Commits format
+- [ ] No mocks for production-relevant deps (real DB, recorded fixtures for external APIs)
+- [ ] Existing tests still green (no regression)
+
+If any unmet → not done. Report the open item explicitly.
+
+---
+
+## Anti-Patterns
+
+- ❌ Skipping Phase 2 (writing implementation first) — that's not TDD; that's hope-driven-development.
+- ❌ "I'll write the tests after, the implementation is simple enough" — every implementation is simple until the regression hits.
+- ❌ Mocking the database in tests — drift from production behavior; use a real (test-instance) DB.
+- ❌ Mocking external APIs with hand-written stubs — drift; use VCR-style recorded fixtures.
+- ❌ `git commit --no-verify` to bypass husky — fix the hook, don't bypass.
+- ❌ Committing with red gates 1-4 — every commit leaves the build green.
+- ❌ Skipping rate-limit on a new API-route — `secureApiRoute` wrapper is mandatory.
+- ❌ Skipping Zod-validation — every API-route validates input shape.
+- ❌ One giant commit covering DB + API + service + UI — split into atomic commits per layer.
+- ❌ Polish-items in Phase 5 added without tests — every polish-item gets a regression-test.
+- ❌ Inferring `requireRole` for a new endpoint without confirming with the spec — auth is explicit, never inferred.
+
+---
+
+## Extension Points
+
+- **Different framework adapters**: Next.js (App Router) is the canonical default. Remix / SvelteKit / Astro extensions add framework-specific test-templates + route-templates. Phase 1-6 stay the same; only the file-paths + test-shapes vary per adapter.
+- **Different DB layers**: Drizzle / Prisma / Supabase all work; the migration-step in Phase 1 + 3 reads the project's DB-layer-config and uses the right tooling.
+- **Different test-runners**: Vitest is canonical. Jest / Bun-test / Deno-test extensions wrap their respective CLIs. The Verify-gate (Phase 4) reads the project's test-config and dispatches.
+- **Per-project quality-gate-overrides**: a starter project might set lint-threshold to "warnings allowed". Override in `aegis.config.json` `gates.<gate>.threshold`. Don't override here.
+- **TDD-skip escape-hatch**: for genuine 1-line fixes (typo, config), `--no-tdd` flag bypasses Phase 2 + 3 if Phase 6 commit-message documents the rationale (e.g., `chore: fix typo in /datenschutz heading [skip-tdd: 1-line text-fix]`). Use sparingly.
+- **Multi-package monorepos**: each package gets its own pipeline. Phase 6 commits are scoped to the package via `pnpm --filter <pkg> <cmd>` or `nx affected`.
+- **Refactor-mode**: a refactor that moves code without changing behavior runs Phase 2 first to capture current behavior in tests, then refactors with the test as a regression-guard.
+- **Bugfix-mode**: write the failing test that reproduces the bug FIRST (Phase 2), then fix (Phase 3). The test becomes a permanent regression-test.

package/skills/foundation/aegis-native/aegis-orchestrator/SKILL.md

@@ -0,0 +1,146 @@
+<!-- aegis-local: AEGIS-native skill, MIT-licensed; master-entry orchestrator that fires on every session-start, loads CLAUDE.md + AGENTS.md + latest handover + project-skill, prints tool inventory + project-state, then dispatches to the matching specialist skill (customer-build / compliance-audit / dev-feature / aegis-self-test). Pattern ported from a private reference-implementation; this is the public OSS variant. -->
+---
+name: aegis-orchestrator
+description: AEGIS Master-Entry. Loads CLAUDE.md + AGENTS.md + latest handover + state.json, detects use-case (customer-build / compliance-audit / dev-feature / aegis-self-test / skill-authoring), routes to specialist skill per AGENTS.md, runs quality-gates pre-commit, writes session-end handover. Trigger keywords - start, session, bootstrap, orchestrator, phase, handover, weiter, weitermachen.
+model: opus
+license: MIT
+metadata:
+  required_tools: "shell-ops,file-ops,task-tracking"
+  required_audit_passes: "1"
+  enforced_quality_gates: "9"
+  pre_done_audit: "true"
+---
+
+# aegis-orchestrator — Session-Entry
+
+Master skill for AEGIS-foundation-bootstrapped repos. Fires on every session-start (Claude Code via SessionStart-Hook in `.claude/settings.json`; Codex via the Bootstrap-section in `AGENTS.md` per the foundation spec §14.5). Ensures every new agent has full context + finds the right specialist skill before responding to the user's first request.
+
+---
+
+## HARD-CONSTRAINT — Bootstrap-Discipline
+
+Before responding to ANY user request, this skill MUST:
+
+1. **Read** `.claude/handover/HANDOVER-LATEST.md` (or `.codex/handover/HANDOVER-LATEST.md` — same file via symlink on `--platform=both`).
+2. **Read** `CLAUDE.md` (project rules).
+3. **Read** `AGENTS.md` (router + tool-mapping table — already in context if AGENTS.md was loaded).
+4. **Read** project-skill if present: `.claude/skills/<project-slug>/SKILL.md`.
+5. **Read** `.aegis/state.json` to pick up the use-case + last completed phase.
+6. **Print** to the user: `Tool-inventory: [...], Skills available: [...], Project-state: phase X, Use-case: Y`.
+7. **THEN** process the user's request — never before.
+
+If any of (1)-(5) is missing, STOP and report the gap explicitly. Don't improvise — `aegis foundation init` should have populated them; if it hasn't, the fix is to run init, not to skip the bootstrap.
+
+---
+
+## Mission
+
+Be the universal session-opener for AEGIS-bootstrapped repositories. Eliminate the "agent starts blind, asks the user where to look" failure mode. Eliminate the "agent dispatches to a non-existent skill" failure mode. Eliminate the "agent commits without quality-gates" failure mode.
+
+Three guarantees per session:
+- Every agent starts with full project context (handover + CLAUDE.md + AGENTS.md + project-skill + state).
+- Every agent dispatches to the matching specialist skill via the AGENTS.md routing-table.
+- Every commit is preceded by `aegis-quality-gates` pre-commit verification.
+
+---
+
+## Triggers
+
+### Slash-commands
+
+- `/start` — start of session, full bootstrap then await user-prompt
+- `/session` — alias for /start
+- `/bootstrap` — alias for /start
+- `/orchestrator` — explicit invocation
+
+### Auto-trigger keywords
+
+Activate automatically when any of these appear in the user's first message:
+
+- start, session, bootstrap, phase, handover, weiter, weitermachen, übergabe, recap
+
+### Auto-trigger via SessionStart-Hook
+
+`.claude/settings.json` configures Claude Code to invoke `aegis-orchestrator` automatically at session-start (via the harness-side hook). Codex agents read the Bootstrap-section in `AGENTS.md` and self-trigger.
+
+---
+
+## Process
+
+The skill follows a fixed bootstrap-then-dispatch sequence. No skipping.
+
+### Phase 1: Bootstrap (mandatory, all 6 steps)
+
+Per the HARD-CONSTRAINT block above. Stop on any missing artifact.
+
+### Phase 2: Use-case detection
+
+Read `.aegis/state.json` `use_case` field. If absent, infer from user's prompt keywords:
+
+| User keywords | Use-case |
+|---|---|
+| build / kunde / customer / agentur / briefing / konfigurator | customer-build |
+| audit / dsgvo / impressum / abmahnung / compliance | compliance-audit |
+| feature / module / db / api / refactor | dev-feature |
+| smoke / verify / self-test / aegis-test | aegis-self-test |
+
+If no use-case can be inferred, ask the user explicitly. Don't guess silently.
+
+### Phase 3: Specialist dispatch
+
+Per the AGENTS.md `Use-Case Routing` table:
+
+| Use-case | Specialist skill |
+|---|---|
+| customer-build | aegis-customer-build (multi-agent: Master + Research + Executor + Strategist) |
+| compliance-audit | brutaler-anwalt (single-agent, multi-persona-internal) |
+| dev-feature | aegis-module-builder |
+| aegis-self-test | aegis-quality-gates → aegis-audit |
+
+Hand off context to the specialist via inline-prompt-template (works on both Claude Code's Task tool AND Codex's spawn_agent per the foundation spec §14.3).
+
+### Phase 4: Pre-commit gate
+
+When the user says "commit" / "push" / "release" — orchestrator invokes `aegis-quality-gates` BEFORE the actual commit. Fails-closed: if any gate is red, commit is blocked + diagnosis printed.
+
+### Phase 5: Session-end handover
+
+When the user says "fertig" / "handover" / "session-ende" / "übergabe" — orchestrator invokes `aegis-handover-writer` to draft the structured handover-file + update the `HANDOVER-LATEST.md` symlink.
+
+---
+
+## Verification / Success Criteria
+
+Before declaring the orchestrator-handoff complete for a session:
+
+- [ ] Bootstrap-checklist completed (all 6 steps, no skipping)
+- [ ] Specialist skill identified + dispatched (or use-case ambiguity reported back to user)
+- [ ] Quality-gates run before any commit (no `--no-verify` bypass)
+- [ ] Session-end handover written (or explicitly deferred-to-next-session if user opts out)
+- [ ] No specialist invoked without verifying its `metadata.required_tools` against the AGENTS.md tool-mapping table for the current harness
+- [ ] `.aegis/state.json` updated with the new phase / last-action timestamp
+
+If any checkbox is unmet: NOT done. Report which step is open + why + what needs to happen.
+
+---
+
+## Anti-Patterns
+
+- ❌ Skipping the bootstrap-checklist "because the user is in a hurry" — the checklist IS the foundation; skipping it breaks every downstream skill.
+- ❌ Inventing a specialist skill that doesn't exist in `AGENTS.md` routing-table.
+- ❌ Committing without `aegis-quality-gates` running first.
+- ❌ Closing a session without writing a handover (next agent starts blind).
+- ❌ Dispatching to a specialist without confirming the harness has the required tools (per AGENTS.md tool-category mapping).
+- ❌ Improvising a use-case when the user-prompt is genuinely ambiguous — instead, ask one clear question and wait.
+- ❌ Pretending the bootstrap files were read when they weren't (file-existence-claims that are false).
+- ❌ Claiming `done` while the project-skill state-file shows an incomplete phase.
+
+---
+
+## Extension Points
+
+- **Add new use-cases**: extend the `Use-Case Routing` table in `AGENTS.md` plus add a new `presets/<use-case>.yaml` describing required-skills + tools + quality-gates + time-budget. Update Phase-2 keyword-inference table here accordingly.
+- **Add new pre-commit-gates**: extend `aegis-quality-gates` SKILL.md (don't extend orchestrator). Orchestrator invokes quality-gates as a black-box.
+- **Add new dispatch-rules**: extend Phase 3 in this skill's Process section. Each dispatch-rule maps one use-case to one specialist (or a multi-agent orchestration per spec §14.3).
+- **Different harness support**: extend the AGENTS.md tool-category mapping to add new harness columns (e.g. Cursor, Windsurf). The orchestrator reads the mapping; no orchestrator-side change needed.
+- **Custom SessionStart-Hook**: a project that needs additional bootstrap steps (e.g., load secrets from a vault, run a `git pull`) extends `.claude/settings.json` with a pre-orchestrator hook. Don't bake project-specific logic into this skill.

package/skills/foundation/aegis-native/aegis-quality-gates/SKILL.md

@@ -0,0 +1,122 @@
+<!-- aegis-local: AEGIS-native skill, MIT-licensed; runs the canonical 9-gate quality-check sequence pre-commit and post-build, fails-closed if any gate is red, produces a JSON+markdown report. The external safety-net per spec §2 Component 5. -->
+---
+name: aegis-quality-gates
+description: One-shot 9-quality-gate runner. Runs build / tsc / lint / tests / aegis-scan / brutaler-anwalt / lighthouse / skillforge-validate / briefing-coverage with per-gate thresholds. Returns exit 0 all-green or exit 1 with failing-gate list. Produces .aegis/verify-report.json + markdown summary. Trigger keywords - verify, check all gates, quality-gates, audit-gate, pre-commit-check.
+model: sonnet
+license: MIT
+metadata:
+  required_tools: "shell-ops,file-ops"
+  required_audit_passes: "1"
+  enforced_quality_gates: "9"
+  pre_done_audit: "true"
+---
+
+# aegis-quality-gates — 9-Gate Verifier
+
+Single-purpose skill: run the canonical AEGIS Foundation quality-gate sequence, return pass/fail per gate, fail-closed when any gate is red. The external safety-net that complements the agent's internal HARD-CONSTRAINT discipline.
+
+---
+
+## HARD-CONSTRAINT — Fail-Closed, No Mocks
+
+This skill is the safety-net for the entire foundation. It MUST:
+
+1. Run real commands against the real artifact (no mocks, no skipping).
+2. Fail-closed: if even one gate is red, return exit-non-zero — do NOT report success.
+3. Be insurance against the failure-mode where a subagent says "it's done" while gates are silently red. The agent's self-report is not trusted; the gate-runner's exit-code is.
+4. Emit a structured report that downstream tooling (CI, handover-writer, status-reporter) can parse — JSON at `.aegis/verify-report.json`, markdown summary printed to stdout.
+
+If husky is bypassed via `--no-verify`: that's a violation per spec §9 hard-NICHTs. Document the override in `SECURITY-EXCEPTION.md` with rationale.
+
+---
+
+## Mission
+
+Be the single source of truth for "is this build ready to commit / push / publish". Operate as a pure function of the working tree + project preset: same inputs → same outputs, no agent-judgment-calls. Make it cheap enough to run pre-commit (every commit) AND comprehensive enough to gate post-build acceptance.
+
+---
+
+## Triggers
+
+### Slash-commands
+
+- `/verify` — full 9-gate run
+- `/check all gates` — alias
+
+### Auto-trigger keywords
+
+- verify, check all gates, quality-gates, audit-gate, pre-commit-check
+
+### Husky pre-commit hook
+
+`templates/customer-project/.husky/pre-commit` invokes `aegis foundation verify --quick` (gates 1-4 only — build/tsc/lint/tests). Full 9-gate run is `--final` for end-of-build. Pre-commit-quick keeps commit-loop fast.
+
+---
+
+## Process
+
+### The 9 gates (sequence + thresholds per spec §6)
+
+| # | Gate | Command | Threshold | Mode |
+|---|---|---|---|---|
+| 1 | build | `npm run build` (or `pnpm run build`) | exit 0 | always |
+| 2 | tsc | `npx tsc --noEmit` | 0 errors | always |
+| 3 | lint | `npm run lint` (if defined) | 0 errors | always |
+| 4 | tests | `npm test` / `pnpm vitest run` | 100% pass, no regression | always |
+| 5 | aegis-scan | `npx -y @aegis-scan/cli scan <built-site>` | score ≥ 950, grade S/FORTRESS | --final only |
+| 6 | brutaler-anwalt | invoke compliance/aegis-native/brutaler-anwalt skill | 0 KRITISCH, ≤ 2 HOCH | --final only |
+| 7 | lighthouse | `npx -y @lhci/cli` | Mobile ≥ 75, Desktop ≥ 90, A11y/SEO/BP = 100 | --final only |
+| 8 | skillforge-validate | `python3 /tmp/SkillForge/scripts/validate-skill.py <each-touched-skill>` | 16/17 or higher per touched skill | always (when skills touched) |
+| 9 | briefing-coverage | custom check: every page in briefing.md exists in built artifact | 100% | --final + briefing present |
+
+### Phase 1: Discover gates that apply
+
+Read `presets/<use-case>.yaml` to determine which gates apply for this use-case + invocation-mode. customer-build uses all 9; compliance-audit uses 5+6+8 only; dev-feature uses 1-4+8.
+
+### Phase 2: Run gates sequentially
+
+In the order above. Capture stdout + stderr + exit-code per gate. Fail-fast if `--bail` flag set; otherwise continue and aggregate all failures into the report.
+
+### Phase 3: Aggregate report
+
+Write `.aegis/verify-report.json` with structured per-gate results. Print a markdown summary to stdout (one-line-per-gate with green/red marker + threshold + actual).
+
+### Phase 4: Exit-code
+
+Exit 0 if all applicable gates pass. Exit 1 otherwise — non-zero exit triggers husky-block on commit.
+
+---
+
+## Verification / Success Criteria
+
+This skill's own success criteria (it's a verifier-of-verifiers):
+
+- [ ] Each of the 9 gates is implemented + integration-tested (gate fires real command, parses real output)
+- [ ] `--quick` mode runs gates 1-4 in under 30 seconds typical (so pre-commit-loop stays usable)
+- [ ] `--final` mode runs all 9 gates + writes `.aegis/verify-report.json` + prints markdown summary
+- [ ] Exit-code is 0 iff every applicable gate passed (no false-positive exit 0 with red gates)
+- [ ] Per-gate threshold is read from the active preset (`presets/<use-case>.yaml`), not hardcoded
+- [ ] husky-template `templates/customer-project/.husky/pre-commit` invokes this skill correctly
+- [ ] When invoked from agent-context (vs CLI): returns the same per-gate status as the CLI does
+
+---
+
+## Anti-Patterns
+
+- ❌ Mocking gate-runs — every gate must hit the real underlying tool. No simulated outputs.
+- ❌ Silent skipping — if a gate's underlying tool is missing (e.g., Lighthouse not installed), report it as a configuration-error, don't pretend the gate passed.
+- ❌ Returning exit 0 while ANY gate is red — even if "the failing gate doesn't matter for this commit". Use preset to exclude gates by use-case, not by ad-hoc judgment.
+- ❌ Allowing `--no-verify` to silently bypass — log every bypass to `SECURITY-EXCEPTION.md`, fail-closed if file is missing, alert on push.
+- ❌ Running the full 9-gate sequence on every keystroke — pre-commit gets `--quick`, end-of-build gets `--final`.
+- ❌ Hard-coding thresholds in the skill body — thresholds live in `presets/<use-case>.yaml` so projects with different bars (e.g., proof-of-concept vs production) can configure.
+- ❌ Skipping the JSON report — downstream tooling depends on `.aegis/verify-report.json` being well-formed.
+
+---
+
+## Extension Points
+
+- **New gate**: add a row to the 9-gate table here + add the gate-implementation in `aegis foundation verify` CLI command code (`packages/cli/src/commands/foundation/verify.ts`). Update preset YAML schema to allow the new gate's threshold-block. Update each `presets/<use-case>.yaml` to opt-in or opt-out.
+- **Per-project threshold-overrides**: a project's `aegis.config.json` can override the preset's threshold for one gate (e.g., a starter-template might cap aegis-scan target at 800 instead of 950). Don't override in code; override in config.
+- **Custom gate-implementations**: for organisation-specific gates (e.g., "all images must be optimised"), add them as `presets/<use-case>.yaml` `custom_gates:` entries pointing at a node-script that returns `{name, pass, output}`. Skill calls the script as if it were a built-in gate.
+- **Quick-vs-final composition**: extend the gate-table with a `mode` column listing `quick` / `final` / `both`. The CLI flag selects which subset runs.
+- **Reporter formats**: report-rendering belongs in `packages/reporters` (existing). This skill emits the structured JSON; reporters render to HTML / SARIF / Markdown / etc.