@grainulation/silo 1.0.0 → 1.0.1

package/lib/templates.js

@@ -5,9 +5,9 @@
  * A template contains: question, audience, constraints, and starter claims.
  */
 
-const fs = require('node:fs');
-const path = require('node:path');
-const { Store } = require('./store.js');
+const fs = require("node:fs");
+const path = require("node:path");
+const { Store } = require("./store.js");
 
 class Templates {
   constructor(store) {
@@ -35,14 +35,14 @@ class Templates {
       savedAt: new Date().toISOString(),
     };
     const filePath = path.join(this.store.templatesDir, `${id}.json`);
-    const tmp1 = filePath + '.tmp.' + process.pid;
-    fs.writeFileSync(tmp1, JSON.stringify(entry, null, 2) + '\n', 'utf-8');
+    const tmp1 = filePath + ".tmp." + process.pid;
+    fs.writeFileSync(tmp1, JSON.stringify(entry, null, 2) + "\n", "utf-8");
     fs.renameSync(tmp1, filePath);
 
     this.store._addToIndex({
       id,
       name,
-      type: 'template',
+      type: "template",
       claimCount: (template.seedClaims || []).length,
       storedAt: entry.savedAt,
     });
@@ -55,7 +55,7 @@ class Templates {
     const id = this._slugify(nameOrId);
     const filePath = path.join(this.store.templatesDir, `${id}.json`);
     if (!fs.existsSync(filePath)) return null;
-    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
   }
 
   /** List all saved templates. */
@@ -66,10 +66,10 @@ class Templates {
 
     return fs
       .readdirSync(dir)
-      .filter((f) => f.endsWith('.json'))
+      .filter((f) => f.endsWith(".json"))
       .map((f) => {
         try {
-          const data = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf-8'));
+          const data = JSON.parse(fs.readFileSync(path.join(dir, f), "utf-8"));
           return {
             id: data.id,
             name: data.name,
@@ -102,17 +102,21 @@ class Templates {
     }
 
     // Write seed claims
-    const claimsPath = path.join(targetDir, 'claims.json');
+    const claimsPath = path.join(targetDir, "claims.json");
     const claims = (template.seedClaims || []).map((c, i) => ({
       ...c,
-      id: c.id || `d${String(i + 1).padStart(3, '0')}`,
+      id: c.id || `d${String(i + 1).padStart(3, "0")}`,
     }));
-    const tmpClaims = claimsPath + '.tmp.' + process.pid;
-    fs.writeFileSync(tmpClaims, JSON.stringify(claims, null, 2) + '\n', 'utf-8');
+    const tmpClaims = claimsPath + ".tmp." + process.pid;
+    fs.writeFileSync(
+      tmpClaims,
+      JSON.stringify(claims, null, 2) + "\n",
+      "utf-8",
+    );
     fs.renameSync(tmpClaims, claimsPath);
 
     // Write sprint config stub
-    const configPath = path.join(targetDir, 'sprint.json');
+    const configPath = path.join(targetDir, "sprint.json");
     const config = {
       question: template.question,
       audience: template.audience,
@@ -120,8 +124,12 @@ class Templates {
       fromTemplate: template.id,
       createdAt: new Date().toISOString(),
     };
-    const tmpConfig = configPath + '.tmp.' + process.pid;
-    fs.writeFileSync(tmpConfig, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    const tmpConfig = configPath + ".tmp." + process.pid;
+    fs.writeFileSync(
+      tmpConfig,
+      JSON.stringify(config, null, 2) + "\n",
+      "utf-8",
+    );
     fs.renameSync(tmpConfig, configPath);
 
     return {
@@ -132,7 +140,10 @@ class Templates {
   }
 
   _slugify(str) {
-    return str.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+    return str
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-|-$/g, "");
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grainulation/silo",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Reusable knowledge for research sprints -- shared claim libraries, templates, and knowledge packs",
   "main": "lib/index.js",
   "exports": {
@@ -27,12 +27,13 @@
   ],
   "author": "grainulation contributors",
   "license": "MIT",
+  "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/grainulation/silo.git"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20"
   },
   "bugs": {
     "url": "https://github.com/grainulation/silo/issues"
@@ -43,6 +44,9 @@
     "lib/",
     "packs/",
     "public/",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "LICENSE",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md"
   ]
 }

package/packs/adr.json

@@ -0,0 +1,219 @@
+{
+  "name": "Architecture Decision Records",
+  "description": "Enterprise ADR framework with evidence tiers. Structured constraints and risk claims for common architecture decisions — use as seed claims when evaluating build-vs-buy, migration, scaling, or technology choices.",
+  "version": "1.0.0",
+  "claims": [
+    {
+      "id": "adr-001",
+      "type": "constraint",
+      "topic": "ADR decision structure",
+      "content": "Every ADR must state: (1) Decision context — what problem are we solving? (2) Decision drivers — what constraints and goals matter most? (3) Options considered — at least 2 alternatives with evidence. (4) Decision outcome — which option and why. (5) Consequences — accepted trade-offs.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": "https://adr.github.io",
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["adr", "structure", "decision-record", "enterprise"]
+    },
+    {
+      "id": "adr-002",
+      "type": "constraint",
+      "topic": "evidence-backed decisions",
+      "content": "Architecture decisions must be backed by evidence, not opinions. Each option should have claims at 'documented' tier or higher. 'We chose X because the team prefers it' is not an ADR — 'We chose X because benchmarks show 3x throughput under our load profile' is.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["adr", "evidence", "decision-quality", "enterprise"]
+    },
+    {
+      "id": "adr-003",
+      "type": "constraint",
+      "topic": "reversibility assessment",
+      "content": "Every architecture decision must classify its reversibility: Type 1 (irreversible — database engine, programming language, cloud provider) requires heavyweight evidence. Type 2 (reversible — framework, library, API design) can proceed with lighter evidence.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["adr", "reversibility", "type-1-type-2", "risk"]
+    },
+    {
+      "id": "adr-004",
+      "type": "risk",
+      "topic": "ADR decay",
+      "content": "ADRs that are not linked to code become stale and misleading. Risk: team makes decisions contradicting existing ADRs because they can't find them. Mitigation: store ADRs alongside code (docs/adr/), reference in relevant source files, review annually.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["adr", "decay", "maintenance", "risk"]
+    },
+    {
+      "id": "adr-005",
+      "type": "recommendation",
+      "topic": "wheat-powered ADR workflow",
+      "content": "Use wheat sprint as ADR research phase: (1) Define decision question as sprint question. (2) Add constraints from stakeholders. (3) Research options — each generates factual claims with evidence tiers. (4) Challenge phase creates conflict claims between options. (5) Compile — the brief IS the ADR.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "stated",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["adr", "wheat", "workflow", "recommendation"]
+    },
+    {
+      "id": "adr-006",
+      "type": "factual",
+      "topic": "build vs buy framework",
+      "content": "Build-vs-buy evaluation dimensions: (1) Total cost of ownership over 3 years (build: salaries + infra; buy: license + integration). (2) Time to value (build: months; buy: weeks). (3) Customization requirements. (4) Strategic differentiation — is this your core competency? (5) Maintenance burden.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["adr", "build-vs-buy", "framework", "tco"]
+    },
+    {
+      "id": "adr-007",
+      "type": "factual",
+      "topic": "migration decision framework",
+      "content": "Migration decision framework: (1) Is the current system at a hard limit (scale, compliance, EOL)? (2) What's the migration risk (data loss, downtime, rollback complexity)? (3) Can you migrate incrementally (strangler fig) or must it be big-bang? (4) What's the team's experience with the target?",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["adr", "migration", "framework", "risk-assessment"]
+    },
+    {
+      "id": "adr-008",
+      "type": "risk",
+      "topic": "consensus-driven decisions",
+      "content": "Risk: architecture by committee produces mediocre compromises. ADRs should identify a single decision owner (usually the tech lead or architect) who makes the call after reviewing evidence. The ADR documents the rationale for future teams.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["adr", "decision-owner", "governance", "risk"]
+    },
+    {
+      "id": "adr-009",
+      "type": "constraint",
+      "topic": "ADR status lifecycle",
+      "content": "ADR statuses: Proposed (under research), Accepted (decision made), Deprecated (superseded by newer ADR), Superseded (link to replacement). Never delete ADRs — they document why past decisions were made, even if reversed.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": "https://adr.github.io",
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["adr", "lifecycle", "status", "governance"]
+    },
+    {
+      "id": "adr-010",
+      "type": "recommendation",
+      "topic": "ADR audit trail",
+      "content": "For enterprise compliance: ADRs created via wheat produce an immutable audit trail. The claims.json is version-controlled, the compilation certificate references a content hash, and git log shows who contributed what. This satisfies SOC 2 change management evidence requirements.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "stated",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["adr", "audit-trail", "compliance", "soc2", "enterprise"]
+    },
+    {
+      "id": "adr-011",
+      "type": "estimate",
+      "topic": "ADR time savings",
+      "content": "Traditional ADR process: 1-2 weeks of stakeholder meetings, document drafting, and review cycles. Wheat-powered ADR: 10-15 minute research sprint produces a compiled brief with evidence tiers, conflict resolution, and structured recommendations — then a 30-minute review meeting to accept.",
+      "source": { "origin": "research", "artifact": null, "connector": null },
+      "evidence": "stated",
+      "status": "active",
+      "phase_added": "research",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["adr", "time-savings", "roi", "enterprise"]
+    },
+    {
+      "id": "adr-012",
+      "type": "factual",
+      "topic": "scaling decision patterns",
+      "content": "Common scaling decision points: (1) Vertical before horizontal — scale up is simpler until hardware limits. (2) Read replicas before sharding — reduces complexity for read-heavy workloads. (3) Caching before rewriting — often 10x improvement for fraction of effort. (4) CDN before app optimization for static assets.",
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
+      "evidence": "documented",
+      "status": "active",
+      "phase_added": "define",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "conflicts_with": [],
+      "resolved_by": null,
+      "tags": ["adr", "scaling", "patterns", "architecture"]
+    }
+  ]
+}

package/packs/api-design.json

@@ -8,7 +8,11 @@
       "type": "constraint",
       "topic": "HTTP method semantics",
       "content": "GET must be safe and idempotent (no side effects). PUT must be idempotent (same result on repeat). POST is neither safe nor idempotent. DELETE should be idempotent (deleting an already-deleted resource returns 204 or 404, not an error). Violating these semantics breaks caches, retries, and client expectations.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -22,7 +26,11 @@
       "type": "recommendation",
       "topic": "error response format",
       "content": "Use RFC 7807 (Problem Details) for error responses: {type, title, status, detail, instance}. Include a machine-readable error code field for client-side branching. Never expose stack traces, internal paths, or database errors in production responses.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -36,7 +44,11 @@
       "type": "recommendation",
       "topic": "cursor-based pagination",
       "content": "Prefer cursor-based pagination over offset-based for datasets that change frequently. Offset pagination becomes inconsistent when rows are inserted or deleted between pages. Cursor pagination uses an opaque token (base64-encoded last-seen ID) and supports consistent forward iteration. Return {data, next_cursor, has_more} in responses.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "production",
       "status": "active",
       "phase_added": "define",
@@ -50,7 +62,11 @@
       "type": "risk",
       "topic": "URL path versioning lock-in",
       "content": "URL path versioning (/v1/users, /v2/users) is simple but creates permanent routing complexity. Every version doubles the endpoint surface. Prefer header-based versioning (Accept: application/vnd.api+json;version=2) or additive-only changes (no versioning needed if you never remove or rename fields).",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "web",
       "status": "active",
       "phase_added": "define",
@@ -64,21 +80,34 @@
       "type": "constraint",
       "topic": "backwards compatibility rules",
       "content": "Breaking changes for public APIs: removing a field, renaming a field, changing a field type, changing a required/optional status, removing an endpoint, changing authentication. Non-breaking: adding optional fields, adding new endpoints, adding new enum values (if clients handle unknown values). Never make breaking changes without a version bump and deprecation period of at least 6 months.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
       "timestamp": "2025-01-01T00:00:00.000Z",
       "conflicts_with": [],
       "resolved_by": null,
-      "tags": ["api", "backwards-compatibility", "deprecation", "breaking-changes"]
+      "tags": [
+        "api",
+        "backwards-compatibility",
+        "deprecation",
+        "breaking-changes"
+      ]
     },
     {
       "id": "api-006",
       "type": "factual",
       "topic": "GraphQL vs REST tradeoffs",
       "content": "GraphQL eliminates over-fetching and under-fetching but introduces: query complexity analysis (must limit depth to 7-10 and breadth), N+1 data loader patterns, cache invalidation complexity (no HTTP caching by default), and a steeper client learning curve. REST is simpler for CRUD-heavy APIs with predictable access patterns.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -92,7 +121,11 @@
       "type": "recommendation",
       "topic": "rate limit headers",
       "content": "Include rate limit headers in every response: X-RateLimit-Limit (max requests per window), X-RateLimit-Remaining (remaining in current window), X-RateLimit-Reset (Unix timestamp when window resets). Return 429 Too Many Requests with a Retry-After header when limit is exceeded. This lets well-behaved clients self-throttle.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -106,7 +139,11 @@
       "type": "constraint",
       "topic": "request payload size limits",
       "content": "Set explicit request body size limits: 1 MB for standard JSON APIs, 10 MB for file uploads via multipart, and configurable limits for specific endpoints. Unbounded request bodies enable denial-of-service attacks. Return 413 Payload Too Large with a clear message stating the limit.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -120,7 +157,11 @@
       "type": "recommendation",
       "topic": "idempotency keys for mutations",
       "content": "POST endpoints that create resources should accept an Idempotency-Key header. Store the key with the response for 24 hours. If a duplicate key arrives, return the stored response without re-executing. This prevents duplicate charges, orders, or records from network retries. Stripe, PayPal, and AWS all use this pattern.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "production",
       "status": "active",
       "phase_added": "define",
@@ -134,7 +175,11 @@
       "type": "risk",
       "topic": "nested resource depth",
       "content": "Deeply nested REST routes (/orgs/:id/teams/:id/members/:id/roles) become rigid and hard to evolve. Limit nesting to 2 levels maximum. Use flat routes with query filters for deeper relationships (/roles?member_id=X&team_id=Y). Deep nesting also makes URL construction fragile for API consumers.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "web",
       "status": "active",
       "phase_added": "define",
@@ -148,7 +193,11 @@
       "type": "factual",
       "topic": "HTTP status code semantics",
       "content": "Use status codes precisely: 200 (success with body), 201 (created, include Location header), 204 (success, no body), 400 (malformed request), 401 (unauthenticated), 403 (authenticated but unauthorized), 404 (not found or hidden), 409 (conflict/duplicate), 422 (valid syntax but semantic error), 429 (rate limited), 500 (server error). Avoid 200-wrapping errors.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "documented",
       "status": "active",
       "phase_added": "define",
@@ -162,7 +211,11 @@
       "type": "recommendation",
       "topic": "API documentation contract testing",
       "content": "Generate API documentation from code (OpenAPI/Swagger) rather than maintaining it manually. Use contract testing (Pact, Dredd, or OpenAPI-diff in CI) to verify that the implementation matches the spec. Manual docs drift within weeks; contract tests catch drift on every PR.",
-      "source": { "origin": "best-practice", "artifact": null, "connector": null },
+      "source": {
+        "origin": "best-practice",
+        "artifact": null,
+        "connector": null
+      },
       "evidence": "tested",
       "status": "active",
       "phase_added": "define",
@@ -186,4 +239,4 @@
       "tags": ["api", "performance", "latency", "sla"]
     }
   ]
-}
+}