sinapse-ai 1.12.1 → 1.13.0

package/.sinapse-ai/core/grounding/README.md

@@ -1,83 +0,0 @@
-# Grounding Hooks (Story 10.47 + GA-1.6)
-
-Hooks shipped by SINAPSE-AI that read user-supplied grounding sources and
-inject relevant context into agent prompts. Each hook is **opt-in**:
-absence of `~/.claude/sinapse-ai-config.yaml` or `enabled: false` in the
-matching section means the hook is a complete no-op (no I/O, no warnings,
-no errors).
-
-## Architecture: Two layers
-
-### Layer 1 — Executable hooks (`.sinapse-ai/hooks/`, story GA-1.6) ✅ ACTIVE
-
-These are the hooks Claude Code actually runs via `UserPromptSubmit`. They
-read real files and inject context into prompts. Registered automatically
-during `npx sinapse-ai install` into `~/.claude/settings.json`.
-
-| Executable hook | Reads | Injects |
-|-----------------|-------|---------|
-| `sinapse-vault-grounding.cjs` | `grounding.vault.path` → top-5 `.md` notes | `<vault-grounding>` |
-| `sinapse-ds-grounding.cjs` | `grounding.designSystem.rootPath` → DS law file | `<ds-grounding>` |
-| `sinapse-brand-grounding.cjs` | `grounding.brand.brandbookPath` → brandbook | `<brand-grounding>` |
-
-**Caller:** `bin/lib/register-grounding-hooks.js` (invoked by `bin/commands/install.js`
-phase 6b). Hook registration is idempotent and non-destructive.
-
-### Layer 2 — Library resolvers (`core/grounding/`, story 10.47) — DEFER
-
-These library stubs (`vault.cjs`, `design-system.cjs`, `brand.cjs`) are
-shallow wrappers around `config-loader.cjs`. They return a structured envelope
-describing what is configured, but do **not** inject context into prompts.
-
-**Why defer:** The executable hooks in Layer 1 (GA-1.6) already implement
-the concrete content injection logic directly. The library resolvers were
-designed as the "integration point" for future use cases where something
-other than the Claude Code hook chain needs to consume grounding data
-(e.g., a CLI command, a report generator, or a programmatic API). No such
-consumer exists today.
-
-**Trigger to activate library resolvers:** a concrete caller (e.g., a new
-CLI sub-command `sinapse grounding status`, or a report generator) that
-needs to query grounding config programmatically. At that point, extend
-`vault.cjs` / `design-system.cjs` / `brand.cjs` to read actual files and
-return rich structured data. Do **not** create a caller just to justify
-activating these resolvers (Article XI — no orphans).
-
-**Current callers of library resolvers:** `bin/lib/prompts.js` and
-`bin/commands/update.js` import `grounding-config` (the wizard package, not
-these library hooks). The library hooks themselves have no production caller
-beyond their own test suite.
-
-| Library resolver | Status | Defer trigger |
-|-----------------|--------|---------------|
-| `vault.cjs` | stub — returns config envelope | new CLI/API consumer |
-| `design-system.cjs` | stub — returns config envelope | new CLI/API consumer |
-| `brand.cjs` | stub — returns config envelope | new CLI/API consumer |
-| `config-loader.cjs` | functional — reads YAML | used by all three stubs |
-
----
-
-## Configuration
-
-Configure interactively via `npx sinapse-ai install` (Story 10.46+10.47
-wizard) or by editing the YAML file directly. See
-`docs/guides/grounding-setup.md` for the full guide.
-
-`~/.claude/sinapse-ai-config.yaml` schema:
-
-```yaml
-version: '1'
-grounding:
-  vault:
-    enabled: true
-    path: /abs/path/to/vault
-    domains: [sinapse, personal]
-  designSystem:
-    enabled: true
-    profileName: SINAPSE
-    rootPath: /abs/path/to/brandbook
-  brand:
-    enabled: true
-    profileName: SINAPSE
-    brandbookPath: /abs/path/to/brandbook/0.0-guidelines.md
-```

package/.sinapse-ai/core/grounding/brand.cjs

@@ -1,29 +0,0 @@
-/**
- * Brand grounding hook — opt-in BYO.
- *
- * @story 10.47
- *
- * Reads the user's brandbook path from `~/.claude/sinapse-ai-config.yaml`
- * (`grounding.brand`). Returns a stub envelope when configured, `null`
- * otherwise. Concrete brandbook parser (positioning, MVV, tone-of-voice
- * extraction) lands in a follow-up.
- */
-
-'use strict';
-
-const configLoader = require('./config-loader.cjs');
-
-function brandGroundingHook(_context = {}) {
-  const section = configLoader.getSection('brand');
-  if (!section || !section.enabled || !section.brandbookPath) return null;
-
-  return {
-    source: 'brand',
-    profileName: section.profileName || '',
-    brandbookPath: section.brandbookPath,
-    note: 'Brand grounding configured. Concrete brandbook parser ships in a follow-up story.',
-  };
-}
-
-module.exports = brandGroundingHook;
-module.exports.brandGroundingHook = brandGroundingHook;

package/.sinapse-ai/core/grounding/config-loader.cjs

@@ -1,52 +0,0 @@
-/**
- * Shared config loader for grounding hooks.
- *
- * @story 10.47
- *
- * Reads `~/.claude/sinapse-ai-config.yaml` once per call. Pure function: no
- * caching, no side effects, never throws — returns `null` on any error so
- * each hook can short-circuit cleanly.
- */
-
-'use strict';
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-const CONFIG_PATH = path.join(os.homedir(), '.claude', 'sinapse-ai-config.yaml');
-
-function loadGroundingConfig(configPath = CONFIG_PATH) {
-  try {
-    if (!fs.existsSync(configPath)) return null;
-    const raw = fs.readFileSync(configPath, 'utf8');
-    // Lazy-require so absence of js-yaml in a downstream consumer never
-    // crashes the hook chain — yaml is shipped via packages/installer
-    // dependency tree but downstream installs may strip dev deps.
-    let yaml;
-    try { yaml = require('js-yaml'); } catch { return null; }
-    const parsed = yaml.load(raw);
-    if (!parsed || typeof parsed !== 'object') return null;
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-function isSectionEnabled(section, configPath = CONFIG_PATH) {
-  const cfg = loadGroundingConfig(configPath);
-  return Boolean(cfg && cfg.grounding && cfg.grounding[section] && cfg.grounding[section].enabled);
-}
-
-function getSection(section, configPath = CONFIG_PATH) {
-  const cfg = loadGroundingConfig(configPath);
-  if (!cfg || !cfg.grounding) return null;
-  return cfg.grounding[section] || null;
-}
-
-module.exports = {
-  CONFIG_PATH,
-  loadGroundingConfig,
-  isSectionEnabled,
-  getSection,
-};

package/.sinapse-ai/core/grounding/design-system.cjs

@@ -1,29 +0,0 @@
-/**
- * Design system grounding hook — opt-in BYO.
- *
- * @story 10.47
- *
- * Reads the user's design-system root from
- * `~/.claude/sinapse-ai-config.yaml` (`grounding.designSystem`). Returns a
- * stub envelope when configured, `null` otherwise. The concrete DS resolver
- * (token lookup, component registry, brandbook diff) lands in a follow-up.
- */
-
-'use strict';
-
-const configLoader = require('./config-loader.cjs');
-
-function designSystemGroundingHook(_context = {}) {
-  const section = configLoader.getSection('designSystem');
-  if (!section || !section.enabled || !section.rootPath) return null;
-
-  return {
-    source: 'designSystem',
-    profileName: section.profileName || '',
-    rootPath: section.rootPath,
-    note: 'Design system grounding configured. Concrete DS resolver ships in a follow-up story.',
-  };
-}
-
-module.exports = designSystemGroundingHook;
-module.exports.designSystemGroundingHook = designSystemGroundingHook;

package/.sinapse-ai/core/grounding/vault.cjs

@@ -1,36 +0,0 @@
-/**
- * Vault grounding hook — opt-in BYO.
- *
- * @story 10.47
- *
- * Reads the user's vault path from `~/.claude/sinapse-ai-config.yaml`
- * (`grounding.vault`) and is the entry point for future context injection
- * from a markdown notes vault.
- *
- * Today this hook is a **structural no-op**: when the section is enabled
- * it returns a stub envelope describing the available vault path so
- * downstream tooling can detect the integration point. When disabled or
- * missing config, returns `null` silently. The concrete vault parser and
- * relevance scorer land in a follow-up story.
- */
-
-'use strict';
-
-// Use module reference (not destructuring) so tests can stub
-// configLoader.getSection at runtime via jest mocks.
-const configLoader = require('./config-loader.cjs');
-
-function vaultGroundingHook(_context = {}) {
-  const section = configLoader.getSection('vault');
-  if (!section || !section.enabled || !section.path) return null;
-
-  return {
-    source: 'vault',
-    path: section.path,
-    domains: Array.isArray(section.domains) ? section.domains : [],
-    note: 'Vault grounding configured. Concrete content injection ships in a follow-up story.',
-  };
-}
-
-module.exports = vaultGroundingHook;
-module.exports.vaultGroundingHook = vaultGroundingHook;