@geraldmaron/construct 1.0.17 → 1.0.19

package/templates/docs/research-finding.md

@@ -1,26 +1,51 @@
 ---
 kind: research-finding
 topic: "<short topic line>"
-confidence: inferred
+confidence: high | medium | low
 sources: []
 created: <ISO timestamp set by construct knowledge add>
-expiresAt: <ISO timestamp, default created + 90d>
+expiresAt: <ISO timestamp, default created + 90d; shorten for fast-moving topics>
 profile: <active profile id>
 ---
 
+<!--
+A lightweight but rigorous knowledge-store entry. Same evidence standard as a
+research brief, condensed: observation separated from inference, every finding
+cited, confidence tied to source grade, an explicit refresh trigger. See
+rules/common/research.md.
+-->
+
+## SOURCES
+
+| Title / Path | Class | Reliability | Credibility | Date | URL | Verified |
+|---|---|---|---|---|---|---|
+| {source} | primary / secondary / tertiary | A–F | 1–6 | {YYYY-MM-DD} | {url} | yes / no |
+
 ## FINDINGS
 
-- <Finding 1 with citation>
-- <Finding 2 with citation>
+<!-- Observation only: what the source states. Each finding cites a source row above. -->
+
+- <Finding 1 [source: …]>
+- <Finding 2 [source: …]>
 
 ## INFERENCES
 
-- <Inference labeled as such>
+<!-- What is concluded beyond what any single source says. Labeled as inference, not fact. -->
+
+- <Inference, with the findings it rests on>
+
+## CONFIDENCE
+
+<!-- high / medium / low, with the reasoning: tie it to the Admiralty grade of the sources (research.md §10). high only on A1/A2/B1. Name the strongest counter-evidence. -->
 
 ## GAPS
 
-- <What we could not confirm>
+- <What could not be confirmed and would change the conclusion if known>
 
 ## RECOMMENDATION
 
-- <Next action based on the evidence available>
+- <Next action based on the evidence available, and the threshold that would change it>
+
+## REFRESH
+
+<!-- When this finding should be re-verified: the expiresAt date, or the event that would invalidate it (a new release, a superseding paper). -->

package/templates/docs/rfc.md

@@ -22,7 +22,19 @@ contract, API, schema, or protocol consumed by other systems.
 <!-- What problem or limitation drives this proposal? Include evidence: incidents, performance data, support tickets, developer friction. Explain why the status quo is not acceptable. -->
 
 ## Proposed design
-<!-- The concrete proposal. Enough detail for reviewers to evaluate feasibility and tradeoffs. Diagrams, code sketches, and data models are appropriate here. -->
+<!-- The concrete proposal. Enough detail for reviewers to evaluate feasibility and tradeoffs. The sequence below shows the proposed behavior in context — include the happy path and at least one error path. -->
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Service
+  participant Store
+  Client->>Service: request
+  Service->>Store: read or write
+  Store-->>Service: result
+  Service-->>Client: response
+  Note over Service,Store: error path — Store unavailable → Service returns degraded response
+```
 
 ## Tradeoffs and alternatives
 <!-- The other credible designs considered. For each: what it is, why it was not chosen, and under what conditions it would be preferred. No strawmen. -->

package/templates/docs/runbook.md

@@ -14,8 +14,27 @@
 ## Impact
 <!-- Who is affected and how badly. Data loss? Degraded performance? Complete outage? -->
 
+## Severity and response
+<!-- Map each severity to the response it triggers: page urgency, comms cadence, and error-budget consequence. A SEV-1 pages immediately and freezes related releases per the error-budget policy (https://sre.google/workbook/error-budget-policy/); a SEV-3 is handled in business hours. -->
+
+| Severity | Trigger condition | Page within | Comms | Error budget |
+|----------|-------------------|-------------|-------|--------------|
+| SEV-1 | {full outage / data loss / SLO breach} | 5 min | exec + status page | breach → freeze releases |
+| SEV-2 | {major degradation, workaround exists} | 15 min | team + stakeholders | partial spend |
+| SEV-3 | {minor / single-tenant / cosmetic} | business hours | team channel | none |
+
 ## Diagnostic steps
-<!-- Ordered checks from cheapest to most expensive. Each step: what to check, how to check it, what the answer means. -->
+<!-- Ordered checks from cheapest to most expensive. Each step: what to check, how to check it, what the answer means. Keep the decision tree below in sync with the steps. -->
+
+```mermaid
+flowchart TD
+  A[Alert fires] --> B{Error rate elevated?}
+  B -->|Yes| C[Check upstream dependency health]
+  B -->|No| D{User-visible impact?}
+  C --> E[Apply remediation]
+  D -->|Yes| C
+  D -->|No| F[Monitor and stand down]
+```
 
 ## Remediation
 <!-- The fix. Step-by-step, with exact commands or UI paths. Include expected output for each step. -->

package/templates/docs/signal-brief.md

@@ -13,7 +13,10 @@ without pretending the requirements are ready.
 <!-- One or two paragraphs. What appears to be happening, and where the signal came from. -->
 
 ## Evidence
-<!-- Cite the concrete notes, tickets, customer quotes, traces, or analytics that support the signal. -->
+<!-- Cite the concrete notes, tickets, customer quotes, traces, or analytics. Grade each source with its Admiralty reliability/credibility (rules/common/research.md §10); for community sources note corroboration and engagement. The signal strength above should follow from the grades, not precede them. -->
+
+## Counter-signal
+<!-- The strongest evidence against the signal, or its absence. A signal no one tried to disconfirm is weaker than it looks. -->
 
 ## Why it matters
 <!-- What product, customer, or business decision this could affect if the signal strengthens. -->

package/templates/docs/skill-artifact.md

@@ -1,9 +1,11 @@
 ---
 name: <verb-led-id>
 scope: "<one paragraph: what it covers, what it does not>"
-observable_outcome: <how someone outside the role tells this skill happened>
+observable_outcome: <how someone outside the role tells this skill happened — a concrete artifact, not "understands X">
+prerequisites:
+  - <skill-id or capability that must exist before this one is useful>
 provenance:
-  - <citation: post-mortem, public framework, competency model>
+  - <citation: post-mortem, public framework, competency model, with URL>
 roles:
   - <role-id that uses this skill>
 ---
@@ -12,16 +14,34 @@ roles:
 
 ## What this skill produces
 
-<Concrete output. Bloom-style: not "knows X" but "produces Y".>
+<Concrete output, Bloom-style: not "knows X" but "produces Y". Name the artifact and what makes it correct. Example: "a runbook whose diagnostic flowchart branches to a fix in ≤3 steps", not "understands incident response".>
 
 ## When to invoke it
 
-<Triggers. What the operator or the upstream persona is doing when this skill is the right call.>
+<Triggers. What the operator or upstream persona is doing when this skill is the right call. Include the signal that distinguishes it from adjacent skills.>
 
-## How it composes
+## Prerequisites and composition
 
-<Other skills typically chained before or after.>
+<What must be true or done first, and the skills typically chained before and after. A skill with unmet prerequisites produces confident-looking but wrong output.>
+
+## Competency rubric
+
+<What the skill looks like at each level. The author of an artifact should be able to place their work on this scale.>
+
+| Level | What it looks like |
+|-------|--------------------|
+| Novice | <produces the artifact but misses edge cases / evidence / failure paths> |
+| Competent | <covers the happy path and the common failure modes; cites sources> |
+| Expert | <anticipates the non-obvious failure, calibrates confidence, leaves the next person a reproducible trail> |
+
+## Failure modes
+
+<How this skill breaks when misapplied — distinct from anti-patterns. What does a wrong-but-plausible output look like, and what signal reveals it? When should the operator escalate or stop?>
 
 ## Anti-patterns
 
-<Ways this skill gets misapplied; what looks similar but is not this.>
+<Ways this skill gets misapplied; what looks similar but is not this skill.>
+
+## Worked example
+
+<A short, concrete instance: the trigger, the artifact produced, and why it meets the observable outcome. One real example removes more ambiguity than a page of guidance.>

package/templates/docs/strategy.md

@@ -15,8 +15,8 @@ Owning workflow: skills/docs/strategy-workflow.md.
 <!-- 1–3 sentences. Where are we going in 3–5 years? -->
 
 ## Bets
-<!-- Explicit choices. Each bet: what we're doing and why. -->
-- **Bet 1**: …
+<!-- Explicit choices. Each bet: what we're doing, why, the leading indicator that tells us early if it's working, and the kill criterion that ends it. A bet with no kill criterion is a belief, not a bet. -->
+- **Bet 1**: … **Why**: … **Leading indicator**: … **Kill criterion**: {what observation would make us stop}
 - **Bet 2**: …
 
 ## Non-bets
@@ -29,6 +29,27 @@ Owning workflow: skills/docs/strategy-workflow.md.
 ## North Star Metric
 <!-- Single measurable outcome. Format: Metric / Baseline / Target / Owner -->
 
+## Metrics
+<!-- The North Star is lagging. Name the leading indicators that move first and predict it, so a failing bet is visible before the lagging metric confirms it. -->
+
+| Metric | Type (leading/lagging) | Baseline | Target | Owner |
+|--------|------------------------|----------|--------|-------|
+| {name} | leading / lagging | {value} | {value} | {who} |
+
+## Milestones
+<!-- What must be true by when. Each milestone is a checkpoint that confirms or kills a bet. -->
+
+| Milestone | By when | Confirms / kills |
+|-----------|---------|------------------|
+| {what}    | {date}  | {which bet}      |
+
+## Risks
+<!-- What could invalidate the strategy. Risk register, not a worry list. -->
+
+| Risk | Likelihood | Impact | Mitigation / leading signal |
+|------|-----------|--------|------------------------------|
+| {what} | high/med/low | high/med/low | {response} |
+
 ## Competitive Positioning
 <!-- How we differentiate. 2–4 sentences. -->
 

package/templates/docs/test-plan.md

@@ -0,0 +1,96 @@
+# Test Plan: {feature or system name}
+
+- **Date**: {YYYY-MM-DD}
+- **Owner**: {name or role}
+- **Status**: draft | in-review | approved | executed
+- **Related**: {PRD / ADR paths or none}
+
+<!--
+Use this when a feature, migration, or system change needs a deliberate
+verification strategy before it ships. The plan is the contract between
+what was specified and what will be proven; every scenario below must
+trace to a requirement or an observed risk, never to guesswork.
+
+Before drafting, read rules/common/framing.md and rules/common/no-fabrication.md.
+Acceptance criteria must be binary pass/fail. If a criterion cannot be
+checked without asking the author, it is not done. Cite the requirement
+(FR/NFR id, ADR decision, ticket) each scenario verifies.
+-->
+
+## Scope
+<!--
+What is under test and what is explicitly not. Name the components, surfaces,
+or behaviors covered. The out-of-scope list protects reviewer attention and
+makes coverage gaps deliberate rather than accidental.
+-->
+
+| | Description |
+|---|---|
+| **In scope** | <what this plan verifies> |
+| **Out of scope** | <related behavior deliberately not tested here, and why> |
+
+## Test strategy
+<!--
+The levels of testing applied and why each is justified. Map levels to risk:
+unit for logic, integration for contracts and boundaries, end-to-end for
+user-visible flows, manual/exploratory for what automation cannot reach.
+State what each level is responsible for so coverage gaps are visible.
+-->
+
+| Level | What it covers | Why it lives at this level |
+|---|---|---|
+| Unit | <logic, pure functions, edge cases> | <reason> |
+| Integration | <contracts, boundaries, data access> | <reason> |
+| End-to-end | <user-visible flows> | <reason> |
+| Manual / exploratory | <what automation cannot reach> | <reason> |
+
+## Key scenarios
+<!--
+The scenarios that prove the change works. Each scenario names the requirement
+it verifies, the setup, the action, and the binary acceptance criterion. A
+reviewer must be able to run or read the scenario and decide pass/fail without
+asking the author.
+-->
+
+| ID | Scenario | Verifies | Acceptance (binary pass/fail) |
+|---|---|---|---|
+| TC-1 | <setup, action, expected result> | <FR/NFR id or risk> | <observable condition> |
+| TC-2 | <...> | <...> | <...> |
+
+## Risks and edge cases
+<!--
+The failure modes and boundary conditions worth explicit attention: empty
+inputs, concurrency, partial failure, large data, permission boundaries,
+rollback. For each, state how the plan covers it or why the residual risk
+is accepted.
+-->
+
+| Risk / edge case | Likelihood | Impact | Coverage or accepted reason |
+|---|---|---|---|
+| <condition> | low / med / high | low / med / high | <how it is tested, or why accepted> |
+
+## Environments and data
+<!--
+Where tests run and what data they use. Name the environments, fixtures,
+seed data, and any external dependencies (sandboxes, stubs, recorded
+responses). Flag data that must be synthetic or anonymized.
+-->
+
+## Entry and exit criteria
+<!--
+Entry: what must be true before testing starts (build available, environment
+provisioned, dependencies stubbed). Exit: what must be true to call testing
+done (all blocking scenarios pass, known issues triaged, coverage threshold
+met). Both are checklists a reviewer can verify.
+-->
+
+**Entry criteria**
+
+- <condition that must hold before execution begins>
+
+**Exit criteria**
+
+- <condition that must hold to declare the plan executed>
+
+## References
+<!-- PRD, ADR, RFC, related test plans, prior incidents. -->

package/lib/bootstrap/lazy-install.mjs

@@ -1,161 +0,0 @@
-/**
- * lib/bootstrap/lazy-install.mjs — on-demand resource installer with consent gating.
- *
- * When a runtime code path needs a resource that is not present, call
- * `lazyInstall(id)`. The function:
- *
- *   1. Reads cached operator consent from config.env (consent key set by the
- *      resource definition in `lib/bootstrap/resources.mjs`).
- *   2. If consent is 'never', returns { installed: false, fallback: <text> }
- *      without prompting or printing anything.
- *   3. If a TTY is available, prompts the user with the resource displayName,
- *      estimated download size, and [y/n/never].
- *   4. On 'y' or an existing 'yes' consent: calls resource.install(), waits
- *      for it to complete, updates config.env, and returns { installed: true }.
- *   5. On 'n': returns { installed: false, fallback: <text> } without saving.
- *   6. On 'never': writes 'never' to config.env and returns { installed: false }.
- *
- * Hooks that run without a TTY (most hook invocations) skip to step 2 and
- * use the fallback silently.
- *
- * Consent is cached per-resource in config.env so the prompt never repeats
- * across process restarts once the user has answered.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import readline from 'node:readline';
-
-import { getResource, probeResource } from './resources.mjs';
-
-const CONFIG_ENV = path.join(os.homedir(), '.construct', 'config.env');
-
-function readConfigEnv() {
-  try {
-    return fs.readFileSync(CONFIG_ENV, 'utf8');
-  } catch {
-    return '';
-  }
-}
-
-function readConsentFromEnv(consentKey) {
-  const lines = readConfigEnv().split('\n');
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-    const eq = trimmed.indexOf('=');
-    if (eq === -1) continue;
-    const k = trimmed.slice(0, eq).trim();
-    const v = trimmed.slice(eq + 1).trim().replace(/^['"]|['"]$/g, '');
-    if (k === consentKey) return v;
-  }
-  return null;
-}
-
-function writeConsentToEnv(consentKey, value) {
-  let content = readConfigEnv();
-  const regex = new RegExp(`^${consentKey}=.*$`, 'm');
-  const line = `${consentKey}=${value}`;
-  if (regex.test(content)) {
-    content = content.replace(regex, line);
-  } else {
-    content = content.trimEnd() + (content ? '\n' : '') + line + '\n';
-  }
-  fs.mkdirSync(path.dirname(CONFIG_ENV), { recursive: true });
-  fs.writeFileSync(CONFIG_ENV, content, { mode: 0o600 });
-}
-
-function hasTty() {
-  return Boolean(process.stdin.isTTY && process.stderr.isTTY);
-}
-
-function formatBytes(bytes) {
-  if (!bytes) return '';
-  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
-  return `${Math.round(bytes / (1024 * 1024))} MB`;
-}
-
-async function promptUser(question) {
-  return new Promise((resolve) => {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim().toLowerCase());
-    });
-  });
-}
-
-/**
- * Attempt to install a resource lazily, respecting cached consent.
- *
- * @param {string} id - resource id from the registry
- * @param {object} [opts]
- * @param {boolean} [opts.silent] - skip TTY prompt, use cached consent only
- * @returns {{ installed: boolean, fallback?: string, error?: string }}
- */
-export async function lazyInstall(id, { silent = false } = {}) {
-  const resource = getResource(id);
-  if (!resource) {
-    return { installed: false, error: `unknown resource: ${id}` };
-  }
-
-  const probe = await probeResource(resource);
-  if (probe.present && probe.healthy) {
-    return { installed: true };
-  }
-
-  const { consentKey, displayName, downloadSize, fallback } = resource;
-  const fallbackMsg = typeof fallback === 'function' ? fallback() : (fallback || '');
-
-  const cached = readConsentFromEnv(consentKey);
-
-  if (cached === 'never') {
-    return { installed: false, fallback: fallbackMsg };
-  }
-
-  if (cached === 'yes') {
-    return await performInstall(resource, fallbackMsg);
-  }
-
-  if (silent || !hasTty()) {
-    return { installed: false, fallback: fallbackMsg };
-  }
-
-  const size = downloadSize ? ` (~${formatBytes(downloadSize)})` : '';
-  const answer = await promptUser(
-    `\n[construct] ${displayName} required${size}. Install now? [y/n/never] `
-  );
-
-  if (answer === 'y' || answer === 'yes') {
-    writeConsentToEnv(consentKey, 'yes');
-    return await performInstall(resource, fallbackMsg);
-  }
-
-  if (answer === 'never') {
-    writeConsentToEnv(consentKey, 'never');
-    process.stderr.write(
-      `[construct] "${displayName}" will not be prompted again. Using fallback: ${fallbackMsg}\n`
-    );
-    return { installed: false, fallback: fallbackMsg };
-  }
-
-  return { installed: false, fallback: fallbackMsg };
-}
-
-async function performInstall(resource, fallbackMsg) {
-  if (typeof resource.install !== 'function') {
-    return { installed: false, fallback: fallbackMsg, error: 'resource has no install()' };
-  }
-  try {
-    process.stderr.write(`[construct] Installing ${resource.displayName}...\n`);
-    const result = await resource.install();
-    if (result?.success) {
-      process.stderr.write(`[construct] ${resource.displayName} installed.\n`);
-      return { installed: true };
-    }
-    return { installed: false, fallback: fallbackMsg, error: result?.log };
-  } catch (err) {
-    return { installed: false, fallback: fallbackMsg, error: err?.message || String(err) };
-  }
-}

package/lib/embed/jobs/vector-sync.mjs

@@ -1,198 +0,0 @@
-/**
- * lib/embed/jobs/vector-sync.mjs — Automatic embedding pipeline for observations.
- *
- * Runs on a schedule (default: every 5 minutes) to embed new/modified observations
- * and store them in Postgres (if available) and/or the local vector index.
- *
- * Design:
- *   - Scans .cx/observations/ for items not yet embedded
- *   - Embeds each using the configured model (local ONNX, OpenAI, Ollama)
- *   - Stores in Postgres construct_observations table (if DATABASE_URL set)
- *   - Falls back to local vectors.json if Postgres unavailable
- *   - Batched processing to avoid overwhelming the embedding API
- *   - Deduplicated via content hash comparison
- */
-import { existsSync, readFileSync, writeFileSync, statSync, mkdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
-
-const DEFAULT_BATCH_SIZE = 32;
-const DEFAULT_INTERVAL_MS = 5 * 60 * 1000;
-
-/**
- * Find observations that haven't been embedded yet.
- * @param {string} rootDir
- * @returns {Array<{ id: string, project: string, role: string, category: string, summary: string, content: string, tags: string[], confidence: number, source: string, filePath: string }>}
- */
-function findUnembeddedObservations(rootDir) {
-  const obsDir = join(rootDir, '.cx', 'observations');
-  if (!existsSync(obsDir)) return [];
-
-  const indexPath = join(obsDir, 'index.json');
-  if (!existsSync(indexPath)) return [];
-
-  let index;
-  try {
-    index = JSON.parse(readFileSync(indexPath, 'utf8'));
-  } catch (err) {
-    process.stderr.write('[jobs/vector-sync.mjs] findUnembedded: ' + (err?.message ?? String(err)) + '\n');
-    return [];
-  }
-
-  // Check which observations have been embedded
-  const vectorsPath = join(obsDir, 'vectors.json');
-  const embeddedIds = new Set();
-  if (existsSync(vectorsPath)) {
-    try {
-      const vectors = JSON.parse(readFileSync(vectorsPath, 'utf8'));
-      for (const v of (vectors.records || vectors)) {
-        if (v.id) embeddedIds.add(v.id);
-      }
-    } catch { /* ignore */ }
-  }
-
-  // Also check Postgres if available
-  // (This is handled by the caller via VectorClient.isHealthy())
-
-  return (index || [])
-    .filter((obs) => obs.id && !embeddedIds.has(obs.id))
-    .map((obs) => ({
-      ...obs,
-      filePath: join(obsDir, `${obs.id}.json`),
-    }))
-    .filter((obs) => existsSync(obs.filePath));
-}
-
-/**
- * Run the vector sync job.
- * @param {object} opts
- * @param {string} opts.rootDir - Root directory for observation store
- * @param {object} opts.env - Environment variables
- * @param {object} opts.logger - Optional logger with debug/info/error methods
- * @param {object} opts.vectorClient - Optional VectorClient instance for SQL storage
- * @returns {Promise<{ synced: number, errors: number, durationMs: number }>}
- */
-export async function runVectorSync({ rootDir, env = process.env, logger, vectorClient } = {}) {
-  const startTime = Date.now();
-  const batchSize = parseInt(env.CONSTRUCT_EMBEDDING_BATCH_SIZE, 10) || DEFAULT_BATCH_SIZE;
-
-  try {
-    const unembedded = findUnembeddedObservations(rootDir);
-    if (!unembedded.length) {
-      logger?.debug?.('Vector sync: no new observations to embed');
-      return { synced: 0, errors: 0, durationMs: Date.now() - startTime };
-    }
-
-    let synced = 0;
-    let errors = 0;
-
-    // Dynamically import embedding engine
-    const { embedBatch } = await import('../../storage/embeddings-engine.mjs');
-
-    for (let i = 0; i < unembedded.length; i += batchSize) {
-      const batch = unembedded.slice(i, i + batchSize);
-      const texts = batch.map((o) => `${o.summary}\n${o.content}`);
-
-      try {
-        const embeddings = await embedBatch(texts, { env });
-
-        for (let j = 0; j < batch.length; j++) {
-          const obs = batch[j];
-          const embedding = embeddings[j].embedding;
-
-          // Store in Postgres if available
-          if (vectorClient && await vectorClient.isHealthy()) {
-            try {
-              await vectorClient.storeObservation({
-                id: obs.id,
-                project: obs.project || rootDir.split('/').pop(),
-                role: obs.role,
-                category: obs.category,
-                summary: obs.summary,
-                content: obs.content,
-                tags: obs.tags || [],
-                confidence: obs.confidence ?? 0.8,
-                source: obs.source,
-                embedding,
-              });
-            } catch (err) {
-              logger?.error?.(`Vector sync: failed to store observation ${obs.id} in SQL: ${err.message}`);
-              errors++;
-              continue;
-            }
-          }
-
-          // Always update local vectors.json
-          updateLocalVectorIndex(rootDir, obs, embedding);
-          synced++;
-        }
-      } catch (err) {
-        logger?.error?.(`Vector sync: batch embedding failed: ${err.message}`);
-        errors += batch.length;
-      }
-    }
-
-    const durationMs = Date.now() - startTime;
-    logger?.info?.(`Vector sync: embedded ${synced} observation(s) in ${durationMs}ms (${errors} errors)`);
-    return { synced, errors, durationMs };
-  } catch (err) {
-    const durationMs = Date.now() - startTime;
-    logger?.error?.(`Vector sync failed: ${err.message}`);
-    return { synced: 0, errors: 1, durationMs };
-  }
-}
-
-/**
- * Update the local vectors.json index with a new embedding.
- * @param {string} rootDir
- * @param {object} obs - Observation record
- * @param {Float32Array} embedding
- */
-function updateLocalVectorIndex(rootDir, obs, embedding) {
-  const obsDir = join(rootDir, '.cx', 'observations');
-  const vectorsPath = join(obsDir, 'vectors.json');
-
-  let vectors;
-  if (existsSync(vectorsPath)) {
-    try {
-      vectors = JSON.parse(readFileSync(vectorsPath, 'utf8'));
-    } catch (err) {
-      process.stderr.write('[jobs/vector-sync.mjs] updateLocalVectorIndex: ' + (err?.message ?? String(err)) + '\n');
-      vectors = { version: 1, model: 'hashing-bow-v1', updatedAt: null, records: [] };
-    }
-  } else {
-    vectors = { version: 1, model: 'hashing-bow-v1', updatedAt: null, records: [] };
-  }
-
-  // Add or update the record
-  const existingIdx = vectors.records.findIndex((r) => r.id === obs.id);
-  const record = {
-    id: obs.id,
-    embedding: Array.from(embedding),
-    summary: obs.summary,
-    content: obs.content,
-    tags: obs.tags || [],
-    project: obs.project,
-    role: obs.role,
-    category: obs.category,
-    updatedAt: new Date().toISOString(),
-  };
-
-  if (existingIdx >= 0) {
-    vectors.records[existingIdx] = record;
-  } else {
-    vectors.records.push(record);
-  }
-
-  // Cap at 1000 records (sliding window)
-  if (vectors.records.length > 1000) {
-    vectors.records = vectors.records.slice(-1000);
-  }
-
-  vectors.updatedAt = new Date().toISOString();
-
-  mkdirSync(dirname(vectorsPath), { recursive: true });
-  writeFileSync(vectorsPath, JSON.stringify(vectors, null, 2), 'utf8');
-}
-
-export { DEFAULT_BATCH_SIZE, DEFAULT_INTERVAL_MS };