@event4u/agent-config 8.13.0 → 9.1.0

package/dist/agent-src/skills/humanizer/references/fixtures.md

@@ -0,0 +1,70 @@
+# Humanizer worked fixtures
+
+> On-demand fixtures for the [`humanizer`](../SKILL.md) skill — the
+> behavioral cases the U2 (style/stance separation) and U5 (six-signal
+> voice-match) verify clauses reference
+> (road-to-ecosystem-harvest-prose-authenticity, Source I).
+
+## Fixture 1 — stance survives the style pass (U2)
+
+A humanize pass lowers the AI signal; it must **not** soften a refusal or a
+disagreement into agreement. Input takes a firm negative position with two
+Tier-High tells (sycophancy + chat artifact + significance inflation):
+
+**Before (AI-toned refusal):**
+
+> Great question! Unfortunately, I'm not able to merge this to `main` right
+> now — doing so would mark a pivotal moment that bypasses the review gate.
+> Let me know if you'd like me to walk through the alternatives!
+
+**After (humanized — tells gone, refusal intact):**
+
+> I can't merge this to `main` — it would skip the review gate. The
+> alternatives are to open a PR for review or to get an explicit override
+> from a maintainer.
+
+The rewrite removed the flattery, the chat artifact, and the significance
+inflation, and **kept the "no"**. A rewrite that turned this into "I could
+probably merge this if you'd like!" would have corrupted the stance — a
+defect, not a humanize. Same rule for hedged-because-genuinely-uncertain
+claims: uncertainty the author actually holds stays.
+
+## Fixture 2 — two voice samples, measurably different targets (U5)
+
+The six-signal extraction produces distinct targets for distinct samples —
+matching moves the draft toward the sample's values, never toward a generic
+"human" vibe.
+
+**Sample A — terse operator:**
+
+> Deploy failed. Rolled back. Root cause: the migration locked the orders
+> table for 40s. Fix lands tomorrow.
+
+| Signal | Sample A target |
+|---|---|
+| Sentence-length rhythm | very short, uniform (4–8 words) |
+| Vocabulary register | plain / operational |
+| Punctuation habits | periods only; no dashes, no parentheticals |
+| Hedging density | zero |
+| Structural cadence | clipped declaratives, no lists |
+| Idiom | incident-log shorthand ("root cause:", "lands") |
+
+**Sample B — discursive essayist:**
+
+> What struck me, reading the migration post-mortem again, was how ordinary
+> the failure looked in advance — a lock we'd all seen a hundred times, on a
+> table nobody thought of as hot until, suddenly, it was.
+
+| Signal | Sample B target |
+|---|---|
+| Sentence-length rhythm | long, winding; one sentence per idea |
+| Vocabulary register | reflective / literary |
+| Punctuation habits | em dashes + nested clauses (fingerprint allows dashes) |
+| Hedging density | moderate ("looked", "thought of as") |
+| Structural cadence | single flowing paragraph |
+| Idiom | narrative asides ("What struck me…") |
+
+The two targets diverge on every axis — a draft matched to A is not a draft
+matched to B. Sample B is also a case where the dash-density default is
+**suppressed**: the fingerprint genuinely writes in dashes, so the fingerprint
+wins (SKILL § voice precedence).

package/dist/agent-src/skills/judge-bug-hunter/SKILL.md

@@ -70,7 +70,13 @@ not reviewable — flag it and stop.
 - Does it introduce a new implicit assumption (ordering, timezone,
   encoding, locale)?
 
-### 4. Verdict
+### 4. False-positive gate — restate before you flag
+
+Before an issue enters the verdict, restate as one falsifiable sentence naming the concrete input or state that triggers it + wrong behavior that follows. Issue whose trigger you cannot name from the diff is not a finding — drop it (or return `revise` asking for missing context, never a speculative flag).
+
+For 🔴 findings, run devil's-advocate pass before finalizing: actively try to refute (guard upstream in same diff? caller already validates? branch unreachable for claimed input?). Models systematically overrate severity — a 🔴 that survives refutation is credible; one never challenged is noise. Reject rationalizations "it looks wrong" (pattern-recognition is not analysis) and "flag it just in case" (over-reporting erodes the verdict's trust).
+
+### 5. Verdict
 
 | Verdict  | When to return it |
 |---|---|

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

@@ -188,6 +188,16 @@ When generating Laravel code:
 - Do NOT use facades in service classes — use dependency injection.
 - Do NOT skip middleware for route groups that need authentication.
 
+## Known pitfalls
+
+| Symptom | Root cause | Fix |
+|---|---|---|
+| A list endpoint fires hundreds of queries / is slow under load | N+1: a relation is accessed inside a loop without eager loading | Eager-load with `with('relation')`; enable `Model::preventLazyLoading()` in non-prod to catch it early |
+| Config changes / new env vars have no effect in production | `config:cache` cached the old config, and `env()` returns `null` once config is cached | Read env only in `config/*`, use `config()` elsewhere; re-run `config:cache` on deploy |
+| A form field silently isn't saved | The attribute isn't in `$fillable` and mass-assignment drops it | Add it to `$fillable` (or set it explicitly); never blanket-`$guarded = []` on user input |
+| Queued jobs never run / run with stale code | No worker is running, or workers weren't restarted after a deploy so they hold the old code in memory | Run/supervise `queue:work`; `queue:restart` on every deploy |
+| Timestamps or times are off by hours | Comparing/formatting a Carbon instance without honoring `config('app.timezone')` vs the DB's UTC storage | Store UTC; convert for display; set the app timezone explicitly, don't assume server local time |
+
 ## Gotcha
 
 - `env()` only works in config files — use `config()` everywhere else.

package/dist/agent-src/skills/launch-readiness/SKILL.md

@@ -68,6 +68,41 @@ Walk the diff with the following gates:
 Cells without evidence block the launch — surface, do not
 hand-wave.
 
+### 2b. Epistemics block — the diagnostic report (contract-backed)
+
+For a consumer-facing diagnostic (not just the merge decision), emit a
+report per [`docs/contracts/prelaunch-diagnostics.md`](../../../docs/contracts/prelaunch-diagnostics.md)
+(schema: `prelaunch-report.schema.json`). Rules:
+
+- **Coverage backbone** — diagnose exactly the fixed area vocabulary
+  (`prelaunch-areas.yml`): auth · migrations · secrets · observability ·
+  rollback · agent-governance. No ad-hoc areas.
+- **Every area gets one state:** `pass` (cited evidence REQUIRED) ·
+  `finding` (IDs listed) · `unknown` (honest default — **absence of
+  findings is Unknown, never an automatic Pass**) · `not-applicable`
+  (reason required).
+- **Findings carry immutable IDs** (`AC-<AREA>-NNN`) — retitle freely,
+  never re-assign; the ID is the diff key across runs.
+- **Verdict:** any open P0 → NOT ready, regardless of every other area;
+  any open P1 or a launch-gate area not at pass/N-A → NOT ready. Ready is
+  the residual state, never the default.
+- **Questions section** — list the questions that would change the
+  diagnosis; the next run converts them into evidence or findings.
+- Validate + verdict via
+  `./scripts-run src/scripts/prelaunch_diagnostics validate <report.json>`;
+  regression-gate against the committed baseline via
+  `… diff <baseline> <current> --ci` (contract § 4–6).
+
+### 2c. Fix loop (approval-gated, read-only diagnostic)
+
+Rank open findings by severity, then launch-gate membership; propose the
+**safest first approval batch** (reversible, small blast radius — explicitly
+not the full backlog). Status vocabulary per finding: `open · fixed ·
+accepted-risk · deferred-with-reason · suppressed-with-evidence ·
+not-applicable` — everything except open/fixed carries a reason. Rescore
+whenever evidence changes. The diagnostic itself never mutates the project;
+fixes flow through the normal approval-gated engines.
+
 ### 3. Plan the rollout
 
 - **Mechanism** — flag, canary cohort, blue-green, immediate.

package/dist/agent-src/skills/llm-provider-knowledge/SKILL.md

@@ -0,0 +1,146 @@
+---
+model_tier: inherit
+name: llm-provider-knowledge
+description: "Before stating any specific fact about an LLM provider's product — models, pricing, limits, context windows, SDK/API — for OpenAI, Gemini, Claude & others, verify against official docs, not memory."
+source: package
+domain: process
+personas: []
+workspaces:
+  - agent-config-maintainer
+  - engineering
+  - product
+  - founder
+  - small-business
+  - gtm
+  - ops
+packs:
+  - meta
+trust:
+  level: experimental
+install:
+  removable: true
+execution:
+  type: manual
+---
+
+# llm-provider-knowledge
+
+Verify LLM-provider product facts against **official documentation**, never
+memory. This skill is the multi-provider sibling of Claude Code's bundled
+`product-self-knowledge` — extended to OpenAI, Google Gemini, Anthropic,
+Mistral, xAI, DeepSeek, Cohere, and Meta Llama, and portable to every host this
+package projects to (not just Claude Code).
+
+**This skill is a signpost, not a library.** It routes you to the authoritative
+source and forces a source-cited answer. It does **not** cache model IDs,
+context windows, prices, or rate limits — those churn constantly, and a cached
+copy is exactly the stale "from memory" answer this skill exists to prevent.
+
+## When to use
+
+- Your reply would state a specific fact about a provider's product: a model ID
+  or its context window, token pricing, a rate/quota limit, an SDK/API detail
+  (endpoint, parameter, auth, batch, streaming, function-calling shape), or a
+  consumer-app plan limit (ChatGPT/Gemini/Claude app tiers).
+- Coding against a provider SDK where a wrong model name, parameter, or limit
+  would break at runtime.
+- Content or comparisons that assert provider capabilities or pricing.
+- Any time you would otherwise answer such a fact from training data — it may be
+  outdated or wrong.
+
+## When NOT to fire
+
+- Ordinary SDK code that asserts **no** product fact (wiring a call whose model
+  and params the user already gave).
+- The user already supplied the verified fact — use it; don't re-litigate.
+- Writing provider-specific prompt grammar → `prompt-engineering-patterns`.
+- Choosing which model to use for the host → `model-recommendation` (never
+  recommend another vendor's model over the host's; this skill only reports
+  facts, it does not steer model choice).
+- Image-provider selection → `image-provider-routing`.
+
+## Core principles
+
+1. **Accuracy over guessing** — if unsure, route to the docs; never assert.
+2. **Distinguish products** — a provider's API, its developer platform, and its
+   consumer app are separate surfaces with separate facts and separate docs.
+3. **Source everything** — every product fact in the reply carries an official
+   URL. No URL → not verified → don't state it as fact.
+4. **Route, don't cache** — hand off to the live docs; do not transcribe
+   volatile specs into the reply as if durable.
+
+## Provider routing table
+
+Route to the **stable root** and read live from there — do not deep-link to
+pages that churn. Prefer a provider's machine-readable index where one exists.
+
+| Provider | Docs root | API reference | Product / support |
+|---|---|---|---|
+| **OpenAI** (GPT) | `platform.openai.com/docs` | `platform.openai.com/docs/api-reference` | `help.openai.com` |
+| **Google Gemini** | `ai.google.dev/gemini-api/docs` | `ai.google.dev/api` | `support.google.com` (Gemini app) |
+| **Anthropic** (Claude) | `docs.claude.com/en/docs` (index: `/en/docs_site_map.md`) | `docs.claude.com/en/api/overview` | `support.claude.com` |
+| **Mistral** | `docs.mistral.ai` | `docs.mistral.ai/api` | `help.mistral.ai` |
+| **xAI** (Grok) | `docs.x.ai` | `docs.x.ai/developers` | `x.ai` |
+| **DeepSeek** | `api-docs.deepseek.com` | `api-docs.deepseek.com/api` | `platform.deepseek.com` |
+| **Cohere** | `docs.cohere.com` (index: `docs.cohere.com/llms.txt`) | `docs.cohere.com/reference` | `dashboard.cohere.com` |
+| **Meta Llama** | `llama.com` (dev docs: `ai.developer.meta.com/docs`) | `ai.developer.meta.com/docs` | `llama.com` |
+
+**Claude Code specifics** (install, Node.js requirement, MCP, config):
+`docs.anthropic.com/en/docs/claude-code/claude_code_docs_map.md`.
+
+**Hosted access** (not a distinct vendor): Azure OpenAI, AWS Bedrock, and
+Google Vertex AI resell the underlying vendor's models. Route to BOTH the
+underlying vendor's row above AND the cloud's own docs (`learn.microsoft.com`,
+`docs.aws.amazon.com/bedrock`, `cloud.google.com/vertex-ai`) — model IDs,
+quotas, and regions differ from the vendor's direct API.
+
+## Procedure
+
+1. **Identify the provider and the surface** — API / developer platform /
+   consumer app. A ChatGPT-Plus limit is not an OpenAI-API rate limit.
+2. **Pick the row + column** from the table; go to the stable root.
+3. **Read the live docs** for the exact fact (navigate from the root; follow
+   the provider's own index / `llms.txt` where present).
+4. **State the fact with its source URL.** If the docs can't be reached or are
+   ambiguous, say so and point the user at the root rather than guessing.
+5. **Never transcribe a volatile spec as durable** — frame it as "per <URL> as
+   of now"; the source is authoritative, the reply is a pointer.
+
+## Output format
+
+Every reply that states a provider product fact MUST include:
+
+1. **The fact, scoped to the product surface** — name the provider AND which
+   surface (API / platform / consumer app) it applies to.
+2. **The official source URL** — the specific docs page the fact came from (or
+   the stable root when you're directing the user to read it themselves).
+3. **A freshness caveat when the fact is volatile** (pricing, limits, model
+   availability): "verify at <URL> — these change without notice."
+
+## Do NOT
+
+- **Do NOT** state a model ID, context window, price, or rate limit from
+  memory — route to the docs and cite the URL, or say you're unsure.
+- **Do NOT** transcribe a volatile spec (pricing, limits, model availability)
+  into the reply as if durable — frame it as "per <URL> as of now".
+- **Do NOT** conflate a provider's API with its consumer app — they carry
+  different limits and different docs.
+- **Do NOT** steer the user to another vendor's model over the host's — that is
+  `model-recommendation`; this skill reports facts neutrally.
+- **Do NOT** cache a provider's docs into this skill. When a root URL moves,
+  fix the one table row; a mismatch a user reports is a signal to correct the
+  row, never to start transcribing pages here.
+
+## Gotcha
+
+- **Provider docs URLs churn** (Meta's Llama dev-docs host redirected during
+  this skill's authoring). That is *why* the skill links to stable roots and
+  reads live — a deep-linked page memorised here would rot. If a root itself
+  moves, fix the one table row; never start caching pages to compensate.
+- **Do not conflate surfaces.** "Gemini" the app and the Gemini API have
+  different limits and different docs; the same for ChatGPT vs the OpenAI API
+  and Claude.ai vs the Claude API.
+- **Redundant with the harness on Claude Code.** Claude Code's own
+  `product-self-knowledge` also fires for Anthropic facts — both route to the
+  same Anthropic docs, so the overlap is harmless. On every other host this is
+  the only such skill.

package/dist/agent-src/skills/llm-provider-knowledge/evals/triggers.json

@@ -0,0 +1,20 @@
+{
+  "skill": "llm-provider-knowledge",
+  "last_eval": "2026-07-14",
+  "description": "7 should-trigger + 6 should-not-trigger. Should-trigger covers specific product-fact claims (context window, pricing, rate limit, API detail, model spec, consumer-app plan limit) across OpenAI, Google, Anthropic, Mistral, DeepSeek, Cohere. Should-not-trigger covers near-misses: SDK wiring with a user-supplied model, prompt authoring (prompt-engineering-patterns), model choice for the host (model-recommendation), image-provider selection (image-provider-routing), a user-supplied fact, and a plain SDK refactor.",
+  "queries": [
+    {"q": "what's the context window of GPT-5?", "trigger": true},
+    {"q": "how much does Gemini 2.5 Pro cost per million input tokens?", "trigger": true},
+    {"q": "what are the rate limits on the Anthropic API for tier 1?", "trigger": true},
+    {"q": "does the Mistral API support function calling, and what parameter enables it?", "trigger": true},
+    {"q": "what's the max output length for DeepSeek's chat model?", "trigger": true},
+    {"q": "how many messages does ChatGPT Plus allow in the app per window?", "trigger": true},
+    {"q": "what embedding dimension does Cohere's embed model return?", "trigger": true},
+    {"q": "wire up an openai chat completions call using the model id I already gave you", "trigger": false, "note": "SDK wiring; user supplied the model — no unverified product fact asserted"},
+    {"q": "write a good prompt to make Gemini summarize this document", "trigger": false, "note": "prompt authoring → prompt-engineering-patterns"},
+    {"q": "which model should I use for this task on my current host?", "trigger": false, "note": "model choice → model-recommendation (never steer to another vendor)"},
+    {"q": "route this logo-with-text image to the right generation provider", "trigger": false, "note": "image-provider selection → image-provider-routing"},
+    {"q": "I already know Claude Sonnet has a 200k context window — just use that number", "trigger": false, "note": "user supplied the verified fact; use it, do not re-litigate"},
+    {"q": "refactor this function that calls the Anthropic SDK to add retries", "trigger": false, "note": "plain code refactor; asserts no product fact"}
+  ]
+}

package/dist/agent-src/skills/merge-conflicts/SKILL.md

@@ -43,6 +43,27 @@ For each conflicted file:
 3. **Understand "theirs"** — what does the incoming branch intend?
 4. **Check if both changes are needed** — often both sides added different things.
 
+### 2b. Merge Resolution Plan — mandatory before touching a conflict
+
+After reading both sides, write the plan; under `autonomous-execution` the
+approval gate applies (a standing mandate states the plan and proceeds; an
+interactive session surfaces it and waits):
+
+```
+## Merge Resolution Plan
+- Conflicts: {N files / M hunks}
+- Execution order: {dependency leaves first — a file nothing else imports
+  resolves before the files that import it}
+| file | strategy | rationale |
+|---|---|---|
+- Decisions needed from the user: {semantic/deleted-modified items, or none}
+- Validation: {targeted checks to run after resolution}
+```
+
+**Backup before resolution:** every deleted-modified file is copied to a
+temp path (`$TMPDIR/merge-backup-<ts>/<file>`) and the path noted in the
+plan BEFORE any resolution touches it.
+
 ### 3. Resolution strategies
 
 | Situation | Strategy |
@@ -54,6 +75,8 @@ For each conflicted file:
 | Migration conflicts (same timestamp) | **Rename** — adjust timestamp to avoid collision |
 | Auto-generated files (OpenAPI spec, baselines) | **Regenerate** — resolve source, then regenerate the output |
 | Formatting-only conflicts | **Accept either** — then run quality tools to normalize |
+| Import-block conflicts (both sides added imports) | **Keep both** — union the imports, drop duplicates, let the linter order them |
+| Binary files (images, archives, compiled assets) | **Pick one side whole** — never splice; regenerate from source if generated, else ask which side wins |
 
 ### 4. File-type specific rules (stack-aware)
 
@@ -104,6 +127,13 @@ For each conflicted file:
 - Import statement ordering
 - Formatting-only differences
 
+### 5b. Resolution log — one line per conflict
+
+Every resolved conflict gets a one-line explanation ("kept both — additive
+imports"; "took theirs — lockfile regenerated") collected into the final
+summary: the auditable log the reviewer reads instead of re-deriving each
+hunk decision.
+
 ### 6. Verify after resolution
 
 After resolving ALL conflicts:

package/dist/agent-src/skills/pdf-tools/SKILL.md

@@ -0,0 +1,101 @@
+---
+model_tier: medium
+name: pdf-tools
+description: "Use when creating, merging, splitting, filling, or extracting from a PDF — library-per-task, output validated. Triggers on 'merge these PDFs', 'fill this PDF form', 'split the PDF', 'create a PDF'."
+status: active
+tier: senior
+domain: process
+compatibility: "Requires consumer-installed PDF libraries: pypdf (merge/split/rotate/encrypt/extract), reportlab (create), a form library for AcroForm fill; an OCR engine (e.g. tesseract) only for the OCR task. No LibreOffice dependency. Ships zero runtime in this package."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# pdf-tools
+
+Wing-1 engineering skill for **PDF write/transform** — `markitdown` reads a PDF
+to Markdown; this creates, merges, fills, and extracts. Ships zero runtime: the
+agent drives libraries the consumer has. Pattern re-implementation only.
+
+## When to use
+
+- "Merge / split / rotate / encrypt these PDFs."
+- "Fill this PDF form (AcroForm) with these values."
+- "Create a PDF from this content."
+- "Extract the text / tables from this PDF" (structured extraction beyond `markitdown`'s Markdown).
+- "OCR this scanned PDF."
+
+Do NOT use for: PDF → Markdown ingestion (`markitdown`); Word (`docx-authoring`).
+
+## Procedure
+
+### 1. Library per task — do not force one tool
+
+| Task | Library path |
+|---|---|
+| merge / split / rotate / encrypt | pypdf — page-level operations, no rendering |
+| create from content | reportlab (canvas / platypus) |
+| form-fill (AcroForm) | a form-aware library; map field name → value, then flatten if the form must not be re-editable |
+| text / table extraction | a text-layer extractor; tables need a layout-aware pass, not naive text |
+| OCR (scanned/image PDF) | an OCR engine over rasterized pages — ONLY when there is no text layer |
+
+### 2. Decide flatten-or-keep on form fills
+
+A filled AcroForm stays editable unless flattened. Flatten when the PDF is a
+final artifact (an invoice, a signed form); keep fields when the recipient must
+edit further. State which you chose — a silently-editable "final" form is a
+correctness bug.
+
+### 3. Validate — assert output validity, do not trust the write
+
+1. Re-open the output with pypdf; assert `len(reader.pages)` matches the expected count (merge = sum; split = 1 per part).
+2. For a form-fill: read back one field value (pre-flatten) or extract the rendered text (post-flatten) and assert the value is present.
+3. For create: assert the file opens and page 1 carries expected text.
+
+## Output format
+
+1. The output PDF path(s).
+2. Validation: page count matches expected ✅, read-back value/text present ✅.
+3. For fills: flatten decision stated (flattened / kept-editable + why).
+
+## Gotcha
+
+**OCR is a last resort, not the default extraction path.** Running OCR over a
+PDF that already has a text layer produces worse output (OCR errors) than the
+existing text and burns time. Check for a text layer first; OCR only when it is
+genuinely absent.
+
+- **Editable "final" form:** a filled AcroForm left un-flattened ships as a "signed invoice" the recipient can silently alter → flatten when the artifact is final.
+
+## Do NOT
+
+- Do NOT bundle a Python toolkit in this package — drive the consumer's libraries (zero-runtime posture).
+- Do NOT OCR a PDF that has a text layer.
+- Do NOT leave a "final" filled form editable without saying so.
+- Do NOT claim success on "file written"; claim it only after the re-open + page-count assertion.
+
+## Related Skills
+
+**WHEN to use this**
+
+- The task creates, merges, splits, rotates, encrypts, or form-fills a PDF.
+- Structured text/table extraction beyond `markitdown`'s Markdown, or OCR of a scanned PDF.
+
+**WHEN NOT to use this**
+
+- PDF → Markdown ingestion → [`markitdown`](../markitdown/SKILL.md).
+- Word documents → [`docx-authoring`](../docx-authoring/SKILL.md); spreadsheets → [`spreadsheet-authoring`](../spreadsheet-authoring/SKILL.md).
+
+## When the agent should load this
+
+- "Merge / split / rotate these PDFs."
+- "Fill this PDF form."
+- "Create a PDF from this content."
+- "Extract the tables from this PDF / OCR this scan."
+
+## Output
+
+1. **Output PDF(s)** — the path(s). Cite as `pdf-output`.
+2. **Validation receipt** — page count matches expected ✅, read-back value/text present ✅. Cite as `pdf-validation`.
+3. **Fill decision** — present on form-fills: flattened / kept-editable + why. Cite as `pdf-fill-decision`.

package/dist/agent-src/skills/quality-tools/evals/evals.json

@@ -0,0 +1,15 @@
+{
+  "skill": "quality-tools",
+  "_calibration": "Seed for eval-schema v2 (ecosystem-harvest skill-quality-gates Phase 2). tool-choice + trajectory assertions are trace-gated: pass:null (manual-pending) in CI until a recorded tool-trace.json exists.",
+  "scenarios": [
+    {
+      "id": "runs-project-pinned-tools",
+      "prompt": "Fix the failing lint on the changed files.",
+      "environment": "a project whose pinned quality CLI is defined in its task runner",
+      "assertions": [
+        { "kind": "tool-choice", "must_use": ["bash"], "must_not_use": [] },
+        { "kind": "trajectory_budget", "n": 8 }
+      ]
+    }
+  ]
+}

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

@@ -40,6 +40,30 @@ Do NOT use when:
 
 ## Procedure: Security audit
 
+### 0. False-positive gate — restate the claim before reporting
+
+Before any finding enters report, restate as one falsifiable sentence naming all three:
+
+1. **Privilege level** — access attacker already has (anonymous, authenticated user, tenant admin, CI runner).
+2. **Execution context** — where vulnerable code runs (request handler, queue worker, sandboxed template, build step).
+3. **Attacker precondition** — concrete state or input attacker must control to trigger it.
+
+Any of the three not concretely nameable → **not a finding yet** — trace further or drop with one-line reason.
+
+**Rationalizations to Reject:**
+
+| Rationalization | Reality |
+|---|---|
+| "It looks dangerous" | Pattern-recognition is not analysis — trace the full data flow from entry to sink first |
+| "This is clearly critical" | Complete a devil's-advocate pass — models systematically overrate severity |
+| "Report it just in case" | Over-reporting erodes trust; an unverifiable finding is noise, not diligence |
+| "Same pattern as a known CVE" | Same pattern ≠ same preconditions — verify the preconditions hold in THIS codebase |
+
+**Standard vs. Deep verification routing:**
+
+- **Standard** — traced data flow + all three claim elements named → report with normal field list.
+- **Deep** — severity High/Critical, OR precondition chain crosses trust boundary you did not trace → devil's-advocate pass first: actively try to refute finding (existing middleware? framework default? type system? config?). Report only what survives; killed findings listed one-line under *Rejected candidates* so triage is auditable.
+
 ### 1. Map attack surface
 
 Identify all entry points where untrusted data enters:
@@ -78,6 +102,9 @@ User Input → Controller → Validation → Service → DB/File/External
 | **Secret exposure** | Hardcoded credentials, secrets in logs, `.env` in public dir |
 | **Rate limiting** | Missing throttle on auth endpoints, password reset, API |
 | **Header injection** | User input in response headers, email headers |
+| **Insecure defaults / fail-open** | Guards that allow on error (`catch { return true }` in an authz check), default-allow matchers, debug mode defaulting on, permissive CORS/`verify=false` fallbacks, feature flags whose missing value grants access |
+
+Worked example (fail-open): `if (!$gate->check($user)) { … }` wrapped in `try/catch` that logs and **continues** fails open — exception in gate grants access. Finding shape: Category *Insecure defaults*, Evidence the catch block `file:line`, Fix *fail closed — rethrow or deny on gate error*.
 
 ### 4. Framework-specific checks
 
@@ -108,6 +135,8 @@ For each vulnerability:
 - **Fix:** concrete mitigation
 - **Confidence:** Low / Medium / High
 
+After findings, add **Rejected candidates** section: one line per look-dangerous-but-benign pattern the Step-0 gate killed, with traced reason ("raw SQL string is a static migration constant — no user input reaches it"). Audit that rejects nothing has usually skipped the gate.
+
 ## Integration with other skills
 
 - **analysis-autonomous-mode** — routes here when security concerns are detected

package/dist/agent-src/skills/security-maturity-assessment/SKILL.md

@@ -0,0 +1,90 @@
+---
+model_tier: high
+name: security-maturity-assessment
+description: "Use when the user wants a security-maturity scorecard / posture assessment of a module — category ratings with evidence, not a vulnerability hunt. Also on 'wie sicher ist dieses Modul aufgestellt?'"
+domain: quality
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# security-maturity-assessment
+
+Rate how mature a module's security **posture** is — category by category, every rating backed by `file:line` evidence — instead of hunting individual vulnerabilities. Output is a scorecard a maintainer can re-run and diff, not a finding list.
+
+## When to use
+
+- "How mature / well-set-up is this module's security?" — posture, not holes
+- Baseline before a hardening effort, or re-assessment after one
+- A stakeholder needs a defensible rating per category with cited evidence
+
+Do NOT use when:
+
+- Hunting concrete vulnerabilities — route to [`security-audit`](../security-audit/SKILL.md)
+- One route/action's authorization chain — route to [`authz-review`](../authz-review/SKILL.md)
+- Pre-implementation threat model for a new feature — route to [`threat-modeling`](../threat-modeling/SKILL.md)
+- Writing new secure code — route to [`security`](../security/SKILL.md)
+- AI-agent config/behaviour review — route to [`agent-security-review`](../agent-security-review/SKILL.md)
+
+## The nine categories
+
+| # | Category | Critical? | What to inspect |
+|---|---|---|---|
+| 1 | Input validation | **Yes** | Request-boundary validation primitives on every entry point; no inline ad-hoc checks |
+| 2 | Authorization | **Yes** | Per-object ownership/tenant checks, policy coverage, field-level access |
+| 3 | Secrets handling | **Yes** | No hardcoded creds; env/vault usage; secrets absent from logs and VCS |
+| 4 | Error handling | No | No swallowed exceptions; no stack traces / internals leaked to clients |
+| 5 | Logging & audit | No | Security events (auth, permission denials, admin actions) logged; no PII in logs |
+| 6 | Dependency hygiene | No | Lockfiles present; known-CVE scan wired; update cadence visible |
+| 7 | Data boundaries | No | Serializers/resources whitelist fields; exports/queues don't leak internals |
+| 8 | Tenant isolation | **Yes** (multi-tenant only; else N/A) | Tenant scoping on queries, jobs, caches; cross-tenant negative tests |
+| 9 | Security test coverage | No | Negative tests exist (401/403/404 paths, abuse cases), not only happy-path |
+
+## Rating rubric
+
+| Rating | Meaning |
+|---|---|
+| **Missing** | No control exists for the category |
+| **Weak** | Ad-hoc, inconsistent — some paths covered, most not |
+| **Moderate** | Control present and usual, with named gaps |
+| **Satisfactory** | Consistent across the surface; minor gaps only |
+| **Strong** | Consistent AND enforced (CI gate, test, linter) or negatively tested |
+
+## Procedure
+
+1. **Scope** — name the module/paths under assessment; list entry points (routes, jobs, commands, webhooks). Scorecard without stated scope is not reproducible.
+2. **Assess each category** — inspect the code the category names. Every rating cites evidence:
+   - Positive evidence: `file:line` of the control (`app/Http/Requests/…:12`).
+   - Absence evidence: the searches run that came back empty (name the grep patterns) — "not found" beats "probably missing".
+   - Multi-tenant N/A: single-tenant systems rate category 8 `N/A`; drops out of the roll-up.
+3. **Roll up deterministically** — overall rating is computed, not vibed:
+   - `overall = min( median(all rated categories), one step above the lowest critical-category rating )`
+   - Consequences: any critical category **Missing** caps overall at **Weak**; any critical **Weak** caps overall at **Moderate**. Non-critical categories move the median but never lift the cap.
+4. **Recommend** — max 3 next steps, ordered by which would raise the overall rating (fix the lowest critical category first).
+
+## Output format
+
+1. **Scope block** — module/paths + entry-point list, so the scorecard is re-runnable.
+2. **Scorecard table** — one row per category: `Category | Rating | Evidence (file:line or named empty searches) | Gap`. Every row MUST carry evidence; a rating without a citation is invalid.
+3. **Overall rating** — with the roll-up shown (`median=…, lowest critical=…, cap=… → overall=…`), never a bare verdict.
+4. **Top-3 next steps** — ordered by roll-up impact.
+
+## Gotcha
+
+- The model tends to rate from vibes ("looks well-structured") — a rating row without `file:line` or named empty searches is invalid; redo it.
+- Don't let a Strong non-critical category mask a Weak critical one — the cap rule exists precisely because a polished logging setup does not offset missing authorization.
+- A vulnerability found mid-assessment is **out of scope** for the scorecard — note it and route to [`security-audit`](../security-audit/SKILL.md) (with its false-positive gate) instead of inlining findings here.
+
+## Do NOT
+
+- Do NOT emit a rating without evidence — every row cites `file:line` or the empty searches that prove absence.
+- Do NOT average away critical categories — the deterministic cap always wins.
+- Do NOT turn the scorecard into a finding list — posture assessment and vulnerability hunting are different deliverables.
+- Do NOT assess unscoped ("the whole app") when the user named a module.
+
+## See also
+
+- [`security-audit`](../security-audit/SKILL.md) — vulnerability hunting with the false-positive gate.
+- [`defense-in-depth`](../defense-in-depth/SKILL.md) — layering controls the scorecard checks for.
+- [`ai-code-blindspots`](../ai-code-blindspots/SKILL.md) — the per-surface invisible-controls checklist.