stacknil · stacknil · Jul 5, 2026 · Jul 5, 2026
diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml
@@ -5,12 +5,14 @@ name: Markdown Validation
   push:
     paths:
       - "README.md"
+      - "docs/**/*.md"
       - "patterns/**/*.md"
       - "TryHackMe/**/*.md"
       - "TryHackMe/_meta/TAGS.md"
       - "notes/**/*.md"
       - "schemas/**/*.json"
       - "scripts/check_markdown.py"
+      - "scripts/check_pattern_library.py"
       - "scripts/render_readme_snapshot.py"
       - "scripts/render_tags_doc.py"
       - "scripts/generate_markdownlint_debt.py"
@@ -24,12 +26,14 @@ name: Markdown Validation
   pull_request:
     paths:
       - "README.md"
+      - "docs/**/*.md"
       - "patterns/**/*.md"
       - "TryHackMe/**/*.md"
       - "TryHackMe/_meta/TAGS.md"
       - "notes/**/*.md"
       - "schemas/**/*.json"
       - "scripts/check_markdown.py"
+      - "scripts/check_pattern_library.py"
       - "scripts/render_readme_snapshot.py"
       - "scripts/render_tags_doc.py"
       - "scripts/generate_markdownlint_debt.py"
@@ -67,6 +71,9 @@ jobs:
       - name: Verify README.md snapshot is in sync with tracked notes
         run: python scripts/render_readme_snapshot.py --check
 
+      - name: Validate pattern library contract
+        run: python scripts/check_pattern_library.py
+
       - name: Run Markdown checks
         run: python scripts/check_markdown.py
 

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -17,6 +17,16 @@ repos:
         files: >-
           ^(README\.md|TryHackMe/(?!_meta/).+\.md|notes/.+\.md|
           scripts/render_readme_snapshot\.py)$
+      - id: validate-pattern-library
+        name: validate-pattern-library
+        entry: python scripts/check_pattern_library.py
+        language: python
+        additional_dependencies:
+          - PyYAML>=6.0,<7.0
+        pass_filenames: false
+        files: >-
+          ^(README\.md|docs/.+\.md|patterns/.+\.md|schemas/pattern-library\.json|
+          scripts/check_pattern_library\.py|notes/.+\.md)$
       - id: validate-frontmatter
         name: validate-frontmatter
         entry: python scripts/check_markdown.py

diff --git a/README.md b/README.md
@@ -4,13 +4,32 @@ Public, sanitized security write-ups from authorized labs and training platforms
 
 > A local-first public knowledge base focused on methodology, reasoning, and reusable security patterns, not copy-paste exploitation.
 
+## Featured Security Patterns
+
+Current extraction metric: **8 stable reusable security patterns extracted
+from 10 distinct supporting notes**.
+
+| Pattern | Review focus |
+| --- | --- |
+| [Parser uncertainty](patterns/parsing/parser-uncertainty.md) | make unsupported input visible instead of treating it as negative evidence |
+| [Authentication burst triage](patterns/auth/authentication-burst-triage.md) | bound failure clusters without claiming compromise |
+| [Multi-user probing](patterns/auth/multi-user-probing.md) | distinguish username spread from ordinary repeated failure |
+| [Alert deduplication](patterns/detection/alert-deduplication.md) | collapse duplicate alerts without erasing evidence |
+| [Bounded correlation](patterns/detection/bounded-correlation.md) | require a reproducible join key, sequence, and window |
+| [Repository baseline governance](patterns/repository/repository-baseline-governance.md) | review suppression drift as security-adjacent code |
+| [SBOM policy warning](patterns/supply-chain/sbom-policy-warning.md) | explain a warning without inventing a package-safety verdict |
+| [Human verification boundary](patterns/ai/human-verification-boundary.md) | keep AI assistance separate from the accountable finding |
+
+The [Pattern Library](patterns/README.md) is the primary reusable output. The
+larger note corpus remains its source archive and evidence base.
+
 ## At A Glance
 
-Current public snapshot:
+Supporting source archive:
 
-- `157` active public notes
-- `100` active TryHackMe notes
-- `57` topic-organized notes under `notes/`
+- `157` public notes retained as source material
+- `100` TryHackMe source notes
+- `57` topic-organized source notes under `notes/`
 - `9` organized TryHackMe learning tracks
 - public governance for taxonomy, placeholders, publication, and maintenance
 
@@ -38,7 +57,7 @@ The emphasis is on:
 
 ## What You Will Find
 
-The live public corpus is currently centered on **TryHackMe** and supplemented by a smaller topic-organized `notes/` tree.
+The supporting source corpus is centered on **TryHackMe** and supplemented by a topic-organized `notes/` tree.
 
 | Track | Notes | Focus |
 | --- | --- | --- |
@@ -52,7 +71,7 @@ The live public corpus is currently centered on **TryHackMe** and supplemented b
 | [TryHackMe/80-blue-team](TryHackMe/80-blue-team) | `6` | SIEM, detection, analyst notes |
 | [TryHackMe/90-events](TryHackMe/90-events) | `32` | event and challenge write-ups, sanitized for publication |
 
-Additional organized notes outside the TryHackMe tree:
+Additional source notes outside the TryHackMe tree:
 
 - `notes/` currently contains `57` active public notes
 
@@ -77,9 +96,12 @@ If you are browsing this repo for the first time:
 ```text
 sec-writeups-public/
 ├── patterns/
+│   ├── ai/
 │   ├── auth/
-│   ├── detection/
 │   ├── cloud/
+│   ├── detection/
+│   ├── parsing/
+│   ├── repository/
 │   └── supply-chain/
 ├── TryHackMe/
 │   ├── 00-foundations/

diff --git a/docs/reviewer-brief.md b/docs/reviewer-brief.md
@@ -6,46 +6,53 @@ Security notes are often hard to publish safely: they either leak too much, coll
 
 ## What it does
 
-`sec-writeups-public` is a public, sanitized security note repository with:
+`sec-writeups-public` is a public, sanitized pattern library backed by a
+security source-note repository with:
 
-- a large TryHackMe-centered note corpus
-- topic-organized notes outside the training-platform tree
+- a stable pattern library extracted from supporting source notes
+- evidence-bounded links from patterns to related implementations
+- a larger TryHackMe-centered source-note corpus
 - taxonomy, placeholder, and publication governance
 - local checks that keep the public corpus maintainable
 
 ## Reviewer Evidence
 
-- Reproducible command: `python scripts/render_readme_snapshot.py --check`
-- Deterministic outputs: rendered README snapshots, generated tag docs, placeholder audit output, taxonomy docs, and markdownlint debt reports.
-- Tests / CI: local publication checks, placeholder checks, markdown checks, pre-commit hooks, and GitHub Actions maintenance workflows.
-- Release evidence: public corpus snapshot, governance docs, sanitization checklist, publication workflow, and maintenance checkpoints.
+- Reproducible command: `python scripts/check_pattern_library.py`
+- Deterministic outputs: pattern maturity, provenance counts, project links, case-study backlinks, rendered README snapshots, and generated tag docs.
+- Tests / CI: pattern-contract validation, publication checks, placeholder checks, markdown checks, pre-commit hooks, and GitHub Actions workflows.
+- Release evidence: stable pattern index, source-note links, governance docs, sanitization checklist, and maintenance checkpoints.
 - Non-goals: raw exploit logs, private evidence dumps, live target identifiers, weaponized exploit chains, or unsanitized challenge transcripts.
 
 ## Quick run
 
 ```bash
 python scripts/render_tags_doc.py --check
 python scripts/render_readme_snapshot.py --check
+python scripts/check_pattern_library.py
 python scripts/check_placeholders.py notes/80-blue-team/soc-fundamentals.md
 python scripts/check_markdown.py
 python -m pre_commit run --files notes/80-blue-team/soc-fundamentals.md
 ```
 
 ## Sample output
 
-The current public snapshot in the README reports:
+The current reviewer-facing metric is:
 
-- `111` active public notes
-- `100` active TryHackMe notes
-- `11` topic-organized notes under `notes/`
+- `8` stable reusable security patterns
+- `10` distinct supporting notes behind those stable patterns
+- `13` total cards across stable and reviewed maturity levels
 
-A representative public-safe note is `notes/80-blue-team/soc-fundamentals.md`, which uses summary-first structure, reusable concepts, and placeholders instead of live identifiers.
+A representative stable card is
+`patterns/detection/bounded-correlation.md`, which makes the signal,
+false-positive contexts, evidence limits, implementation bridge, and source
+notes independently reviewable.
 
 ## What this proves
 
 - security writing can be structured like an engineered artifact
 - publication safety can be enforced with explicit governance
-- public notes can stay reusable and maintainable instead of one-off dumps
+- source notes can be distilled into stable, reusable security patterns
+- pattern maturity and evidence links can be enforced in CI
 - reviewer-facing documentation discipline extends beyond code repos
 
 ## Safety / boundaries
@@ -63,4 +70,5 @@ A representative public-safe note is `notes/80-blue-team/soc-fundamentals.md`, w
 
 ## Next milestone
 
-Keep deepening blue-team and detection-oriented notes while improving reviewer-facing indexes for the strongest public writing paths.
+Promote reviewed cards only when new evidence or implementation work increases
+their decision value; avoid growing the source archive as an end in itself.
diff --git a/notes/80-blue-team/ai-forensics-public.md b/notes/80-blue-team/ai-forensics-public.md
@@ -341,3 +341,9 @@ Convenience can collide with privacy law, chain of custody, and admissibility.
 * NIST AI Risk Management Framework
 * legal references on the Daubert standard and expert testimony
 * privacy-preserving federated learning references
+
+---
+
+## 11. Related Patterns
+
+* [Human Verification Boundary](../../patterns/ai/human-verification-boundary.md)
diff --git a/notes/80-blue-team/containment-public.md b/notes/80-blue-team/containment-public.md
@@ -471,3 +471,9 @@ environments.
 * Prompt injection defensive guidance
 * Human-in-the-loop incident response patterns
 * Ransomware triage and evidence-validation playbooks
+
+---
+
+## 16. Related Patterns
+
+* [Human Verification Boundary](../../patterns/ai/human-verification-boundary.md)
diff --git a/notes/80-blue-team/understanding-ai-supply-chains-public.md b/notes/80-blue-team/understanding-ai-supply-chains-public.md
@@ -615,3 +615,9 @@ reproducibility, not page aesthetics.
 * SafeTensors documentation
 * PyPI analysis of the Ultralytics supply-chain attack
 * PyTorch advisory on the torchtriton dependency confusion incident
+
+---
+
+## 16. Related Patterns
+
+* [SBOM Policy Warning](../../patterns/supply-chain/sbom-policy-warning.md)
diff --git a/patterns/README.md b/patterns/README.md
@@ -1,49 +1,82 @@
 # Pattern Library
 
-Pattern Library v0.1 is the stable entry point for reusable security detection,
-triage, and review patterns. Read these cards before browsing the larger note
+This is the stable entry point for reusable security detection, triage, and
+review patterns. Read these cards before browsing the larger source-note
 archive when you need a compact, evidence-bounded defensive workflow.
 
-## Authentication
+Current extraction metric: **8 stable reusable security patterns extracted
+from 10 distinct supporting notes**.
 
-* [SSH brute-force triage](auth/ssh-bruteforce-triage.md)
-* [Multi-user probing](auth/multi-user-probing.md)
-* [Sudo burst review](auth/sudo-burst-review.md)
+## Featured Stable Patterns
 
-## Detection Engineering
+| Pattern | Primary implementation |
+| --- | --- |
+| [Parser uncertainty](parsing/parser-uncertainty.md) | LogLens |
+| [Authentication burst triage](auth/authentication-burst-triage.md) | LogLens |
+| [Multi-user probing](auth/multi-user-probing.md) | LogLens |
+| [Alert deduplication](detection/alert-deduplication.md) | telemetry-lab |
+| [Bounded correlation](detection/bounded-correlation.md) | telemetry-lab |
+| [Repository baseline governance](repository/repository-baseline-governance.md) | repo-sentinel-lite |
+| [SBOM policy warning](supply-chain/sbom-policy-warning.md) | sbom-diff-and-risk |
+| [Human verification boundary](ai/human-verification-boundary.md) | telemetry-lab |
 
-* [Alert deduplication](detection/alert-deduplication.md)
-* [Cooldown suppression](detection/cooldown-suppression.md)
-* [Bounded correlation](detection/bounded-correlation.md)
+## Reviewed Patterns
 
-## Cloud
+These cards remain useful but are not part of the featured stable set:
 
+* [SSH brute-force triage](auth/ssh-bruteforce-triage.md)
+* [Sudo burst review](auth/sudo-burst-review.md)
+* [Cooldown suppression](detection/cooldown-suppression.md)
 * [IAM policy attachment review](cloud/iam-policy-attachment-review.md)
+* [SBOM dependency diff review](supply-chain/sbom-dependency-diff-review.md)
 
-## Supply Chain
+## Maturity Model
 
-* [SBOM dependency diff review](supply-chain/sbom-dependency-diff-review.md)
+| Maturity | Meaning |
+| --- | --- |
+| `draft` | Useful hypothesis; evidence or implementation bridge is still incomplete. |
+| `reviewed` | Structurally reviewed and supported, but not yet promoted as a stable library entry. |
+| `stable` | Evidence-bounded, linked to a core implementation, and supported by at least one source note. |
+
+Every card records `maturity` and `last_reviewed` in front matter.
 
 ## Card Contract
 
-Every stable card uses the same fields:
+Every card uses the same body fields:
 
 1. **Signal**
 2. **Why it matters**
-3. **False positives**
-4. **Minimum evidence**
+3. **False-positive contexts**
+4. **Evidence limits**
 5. **Defensive next step**
-6. **Related project**
-7. **Related notes**
+6. **Related implementation**
+7. **Supporting notes**
 
-The minimum-evidence field is the claim boundary: a card should guide an
+The evidence-limits field is the claim boundary: a card should guide an
 investigation without turning a weak signal into an unsupported conclusion.
 
+## Automated Contract
+
+`python scripts/check_pattern_library.py` verifies that:
+
+* every card has valid maturity metadata and the fixed section order
+* every stable card links to an approved core implementation
+* every stable card links to at least one source note under `notes/` or `TryHackMe/`
+* the featured set contains between six and eight stable cards
+* every configured flagship case study links back to at least one pattern
+* the extraction metric matches the current stable-card provenance graph
+
+## Flagship Case Studies
+
+* [ContAInment](../notes/80-blue-team/containment-public.md)
+* [AI Forensics](../notes/80-blue-team/ai-forensics-public.md)
+* [Understanding AI Supply Chains](../notes/80-blue-team/understanding-ai-supply-chains-public.md)
+
 ## Project Bridges
 
 | Pattern area | Related project |
 | --- | --- |
-| Authentication | [LogLens](https://github.com/stacknil/LogLens) |
-| Detection engineering | [telemetry-lab](https://github.com/stacknil/telemetry-lab) |
-| Cloud review | [telemetry-lab](https://github.com/stacknil/telemetry-lab) |
+| Parsing and authentication | [LogLens](https://github.com/stacknil/LogLens) |
+| Detection and human review | [telemetry-lab](https://github.com/stacknil/telemetry-lab) |
+| Repository governance | [repo-sentinel-lite](https://github.com/stacknil/repo-sentinel-lite) |
 | Supply-chain review | [sbom-diff-and-risk](https://github.com/stacknil/scientific-computing-toolkit/tree/main/tools/sbom-diff-and-risk) |