Skip to content

Commit 69c06d2

Browse files
committed
fix(ci): make the gates pipeline genuinely green
Root causes, all fixed: - check-code.py TypeScript checker used a malformed npx invocation (npm error: could not determine executable to run) and, once fixed, pulled in DOM lib types by default, colliding with sample classes named Notification. Now compiles against a shared scratch project (typescript + @types/node) with --lib es2022, no DOM. - Blocks in a file that reference a symbol defined in an earlier same-language block (a class, then a test double for it further down) are legitimate progressive documentation, not broken samples. The checker now retries a failing block against every same-language block seen so far in that file before failing it. - Added a markdown style gate (markdownlint-cli2 0.23.2), config tuned for a citation-heavy technical corpus: line length, bare URLs, and ordered-list-restart rules disabled where they conflict with continuous reference numbering across headed subsections; everything else enforced. Fixed the 4 genuine defects it found (missing blank lines around headings, a malformed C# heading). Also: the pipeline script (workflows/patterns-lean.js) no longer trusts an authoring agent's own completion claim. A real incident during this session: an agent returned "SKIP already complete" for a file that did not exist. Every chunk is now re-verified by a dedicated read-only agent re-running the structural gate, and a per-agent 30-minute timeout catches a stuck slot instead of hanging the batch forever. Both mechanisms proven against fixtures replaying the real failure before being trusted. 46/46 entries pass structure and prose. 197/197 code samples compile. 0 markdown issues.
1 parent 17aaf1a commit 69c06d2

14 files changed

Lines changed: 3670 additions & 931 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,3 +67,14 @@ jobs:
6767
python-version: "3.12"
6868
- name: Probe every cited URL
6969
run: python3 tools/validate-refs.py --strict --timeout 25
70+
71+
markdown:
72+
name: markdown style
73+
runs-on: ubuntu-latest
74+
steps:
75+
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
76+
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
77+
with:
78+
node-version: "22"
79+
- name: markdownlint-cli2
80+
run: npx --yes markdownlint-cli2@0.23.2

‎.markdownlint-cli2.jsonc‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"config": {
3+
"default": true,
4+
"MD010": { "code_blocks": false },
5+
"MD013": false,
6+
"MD024": { "siblings_only": true },
7+
"MD020": false,
8+
"MD025": false,
9+
"MD029": false,
10+
"MD040": false,
11+
"MD033": false,
12+
"MD034": false,
13+
"MD041": false,
14+
"MD060": false
15+
},
16+
"globs": ["patterns/**/*.md", "docs/**/*.md", "README.md"],
17+
"ignores": ["docs/council/**"]
18+
}

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -170,7 +170,7 @@ Content is licensed under
170170

171171
Use it, adapt it, sell work built on it. Give credit and link back.
172172

173-
```
173+
```text
174174
"Patterns" by Mirza Iqbal, CC BY 4.0
175175
https://github.com/mjmirza/patterns
176176
```

‎docs/ENTRY-TEMPLATE.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,80 +45,98 @@ is not yet settled.
4545
## The 18 dimensions, in order
4646

4747
### 1. Name, aliases, and lineage
48+
4849
Canonical name. Every alias in real use. Who first described it, in which
4950
publication, in which year, with the citation. If the name is contested or the
5051
pattern is known by a different name in another community, say so here.
5152

5253
### 2. Problem and context
54+
5355
The concrete situation that creates the need. Written so a reader who has never
5456
heard the pattern name can recognise the problem in their own codebase. State
5557
the context in which the problem arises, because a pattern outside its context
5658
is an anti-pattern.
5759

5860
### 3. Forces
61+
5962
The competing pressures the pattern balances. At minimum consider latency,
6063
coupling, consistency, operability, cost, team topology, and cognitive load.
6164
Say which forces the pattern favours and which it sacrifices. A pattern that
6265
sacrifices nothing is described wrongly.
6366

6467
### 4. Applicability and non-applicability
68+
6569
Two lists. When to reach for it. When NOT to, with the reason. The second list
6670
is the more valuable one and is the one most catalogs omit.
6771

6872
### 5. Structure
73+
6974
Participants with their responsibilities, and the relationships between them.
7075
Name each participant with the role it plays, not with a generic class name.
7176

7277
### 6. ASCII structure diagram
78+
7379
Inside a fenced code block. Boxes and arrows showing the participants and their
7480
relationships. Must be readable in a plain terminal at 80 columns.
7581

7682
### 7. Dynamics
83+
7784
How the participants interact at runtime. A sequence flow, a state transition,
7885
or an event flow, whichever fits. Also inside a fenced code block when drawn.
7986

8087
### 8. Implementation variants
88+
8189
The real ways this pattern is built in practice, with the trade-off of each.
8290
Include the language-idiomatic variants where a language changes the shape,
8391
for example a closure replacing a Strategy class.
8492

8593
### 9. Known production uses
94+
8695
Named systems, libraries, frameworks, or standards, each with a source. At least
8796
two. This is the dimension that proves the pattern is real and not academic.
8897

8998
### 10. Consequences
99+
90100
Positive and negative, as two explicit lists. Every pattern has a cost. Name it.
91101

92102
### 11. Failure modes and misuse
103+
93104
How this pattern breaks in production, and how people misuse it. Include the
94105
symptom a reader would actually observe, not the abstract mistake alone.
95106

96107
### 12. Trade-off matrix
108+
97109
A table comparing this pattern against its named alternatives across the forces
98110
from dimension 3. The alternatives must be named patterns, not strawmen.
99111

100112
### 13. Related and incompatible patterns
113+
101114
Which patterns compose with this one, which ones replace it, and which ones
102115
actively conflict with it. Explain the relationship, never a bare list of names.
103116

104117
### 14. Refactoring path in and out
118+
105119
How to introduce this pattern into code that does not have it, step by step.
106120
And how to remove it when it stops earning its place. Cross reference the
107121
refactoring family where a named refactoring applies.
108122

109123
### 15. Testing and verification
124+
110125
How to test code that uses this pattern. What is easy to test because of it,
111126
and what became harder. Name the test doubles or techniques that apply.
112127

113128
### 16. Observability signals
129+
114130
What to log, trace, or measure so this pattern is visible in production. What a
115131
healthy instance looks like on a dashboard, and what a failing one looks like.
116132

117133
### 17. Security and privacy implications
134+
118135
The attack surface the pattern opens or closes. Data handling implications.
119136
Where it is silent, say so plainly rather than inventing a concern.
120137

121138
### 18. References
139+
122140
Every source used, with author, title, edition or version, page or section, URL
123141
where one exists, and the date the URL was verified. Sources must be
124142
independently checkable by a reader.

‎docs/INVENTORY-v1.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,15 @@ Counts verified from the live sitemap (2026-08-02) where marked SITEMAP.
1010
SITEMAP: refactoring.guru covers 22. It omits **Interpreter**. We cover all 23.
1111

1212
### Creational (5)
13+
1314
abstract-factory, builder, factory-method, prototype, singleton
1415

1516
### Structural (7)
17+
1618
adapter, bridge, composite, decorator, facade, flyweight, proxy
1719

1820
### Behavioral (11)
21+
1922
chain-of-responsibility, command, interpreter, iterator, mediator, memento,
2023
observer, state, strategy, template-method, visitor
2124

‎docs/council/codex-gap-audit-2026-08-02.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
Yes: the checklist is strong, but not complete at master level.
22

33
**1. Missing Families**
4+
45
- **API and interface design patterns:** REST resource modeling, GraphQL resolver/data-loader patterns, gRPC streaming, webhook receiver, idempotent API, pagination patterns, versioning patterns.
56
- **Release/deployment patterns:** Blue-Green Deployment, Canary Release, Rolling Deployment, Shadow Traffic, Dark Launch, Feature Toggle, Branch by Abstraction, Expand-Contract Migration.
67
- **SRE/operations patterns:** SLO, Error Budget, Toil Automation, Runbook Automation, Game Day, Chaos Engineering, Graceful Degradation, Emergency Lever, Static Stability. Google SRE and AWS Well-Architected are authoritative here. ([sre.google](https://sre.google/books/?utm_source=openai)) ([docs.aws.amazon.com](https://docs.aws.amazon.com/wellarchitected/latest/reliability-pillar/welcome.html?utm_source=openai))
@@ -11,6 +12,7 @@ Yes: the checklist is strong, but not complete at master level.
1112
- **Interaction/HCI patterns:** Undo, Wizard, Breadcrumbs, Command Palette, Inline Validation, Empty State, Progressive Disclosure, Autosave, Bulk Action, Optimistic Undo.
1213

1314
**2. Missing Entries Inside Existing Families**
15+
1416
- **05 Architectural:** CQRS as architecture style, Event Sourcing, CQRS/Event Sourcing pair, Service Mesh, API Gateway, Backend-for-Frontend, Event-Carried State Transfer, Shared Kernel Architecture, Plugin Sandbox.
1517
- **08 Cloud/Distributed:** Blue-Green Deployment, Canary Release, Rolling Deployment, Disaster Recovery Pilot Light, Warm Standby, Multi-Site Active/Active, Cell-Based Architecture, Regional Evacuation, Static Stability, Emergency Lever, Graceful Degradation.
1618
- **09 Concurrency:** Read-Copy-Update, Compare-and-Swap Loop, Lock Striping, Semaphore, Countdown Latch, Phaser, Work Queue, Structured Concurrency, Async/Await, Backpressure, Rate Limiter, Scheduler.
@@ -47,6 +49,7 @@ Each entry needs these dimensions, otherwise it reads as a starter catalog:
4749
- **Citations with page/section/version/date**
4850

4951
**4. Padding To Cut**
52+
5053
- **Family 04 Design Principles** should not be a pattern family. SOLID, GRASP, CUPID, CAP, PACELC, ACID, BASE, Conway’s Law, and Postel’s Law are principles, laws, or distributed-systems constraints. Keep them as cross-reference pages, not peer entries beside GoF/EIP/PoEAA.
5154
- **Family 18 Anti-Patterns** is valid only if anchored in Brown et al. and production failure modes. Otherwise it becomes a grab bag overlapping Code Smells and Security. Do not cut it entirely; split into **Software Anti-Patterns**, **Architecture Anti-Patterns**, **Distributed Systems Failure Patterns**, and **AI Anti-Patterns**.
5255

‎patterns/08-cloud-distributed/README.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,15 @@
22

33
Origin. Azure Architecture Center, Nygard
44

5-
18 entries, 171,524 words. Every entry carries all 18
5+
18 entries, 172,251 words. Every entry carries all 18
66
dimensions from [the entry contract](../../docs/ENTRY-TEMPLATE.md).
77

88
## Cloud and Distributed
99

1010
| Pattern | Maturity | Words | Intent |
1111
|---|---|---|---|
12-
| [Cache-Aside](cache-aside.md) | canonical | 11,154 | A service reads the same records far more often than it writes them, and the read path is expensive. |
12+
| [Cache-Aside](cache-aside.md) | canonical | 11,151 | A service reads the same records far more often than it writes them, and the read path is expensive. |
1313
| [Gateway Aggregation](gateway-aggregation.md) | canonical | 7,007 | A client needs data or a decision that no single backend service owns end to end. |
14-
| [Health Endpoint Monitoring](health-endpoint-monitoring.md) | canonical | 7,690 | A service that has crashed is easy to notice. |
1514
| [Materialized View](materialized-view.md) | canonical | 8,521 | An application reads data far more often than it writes it, and the shape a write path needs is almost never the shape a read path wants. |
1615

1716
## Coordination
@@ -57,6 +56,12 @@ dimensions from [the entry contract](../../docs/ENTRY-TEMPLATE.md).
5756
|---|---|---|---|
5857
| [Strangler Fig](strangler-fig.md) | canonical | 10,348 | A system has been running in production for years. |
5958

59+
## Reliability
60+
61+
| Pattern | Maturity | Words | Intent |
62+
|---|---|---|---|
63+
| [Health Endpoint Monitoring](health-endpoint-monitoring.md) | canonical | 8,420 | A service running behind a load balancer, an orchestrator, or a service mesh can fail in ways that are invisible from outside the process. |
64+
6065
## Resilience
6166

6267
| Pattern | Maturity | Words | Intent |

‎patterns/08-cloud-distributed/cache-aside.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -408,8 +408,8 @@ mechanism, which no client-side approach does.
408408

409409
Each reader independently decides whether to rebuild before the entry expires,
410410
with a probability that rises as expiry approaches. The XFetch algorithm from
411-
Vattani, Chierichetti and Lowenstein evaluates `time() - delta * beta * ln(rand())
412-
>= expiry`, where `delta` is the measured recomputation cost and `beta` tunes how
411+
Vattani, Chierichetti and Lowenstein evaluates `time() - delta *beta* ln(rand())
412+
>= expiry`, where`delta` is the measured recomputation cost and `beta` tunes how
413413
early recomputation is favoured
414414
([Vattani, Chierichetti, Lowenstein, *Optimal Probabilistic Cache Stampede
415415
Prevention*, PVLDB volume 8, pages 886 to 897, 2015](https://dl.acm.org/doi/10.14778/2757807.2757813),

0 commit comments

Comments
 (0)