@aegis-scan/skills 0.4.0 → 0.5.0

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

@@ -26,8 +26,9 @@ Before responding to ANY user request, this skill MUST:
 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.
+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.
 
@@ -105,7 +106,87 @@ When the user says "commit" / "push" / "release" — orchestrator invokes `aegis
 
 ### 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.
+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`.
 
 ---
 
@@ -113,12 +194,14 @@ When the user says "fertig" / "handover" / "session-ende" / "übergabe" — orch
 
 Before declaring the orchestrator-handoff complete for a session:
 
-- [ ] Bootstrap-checklist completed (all 6 steps, no skipping)
+- [ ] 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.
 

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

@@ -1,17 +1,17 @@
 <!-- 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.
+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: "9"
+  enforced_quality_gates: "10"
   pre_done_audit: "true"
 ---
 
-# aegis-quality-gates — 9-Gate Verifier
+# 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.
 
@@ -55,7 +55,7 @@ Be the single source of truth for "is this build ready to commit / push / publis
 
 ## Process
 
-### The 9 gates (sequence + thresholds per spec §6)
+### The 10 gates (sequence + thresholds per spec §6)
 
 | # | Gate | Command | Threshold | Mode |
 |---|---|---|---|---|
@@ -68,6 +68,7 @@ Be the single source of truth for "is this build ready to commit / push / publis
 | 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
 
@@ -87,13 +88,72 @@ Exit 0 if all applicable gates pass. Exit 1 otherwise — non-zero exit triggers
 
 ---
 
+## 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 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
+- [ ] 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
@@ -107,7 +167,7 @@ This skill's own success criteria (it's a verifier-of-verifiers):
 - ❌ 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`.
+- ❌ 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.
 
@@ -115,7 +175,7 @@ This skill's own success criteria (it's a verifier-of-verifiers):
 
 ## 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.
+- **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.