@aegis-scan/skills 0.2.1 → 0.5.0

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

@@ -0,0 +1,255 @@
+<!-- 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, observable + independently verifiable)
+```
+
+Don't infer from chat-context. Demand the spec.
+
+### Plans.md task discipline
+
+Every module-build creates a row in `.aegis/Plans.md` per the format defined in `aegis-orchestrator` ("Plans.md — Live Working-Plan SSOT" section). The acceptance-criteria from the feature-spec become the AC checkboxes on the task row. As phases 2-6 run, the AC are checked off; task moves DONE only when all are checked. If a phase is blocked, the AC stays unchanged + the blocker is documented in `## Blockers`.
+
+---
+
+## 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,229 @@
+<!-- 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. **Read** `.aegis/Plans.md` if present — the live working-plan SSOT (see "Plans.md" section below). Skip if missing; orchestrator initializes it during Phase 3 dispatch.
+7. **Print** to the user: `Tool-inventory: [...], Skills available: [...], Project-state: phase X, Use-case: Y, Open tasks: N`.
+8. **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. The handover-writer reads `.aegis/Plans.md` to summarize task-status into the handover doc.
+
+---
+
+## Plans.md — Live Working-Plan SSOT
+
+`.aegis/Plans.md` is the single source of truth for the **current** working plan (in-flight tasks, blockers, acceptance criteria). It complements (not replaces) `state.json` (machine-readable phase-state) and handover docs (point-in-time snapshots at session boundaries).
+
+> Concept adapted from [Chachamaru127/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness) (MIT) — their `Plans.md` SSOT pattern. AEGIS adapts the idea, not the tool: no Go binary, no marketplace plugin, no `/harness-*` verb-commands. Pure markdown discipline integrated into the existing AEGIS skill cluster.
+
+### Lifecycle
+
+1. **Initialize** — orchestrator creates `.aegis/Plans.md` on first dispatch if absent. Template is the format below.
+2. **Update** — every specialist skill that performs work updates the relevant task row (status, blockers, AC checkbox progress). Module-builder, customer-build, audit, skill-creator, dsgvo-compliance all touch this file as they work.
+3. **Summarize** — handover-writer reads Plans.md at session-end and folds the open-task-list into the handover doc's `§5 Open` section.
+4. **Reset** — when a use-case completes (e.g., customer-build hits DONE-with-proof), orchestrator archives Plans.md to `.aegis/Plans-archive/<timestamp>.md` and starts a fresh one for the next use-case.
+
+### Format
+
+```markdown
+# Plans.md — Working Plan
+
+**Use-case:** customer-build (or compliance-audit / dev-feature / aegis-self-test / skill-authoring)
+**Started:** 2026-04-28T14:00Z
+**Last updated:** 2026-04-28T15:42Z
+**Phase:** 3 of 7 (component-build)
+
+---
+
+## Tasks
+
+### T01 — [DONE] Briefing-validation against schema
+
+**AC:**
+- [x] Briefing parsed without errors
+- [x] All required schema-fields present
+- [x] Pages-list extracted with N=5 entries
+
+**Notes:** parsed-briefing.json written to .aegis/
+
+### T02 — [IN PROGRESS] Component-tree binding to project library
+
+**AC:**
+- [x] Library inventory loaded
+- [x] Pages 1-3 bound to library components
+- [ ] Pages 4-5 bound (BLOCKER: missing testimonial-component variant)
+- [ ] Component-tree exported as machine-readable JSON
+
+**Notes:** Pages 4-5 use a variant of testimonial-card that the project library does not ship. Operator decision needed: drop the variant, request library extension, or use the closest existing variant.
+
+### T03 — [PENDING] Phase-6 mid-audit
+
+**AC:**
+- [ ] aegis-scan run on the in-progress build
+- [ ] brutaler-anwalt HUNT on impressum + cookie + DSE
+- [ ] Repair-loop ≤ 3 iterations OR document blockers
+
+---
+
+## Blockers
+
+- B01 (T02) — Library variant missing for testimonial-card. Awaiting operator decision.
+```
+
+### Acceptance-Criteria template
+
+Every task carries an explicit AC list (1-N checkboxes). The discipline:
+
+- AC must be **observable** (passes a check, file exists, command exits 0, etc.) — not subjective ("looks good").
+- AC must be **complete** — task is DONE only when all AC are checked. No "looks done at 80%".
+- AC must be **independently verifiable** — another agent reading the AC list can confirm pass/fail without context from the task-author.
+
+When task is blocked, the AC stays unchanged (don't lower the bar to fit the blocker). Document the blocker explicitly in `## Blockers` section + flag in the task row.
+
+### Cross-references
+
+- `aegis-module-builder` reads Plans.md for task-AC discipline + writes back module-task progress.
+- `aegis-customer-build` writes per-phase tasks into Plans.md as it executes the 7-phase pipeline.
+- `aegis-audit` writes audit-finding tasks into Plans.md (1 task per layer-finding).
+- `aegis-handover-writer` reads Plans.md → summarizes into handover §5 Open.
+- `aegis-quality-gates` does NOT touch Plans.md — it is a stateless verifier; results go to `.aegis/verify-report.json`.
+
+---
+
+## Verification / Success Criteria
+
+Before declaring the orchestrator-handoff complete for a session:
+
+- [ ] Bootstrap-checklist completed (all 8 steps, no skipping)
+- [ ] `.aegis/Plans.md` initialized for the current use-case (or carried-over from prior session if mid-use-case)
+- [ ] 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
+- [ ] `.aegis/Plans.md` reflects the current task-state (closed tasks marked DONE, blockers documented)
+
+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,182 @@
+<!-- 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 10-quality-gate runner. Runs build / tsc / lint / tests / aegis-scan / brutaler-anwalt / lighthouse / skillforge-validate / briefing-coverage / residue-check 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, residue-check.
+model: sonnet
+license: MIT
+metadata:
+  required_tools: "shell-ops,file-ops"
+  required_audit_passes: "1"
+  enforced_quality_gates: "10"
+  pre_done_audit: "true"
+---
+
+# aegis-quality-gates — 10-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 10 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 |
+| 10 | residue-check | scan for stale references (see "Residue-Check" section below) | 0 stale refs, 0 broken cross-links | --quick + --final |
+
+### 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.
+
+---
+
+## Residue-Check (Gate 10) — Stale-Reference Detection
+
+Detects references that became stale through edits, rebases, or refactors but were not updated. The class of bug that motivated this gate: a handover-doc cited commit-SHA `c89bf3f` after a `git rebase` invalidated it, leaving an operator-procedure that pointed at a non-existent commit.
+
+> Concept adapted from [Chachamaru127/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness)'s `harness doctor --residue` command (MIT). AEGIS adapts the methodology, not the binary: pure shell + grep, integrated as gate 10 of this verifier rather than a standalone tool.
+
+### What counts as "residue"
+
+| Residue class | Detection |
+|---|---|
+| Stale commit-SHAs in handover docs | Each 7-40 hex SHA in `*.md` is `git cat-file -e <sha>`-tested; missing → stale |
+| Broken markdown cross-links to local files | Each `](./...)` or `](../...)` link is path-tested; missing target → broken |
+| Orphan path references in skill bodies | Paths like `packages/skills/skills/<...>/<skill>/<...>` are existence-tested |
+| Dead `<!-- aegis-local: -->` provenance refs | Header pointing at `<source>@<sha>` where `<sha>` is no longer reachable → stale fork-base |
+| `_(post-X.Y.Z)_` markers past their version | Version-X.Y.Z is current → marker is stale, content should be active |
+| Phantom skill names in `_INDEX.md` routing tables | Skill name in row → SKILL.md must exist at the cited path |
+
+### Detection commands
+
+`aegis foundation verify --residue` (planned in Phase 3 CLI per the foundation handover §5 Pri 2) implements this gate. Until then, the methodology is documented here so any agent or operator can run it manually:
+
+```bash
+# Stale SHA detection in handover docs
+for sha in $(grep -roE '\b[0-9a-f]{7,40}\b' docs/handover seitengold-build/strategy 2>/dev/null \
+              | awk -F: '{print $2}' | sort -u); do
+  git cat-file -e "$sha" 2>/dev/null || echo "STALE-SHA: $sha"
+done
+
+# Broken markdown cross-links (relative paths)
+grep -roE '\]\((\./|\.\./)[^)]+\)' packages/skills/skills/ \
+  | sed 's/.*\](\(.*\))/\1/' | sort -u \
+  | while read p; do [ -e "$p" ] || echo "BROKEN-LINK: $p"; done
+
+# Phantom _INDEX.md skill rows
+for idx in packages/skills/skills/*/_INDEX.md; do
+  awk -F'`' '/SKILL\.md`/ {print $4}' "$idx" \
+    | while read p; do [ -e "packages/skills/skills/$p" ] || echo "PHANTOM-SKILL-ROW in $idx: $p"; done
+done
+```
+
+### Threshold
+
+- **0 stale SHAs** in any tracked handover/state doc — strict
+- **0 broken cross-links** in shipped SKILL.md or `_INDEX.md` content — strict
+- **0 orphan path references** in body of any aegis-native skill — strict
+- **0 phantom skill rows** in any `_INDEX.md` — strict
+- **0 dead aegis-local headers** — strict
+
+Any non-zero count fails the gate. Output written to `.aegis/verify-report.json` under `residue: { stale_shas: [...], broken_links: [...], orphan_paths: [...], phantom_rows: [...], dead_provenance: [...] }`.
+
+### When to run
+
+- `--quick` mode (pre-commit): include residue-check (it's fast — pure grep + path tests, no compilation).
+- `--final` mode (end-of-build, pre-publish): always include.
+- `--residue` mode (operator-on-demand): runs gate 10 only, useful after a rebase or merge to verify documentation didn't fall behind.
+
+---
+
+## Verification / Success Criteria
+
+This skill's own success criteria (it's a verifier-of-verifiers):
+
+- [ ] Each of the 10 gates is implemented + integration-tested (gate fires real command, parses real output)
+- [ ] `--quick` mode runs gates 1-4 + 10 in under 30 seconds typical (so pre-commit-loop stays usable)
+- [ ] `--final` mode runs all 10 gates + writes `.aegis/verify-report.json` + prints markdown summary
+- [ ] `--residue` mode runs gate 10 only (operator-on-demand post-rebase / post-merge check)
+- [ ] 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 10-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 10-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.