@grainulation/silo 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -8,7 +8,11 @@
8
8
  "type": "constraint",
9
9
  "topic": "migration rollback safety",
10
10
  "content": "Production migrations must be reversible. Every schema change, data transform, or infrastructure swap needs a tested rollback procedure with a maximum rollback time SLA.",
11
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
11
+ "source": {
12
+ "origin": "best-practice",
13
+ "artifact": null,
14
+ "connector": null
15
+ },
12
16
  "evidence": "documented",
13
17
  "status": "active",
14
18
  "phase_added": "define",
@@ -22,7 +26,11 @@
22
26
  "type": "risk",
23
27
  "topic": "dual-write consistency risk",
24
28
  "content": "Dual-write periods introduce data consistency risks. During cutover, writes must go to both old and new systems, and a reconciliation process must detect drift.",
25
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
29
+ "source": {
30
+ "origin": "best-practice",
31
+ "artifact": null,
32
+ "connector": null
33
+ },
26
34
  "evidence": "documented",
27
35
  "status": "active",
28
36
  "phase_added": "define",
@@ -36,7 +44,11 @@
36
44
  "type": "risk",
37
45
  "topic": "migration window overrun",
38
46
  "content": "Data migrations that run longer than the maintenance window force a choice between extended downtime and incremental migration. Estimate data volume transfer rates early.",
39
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
47
+ "source": {
48
+ "origin": "best-practice",
49
+ "artifact": null,
50
+ "connector": null
51
+ },
40
52
  "evidence": "documented",
41
53
  "status": "active",
42
54
  "phase_added": "define",
@@ -50,7 +62,11 @@
50
62
  "type": "constraint",
51
63
  "topic": "minimum viable migration scope",
52
64
  "content": "Feature parity with the legacy system is rarely achievable on day one. Define a 'minimum viable migration' scope that covers the critical path and defer edge cases.",
53
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
65
+ "source": {
66
+ "origin": "best-practice",
67
+ "artifact": null,
68
+ "connector": null
69
+ },
54
70
  "evidence": "stated",
55
71
  "status": "active",
56
72
  "phase_added": "define",
@@ -64,7 +80,11 @@
64
80
  "type": "recommendation",
65
81
  "topic": "strangler fig migration pattern",
66
82
  "content": "Use the strangler fig pattern for large migrations: route traffic incrementally to the new system while the old system continues to serve unmodified paths.",
67
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
83
+ "source": {
84
+ "origin": "best-practice",
85
+ "artifact": null,
86
+ "connector": null
87
+ },
68
88
  "evidence": "documented",
69
89
  "status": "active",
70
90
  "phase_added": "define",
@@ -78,7 +98,11 @@
78
98
  "type": "risk",
79
99
  "topic": "character encoding corruption",
80
100
  "content": "Character encoding mismatches (UTF-8 vs Latin-1, collation differences) are the most common silent data corruption source in database migrations. Test with production-representative data.",
81
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
101
+ "source": {
102
+ "origin": "best-practice",
103
+ "artifact": null,
104
+ "connector": null
105
+ },
82
106
  "evidence": "documented",
83
107
  "status": "active",
84
108
  "phase_added": "define",
@@ -106,7 +130,11 @@
106
130
  "type": "constraint",
107
131
  "topic": "API versioning during migration",
108
132
  "content": "API contract changes during migration require versioned endpoints. Clients must be able to continue using the old API for a deprecation period (minimum 3 months is standard).",
109
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
133
+ "source": {
134
+ "origin": "best-practice",
135
+ "artifact": null,
136
+ "connector": null
137
+ },
110
138
  "evidence": "documented",
111
139
  "status": "active",
112
140
  "phase_added": "define",
@@ -120,7 +148,11 @@
120
148
  "type": "recommendation",
121
149
  "topic": "shadow traffic validation",
122
150
  "content": "Run shadow traffic (replay production reads against the new system without serving responses) for at least 2 weeks before cutover. Compare results for correctness and latency.",
123
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
151
+ "source": {
152
+ "origin": "best-practice",
153
+ "artifact": null,
154
+ "connector": null
155
+ },
124
156
  "evidence": "documented",
125
157
  "status": "active",
126
158
  "phase_added": "define",
@@ -134,7 +166,11 @@
134
166
  "type": "risk",
135
167
  "topic": "legacy knowledge decay",
136
168
  "content": "Team knowledge of the legacy system degrades over time. If migration stalls, institutional knowledge may be lost before it completes. Document as you migrate, not after.",
137
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
169
+ "source": {
170
+ "origin": "best-practice",
171
+ "artifact": null,
172
+ "connector": null
173
+ },
138
174
  "evidence": "stated",
139
175
  "status": "active",
140
176
  "phase_added": "define",
@@ -8,7 +8,11 @@
8
8
  "type": "constraint",
9
9
  "topic": "structured logging format",
10
10
  "content": "All application logs must be structured JSON with mandatory fields: timestamp (ISO 8601), level (debug/info/warn/error/fatal), message, service, and trace_id. Unstructured string logs break log aggregation queries and make correlation impossible at scale.",
11
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
11
+ "source": {
12
+ "origin": "best-practice",
13
+ "artifact": null,
14
+ "connector": null
15
+ },
12
16
  "evidence": "production",
13
17
  "status": "active",
14
18
  "phase_added": "define",
@@ -22,7 +26,11 @@
22
26
  "type": "recommendation",
23
27
  "topic": "RED method for services",
24
28
  "content": "Every service should expose the RED metrics: Rate (requests per second), Errors (failed requests per second), and Duration (latency histogram). These three metrics cover 80% of service-level debugging. Use histograms with buckets at 5ms, 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 2.5s, 5s, 10s.",
25
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
29
+ "source": {
30
+ "origin": "best-practice",
31
+ "artifact": null,
32
+ "connector": null
33
+ },
26
34
  "evidence": "documented",
27
35
  "status": "active",
28
36
  "phase_added": "define",
@@ -36,7 +44,11 @@
36
44
  "type": "factual",
37
45
  "topic": "SLO error budget calculation",
38
46
  "content": "An SLO of 99.9% availability allows 43.2 minutes of downtime per 30-day window (0.1% error budget). An SLO of 99.95% allows 21.6 minutes. Error budget = total time * (1 - SLO target). When budget is exhausted, freeze feature work and focus on reliability.",
39
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
47
+ "source": {
48
+ "origin": "best-practice",
49
+ "artifact": null,
50
+ "connector": null
51
+ },
40
52
  "evidence": "documented",
41
53
  "status": "active",
42
54
  "phase_added": "define",
@@ -50,7 +62,11 @@
50
62
  "type": "risk",
51
63
  "topic": "alert fatigue",
52
64
  "content": "Alert fatigue occurs when on-call engineers receive more than 2-3 actionable alerts per shift. Non-actionable alerts must be demoted to dashboards or deleted. Every alert should have a runbook link, a clear threshold, and an expected action. Pages without runbooks erode trust in the alerting system.",
53
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
65
+ "source": {
66
+ "origin": "best-practice",
67
+ "artifact": null,
68
+ "connector": null
69
+ },
54
70
  "evidence": "production",
55
71
  "status": "active",
56
72
  "phase_added": "define",
@@ -64,21 +80,34 @@
64
80
  "type": "recommendation",
65
81
  "topic": "distributed trace propagation",
66
82
  "content": "Propagate W3C Trace Context headers (traceparent, tracestate) across all service boundaries including HTTP, gRPC, and message queues. Without trace propagation, latency debugging in distributed systems requires manual log correlation which takes 10-50x longer.",
67
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
83
+ "source": {
84
+ "origin": "best-practice",
85
+ "artifact": null,
86
+ "connector": null
87
+ },
68
88
  "evidence": "documented",
69
89
  "status": "active",
70
90
  "phase_added": "define",
71
91
  "timestamp": "2025-01-01T00:00:00.000Z",
72
92
  "conflicts_with": [],
73
93
  "resolved_by": null,
74
- "tags": ["observability", "tracing", "distributed-systems", "opentelemetry"]
94
+ "tags": [
95
+ "observability",
96
+ "tracing",
97
+ "distributed-systems",
98
+ "opentelemetry"
99
+ ]
75
100
  },
76
101
  {
77
102
  "id": "obs-006",
78
103
  "type": "constraint",
79
104
  "topic": "no PII in logs",
80
105
  "content": "Logs must never contain PII (emails, names, IP addresses, session tokens, passwords). Use hashed or tokenized identifiers for correlation. Accidental PII in logs creates GDPR/CCPA compliance risk and makes log retention policies complex. Enforce with automated log scrubbing or allowlist-based field serialization.",
81
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
106
+ "source": {
107
+ "origin": "best-practice",
108
+ "artifact": null,
109
+ "connector": null
110
+ },
82
111
  "evidence": "documented",
83
112
  "status": "active",
84
113
  "phase_added": "define",
@@ -92,7 +121,11 @@
92
121
  "type": "recommendation",
93
122
  "topic": "USE method for infrastructure",
94
123
  "content": "For infrastructure resources (CPU, memory, disk, network), track the USE metrics: Utilization (% of capacity used), Saturation (queue depth or wait time), and Errors (error count). Alert when utilization exceeds 80% sustained over 5 minutes or saturation is non-zero.",
95
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
124
+ "source": {
125
+ "origin": "best-practice",
126
+ "artifact": null,
127
+ "connector": null
128
+ },
96
129
  "evidence": "documented",
97
130
  "status": "active",
98
131
  "phase_added": "define",
@@ -120,7 +153,11 @@
120
153
  "type": "recommendation",
121
154
  "topic": "incident severity definitions",
122
155
  "content": "Define incident severity levels with quantitative criteria: SEV1 (total service outage or data loss, all hands, 15-min response), SEV2 (degraded for >50% of users, team response, 30-min), SEV3 (degraded for <50% or non-critical feature down, next business day), SEV4 (cosmetic or minor, backlog). Ambiguous severity wastes escalation time.",
123
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
156
+ "source": {
157
+ "origin": "best-practice",
158
+ "artifact": null,
159
+ "connector": null
160
+ },
124
161
  "evidence": "documented",
125
162
  "status": "active",
126
163
  "phase_added": "define",
@@ -134,7 +171,11 @@
134
171
  "type": "risk",
135
172
  "topic": "cardinality explosion in metrics",
136
173
  "content": "High-cardinality labels (user IDs, request IDs, full URLs) on metrics cause cardinality explosion, which degrades query performance and inflates storage costs exponentially. Prometheus recommends keeping total time series under 10 million. Use logs or traces for high-cardinality data, not metrics.",
137
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
174
+ "source": {
175
+ "origin": "best-practice",
176
+ "artifact": null,
177
+ "connector": null
178
+ },
138
179
  "evidence": "production",
139
180
  "status": "active",
140
181
  "phase_added": "define",
@@ -148,7 +189,11 @@
148
189
  "type": "recommendation",
149
190
  "topic": "postmortem blamelessness",
150
191
  "content": "Postmortems must be blameless and focus on systemic causes, not individual actions. Required sections: timeline, impact (users affected, duration, revenue impact), root cause, contributing factors, action items with owners and due dates. Publish postmortems within 48 hours of incident resolution.",
151
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
192
+ "source": {
193
+ "origin": "best-practice",
194
+ "artifact": null,
195
+ "connector": null
196
+ },
152
197
  "evidence": "documented",
153
198
  "status": "active",
154
199
  "phase_added": "define",
@@ -172,4 +217,4 @@
172
217
  "tags": ["observability", "opentelemetry", "migration", "cost"]
173
218
  }
174
219
  ]
175
- }
220
+ }
@@ -8,7 +8,11 @@
8
8
  "type": "constraint",
9
9
  "topic": "SQL injection prevention",
10
10
  "content": "All database queries must use parameterized statements or prepared queries. String concatenation for SQL is never acceptable, even for internal tools. ORMs provide this by default but raw queries must be audited. OWASP ranks injection as A03:2021.",
11
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
11
+ "source": {
12
+ "origin": "best-practice",
13
+ "artifact": null,
14
+ "connector": null
15
+ },
12
16
  "evidence": "documented",
13
17
  "status": "active",
14
18
  "phase_added": "define",
@@ -22,7 +26,11 @@
22
26
  "type": "constraint",
23
27
  "topic": "secrets never in source control",
24
28
  "content": "Secrets (API keys, database credentials, signing keys) must never appear in source control, including in commit history. Use environment variables, secret managers (Vault, AWS Secrets Manager, 1Password CLI), or encrypted .env files with .gitignore. Rotate any secret that has ever been committed.",
25
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
29
+ "source": {
30
+ "origin": "best-practice",
31
+ "artifact": null,
32
+ "connector": null
33
+ },
26
34
  "evidence": "documented",
27
35
  "status": "active",
28
36
  "phase_added": "define",
@@ -36,7 +44,11 @@
36
44
  "type": "recommendation",
37
45
  "topic": "JWT access token lifetime",
38
46
  "content": "JWT access tokens should have a lifetime of 5-15 minutes. Refresh tokens should be opaque (not JWT), stored server-side, rotated on each use, and have a maximum lifetime of 7-30 days. Never store JWTs in localStorage; use httpOnly secure cookies or in-memory storage.",
39
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
47
+ "source": {
48
+ "origin": "best-practice",
49
+ "artifact": null,
50
+ "connector": null
51
+ },
40
52
  "evidence": "documented",
41
53
  "status": "active",
42
54
  "phase_added": "define",
@@ -50,7 +62,11 @@
50
62
  "type": "risk",
51
63
  "topic": "dependency supply chain attacks",
52
64
  "content": "npm, PyPI, and other registries are vectors for supply chain attacks (typosquatting, maintainer account takeover, malicious postinstall scripts). Pin exact dependency versions, use lockfiles, audit with npm audit / pip-audit, and consider running install with --ignore-scripts in CI.",
53
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
65
+ "source": {
66
+ "origin": "best-practice",
67
+ "artifact": null,
68
+ "connector": null
69
+ },
54
70
  "evidence": "production",
55
71
  "status": "active",
56
72
  "phase_added": "define",
@@ -64,7 +80,11 @@
64
80
  "type": "factual",
65
81
  "topic": "bcrypt cost factor",
66
82
  "content": "bcrypt with a cost factor of 10 takes approximately 100ms to hash on modern hardware. Increase to 12 (roughly 400ms) for high-security contexts. Argon2id is the current OWASP recommendation for new projects, with minimum parameters: 19 MiB memory, 2 iterations, 1 parallelism.",
67
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
83
+ "source": {
84
+ "origin": "best-practice",
85
+ "artifact": null,
86
+ "connector": null
87
+ },
68
88
  "evidence": "documented",
69
89
  "status": "active",
70
90
  "phase_added": "define",
@@ -78,7 +98,11 @@
78
98
  "type": "constraint",
79
99
  "topic": "CORS allowlist",
80
100
  "content": "CORS Access-Control-Allow-Origin must never be set to * for authenticated endpoints. Maintain an explicit allowlist of permitted origins. Reflect the Origin header only if it matches the allowlist. Misconfigured CORS is OWASP A01:2021 (Broken Access Control).",
81
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
101
+ "source": {
102
+ "origin": "best-practice",
103
+ "artifact": null,
104
+ "connector": null
105
+ },
82
106
  "evidence": "documented",
83
107
  "status": "active",
84
108
  "phase_added": "define",
@@ -92,7 +116,11 @@
92
116
  "type": "recommendation",
93
117
  "topic": "CSP header configuration",
94
118
  "content": "Content-Security-Policy should start strict and loosen as needed: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'. Avoid 'unsafe-inline' and 'unsafe-eval'. Use nonces for inline scripts if unavoidable. Report violations with report-uri or report-to.",
95
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
119
+ "source": {
120
+ "origin": "best-practice",
121
+ "artifact": null,
122
+ "connector": null
123
+ },
96
124
  "evidence": "documented",
97
125
  "status": "active",
98
126
  "phase_added": "define",
@@ -106,7 +134,11 @@
106
134
  "type": "risk",
107
135
  "topic": "SSRF in internal services",
108
136
  "content": "Server-Side Request Forgery (SSRF) allows attackers to make requests from your server to internal networks, cloud metadata endpoints (169.254.169.254), or localhost services. Validate and allowlist all URLs that originate from user input. Block requests to private IP ranges and link-local addresses.",
109
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
137
+ "source": {
138
+ "origin": "best-practice",
139
+ "artifact": null,
140
+ "connector": null
141
+ },
110
142
  "evidence": "production",
111
143
  "status": "active",
112
144
  "phase_added": "define",
@@ -120,7 +152,11 @@
120
152
  "type": "recommendation",
121
153
  "topic": "rate limiting auth endpoints",
122
154
  "content": "Login endpoints must be rate-limited to no more than 10 attempts per IP per minute and 5 attempts per account per minute. After 5 consecutive failures for an account, enforce exponential backoff or temporary lockout (15-30 minutes). Log all failed attempts with IP and timestamp for anomaly detection.",
123
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
155
+ "source": {
156
+ "origin": "best-practice",
157
+ "artifact": null,
158
+ "connector": null
159
+ },
124
160
  "evidence": "documented",
125
161
  "status": "active",
126
162
  "phase_added": "define",
@@ -134,7 +170,11 @@
134
170
  "type": "factual",
135
171
  "topic": "HTTPS and HSTS requirements",
136
172
  "content": "All production traffic must use TLS 1.2 or higher. TLS 1.0 and 1.1 are deprecated (RFC 8996). Set Strict-Transport-Security header with max-age of at least 31536000 (1 year) and includeSubDomains. Submit to the HSTS preload list for public-facing domains.",
137
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
173
+ "source": {
174
+ "origin": "best-practice",
175
+ "artifact": null,
176
+ "connector": null
177
+ },
138
178
  "evidence": "documented",
139
179
  "status": "active",
140
180
  "phase_added": "define",
@@ -148,7 +188,11 @@
148
188
  "type": "risk",
149
189
  "topic": "insecure deserialization",
150
190
  "content": "Never deserialize untrusted data with language-native serialization (Java ObjectInputStream, Python pickle, PHP unserialize). These allow arbitrary code execution. Use JSON or Protocol Buffers with schema validation instead. OWASP A08:2021 (Software and Data Integrity Failures).",
151
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
191
+ "source": {
192
+ "origin": "best-practice",
193
+ "artifact": null,
194
+ "connector": null
195
+ },
152
196
  "evidence": "documented",
153
197
  "status": "active",
154
198
  "phase_added": "define",
@@ -162,7 +206,11 @@
162
206
  "type": "recommendation",
163
207
  "topic": "least privilege for service accounts",
164
208
  "content": "Service accounts and IAM roles must follow least privilege: grant only the specific actions on the specific resources needed. Audit permissions quarterly. AWS policies should never use Resource: * with Action: *. Use IAM Access Analyzer to identify unused permissions.",
165
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
209
+ "source": {
210
+ "origin": "best-practice",
211
+ "artifact": null,
212
+ "connector": null
213
+ },
166
214
  "evidence": "documented",
167
215
  "status": "active",
168
216
  "phase_added": "define",
@@ -172,4 +220,4 @@
172
220
  "tags": ["security", "iam", "least-privilege", "cloud"]
173
221
  }
174
222
  ]
175
- }
223
+ }
@@ -8,14 +8,23 @@
8
8
  "type": "constraint",
9
9
  "topic": "code review turnaround time",
10
10
  "content": "Code reviews should receive first-pass feedback within 4 business hours. Reviews taking longer than 24 hours are the top-cited blocker for developer productivity (Google Developer Survey 2023). Set team norms: reviews under 400 lines get same-day response, larger PRs should be split or paired on.",
11
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
11
+ "source": {
12
+ "origin": "best-practice",
13
+ "artifact": null,
14
+ "connector": null
15
+ },
12
16
  "evidence": "documented",
13
17
  "status": "active",
14
18
  "phase_added": "define",
15
19
  "timestamp": "2025-01-01T00:00:00.000Z",
16
20
  "conflicts_with": [],
17
21
  "resolved_by": null,
18
- "tags": ["team-process", "code-review", "developer-experience", "productivity"]
22
+ "tags": [
23
+ "team-process",
24
+ "code-review",
25
+ "developer-experience",
26
+ "productivity"
27
+ ]
19
28
  },
20
29
  {
21
30
  "id": "team-002",
@@ -36,7 +45,11 @@
36
45
  "type": "recommendation",
37
46
  "topic": "on-call rotation design",
38
47
  "content": "On-call rotations should be 1 week per engineer, with a minimum of 6 people in the rotation (no more than 1 week in 6 on primary). Provide a secondary on-call who shadows. Compensate on-call with either extra pay (10-15% of base for the week) or time off (1 day per week on-call). On-call without compensation breeds resentment and attrition.",
39
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
48
+ "source": {
49
+ "origin": "best-practice",
50
+ "artifact": null,
51
+ "connector": null
52
+ },
40
53
  "evidence": "production",
41
54
  "status": "active",
42
55
  "phase_added": "define",
@@ -50,7 +63,11 @@
50
63
  "type": "recommendation",
51
64
  "topic": "RFC process for decisions",
52
65
  "content": "Use RFCs (Request for Comments) for decisions that are: cross-team, hard to reverse, or affect more than 3 people. RFC template: Context (why now), Proposal (what), Alternatives considered (at least 2), Tradeoffs, Migration plan. Set a review period of 5 business days. Silence is not consent; require explicit approvals from stakeholders. Archive accepted RFCs as ADRs.",
53
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
66
+ "source": {
67
+ "origin": "best-practice",
68
+ "artifact": null,
69
+ "connector": null
70
+ },
54
71
  "evidence": "documented",
55
72
  "status": "active",
56
73
  "phase_added": "define",
@@ -78,7 +95,11 @@
78
95
  "type": "factual",
79
96
  "topic": "estimation accuracy ranges",
80
97
  "content": "Software estimation accuracy follows the Cone of Uncertainty: at project inception, estimates are 0.25x-4x actual. After requirements, 0.5x-2x. After detailed design, 0.67x-1.5x. After code complete, 0.9x-1.1x. Communicate estimates as ranges, never single points. Use relative sizing (story points) for prioritization and historical velocity for date forecasting.",
81
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
98
+ "source": {
99
+ "origin": "best-practice",
100
+ "artifact": null,
101
+ "connector": null
102
+ },
82
103
  "evidence": "documented",
83
104
  "status": "active",
84
105
  "phase_added": "define",
@@ -92,21 +113,34 @@
92
113
  "type": "recommendation",
93
114
  "topic": "postmortem action item tracking",
94
115
  "content": "Postmortem action items must have: a single owner (not a team), a due date within 30 days, and a tracking ticket. Review incomplete action items at the start of every postmortem meeting. Teams that do not track action items to completion repeat the same incidents. 60% of incidents are caused by previously identified but unresolved issues.",
95
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
116
+ "source": {
117
+ "origin": "best-practice",
118
+ "artifact": null,
119
+ "connector": null
120
+ },
96
121
  "evidence": "production",
97
122
  "status": "active",
98
123
  "phase_added": "define",
99
124
  "timestamp": "2025-01-01T00:00:00.000Z",
100
125
  "conflicts_with": [],
101
126
  "resolved_by": null,
102
- "tags": ["team-process", "postmortem", "incident-response", "accountability"]
127
+ "tags": [
128
+ "team-process",
129
+ "postmortem",
130
+ "incident-response",
131
+ "accountability"
132
+ ]
103
133
  },
104
134
  {
105
135
  "id": "team-008",
106
136
  "type": "constraint",
107
137
  "topic": "meeting hygiene for engineers",
108
138
  "content": "Protect maker time: engineers need 4-hour uninterrupted blocks for complex work. Meeting-free mornings or meeting-free days (e.g., no meetings on Tuesday/Thursday) measurably increase output. Context-switching between meetings costs 15-25 minutes of recovery time per switch. Batch meetings into afternoon blocks.",
109
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
139
+ "source": {
140
+ "origin": "best-practice",
141
+ "artifact": null,
142
+ "connector": null
143
+ },
110
144
  "evidence": "web",
111
145
  "status": "active",
112
146
  "phase_added": "define",
@@ -120,7 +154,11 @@
120
154
  "type": "recommendation",
121
155
  "topic": "runbook-driven operations",
122
156
  "content": "Every alert and recurring operational task should have a runbook: what the alert means, how to diagnose, step-by-step remediation, escalation criteria, and who to contact. Runbooks reduce MTTR by 40-60% for on-call engineers encountering unfamiliar alerts. Store runbooks alongside alert definitions, linked by alert name. Review and update runbooks after every incident.",
123
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
157
+ "source": {
158
+ "origin": "best-practice",
159
+ "artifact": null,
160
+ "connector": null
161
+ },
124
162
  "evidence": "production",
125
163
  "status": "active",
126
164
  "phase_added": "define",
@@ -134,7 +172,11 @@
134
172
  "type": "risk",
135
173
  "topic": "bus factor for critical systems",
136
174
  "content": "Bus factor (number of people who could be hit by a bus before the project stalls) of 1 is a critical risk. Mitigate with: pair programming or rotation on critical systems, mandatory documentation for system architecture and runbooks, cross-training sessions quarterly, and code review requirements that expose at least 2 people to every area of the codebase.",
137
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
175
+ "source": {
176
+ "origin": "best-practice",
177
+ "artifact": null,
178
+ "connector": null
179
+ },
138
180
  "evidence": "documented",
139
181
  "status": "active",
140
182
  "phase_added": "define",
@@ -162,14 +204,23 @@
162
204
  "type": "recommendation",
163
205
  "topic": "retrospective action limits",
164
206
  "content": "Limit retrospective action items to 2-3 per sprint. Teams that generate 8-10 action items per retro complete fewer than 20% of them, creating learned helplessness. Pick the highest-impact items, assign owners, and carry forward only incomplete items from the previous retro. If the same item appears 3 retros in a row, escalate it.",
165
- "source": { "origin": "best-practice", "artifact": null, "connector": null },
207
+ "source": {
208
+ "origin": "best-practice",
209
+ "artifact": null,
210
+ "connector": null
211
+ },
166
212
  "evidence": "documented",
167
213
  "status": "active",
168
214
  "phase_added": "define",
169
215
  "timestamp": "2025-01-01T00:00:00.000Z",
170
216
  "conflicts_with": [],
171
217
  "resolved_by": null,
172
- "tags": ["team-process", "retrospective", "agile", "continuous-improvement"]
218
+ "tags": [
219
+ "team-process",
220
+ "retrospective",
221
+ "agile",
222
+ "continuous-improvement"
223
+ ]
173
224
  }
174
225
  ]
175
- }
226
+ }
@@ -8,7 +8,11 @@
8
8
  "type": "constraint",
9
9
  "topic": "test framework",
10
10
  "content": "All tests must use node:test and node:assert/strict with zero external dependencies. No Jest, Mocha, Vitest, or other frameworks.",
11
- "source": { "origin": "architecture", "artifact": null, "connector": null },
11
+ "source": {
12
+ "origin": "architecture",
13
+ "artifact": null,
14
+ "connector": null
15
+ },
12
16
  "evidence": "documented",
13
17
  "status": "active",
14
18
  "phase_added": "define",
@@ -22,7 +26,11 @@
22
26
  "type": "constraint",
23
27
  "topic": "test isolation",
24
28
  "content": "Tests must use real filesystem (mkdtempSync), real processes (child_process.spawn), and real HTTP. No mocks, no spies, no test doubles.",
25
- "source": { "origin": "architecture", "artifact": null, "connector": null },
29
+ "source": {
30
+ "origin": "architecture",
31
+ "artifact": null,
32
+ "connector": null
33
+ },
26
34
  "evidence": "documented",
27
35
  "status": "active",
28
36
  "phase_added": "define",
@@ -78,7 +86,11 @@
78
86
  "type": "constraint",
79
87
  "topic": "CI matrix",
80
88
  "content": "CI must test on Node 18, 20, and 22. Every CI run verifies zero runtime dependencies, runs all tests, checks CLI --help, and performs a dry-run npm publish.",
81
- "source": { "origin": "architecture", "artifact": ".github/workflows/ci.yml", "connector": null },
89
+ "source": {
90
+ "origin": "architecture",
91
+ "artifact": ".github/workflows/ci.yml",
92
+ "connector": null
93
+ },
82
94
  "evidence": "documented",
83
95
  "status": "active",
84
96
  "phase_added": "define",
@@ -92,7 +104,11 @@
92
104
  "type": "factual",
93
105
  "topic": "test coverage baseline",
94
106
  "content": "Baseline: 191 tests across 5 repos (wheat 25, barn 58, mill 30, silo 21, ranch 44). After adding server, UI smoke, and cross-tool tests: ~260 tests total.",
95
- "source": { "origin": "measurement", "artifact": null, "connector": null },
107
+ "source": {
108
+ "origin": "measurement",
109
+ "artifact": null,
110
+ "connector": null
111
+ },
96
112
  "evidence": "tested",
97
113
  "status": "active",
98
114
  "phase_added": "research",