@rkarim08/sia 1.0.0

package/src/agent/modules/sia-regression.md

@@ -0,0 +1,115 @@
+# Sia — Regression Investigation Playbook
+
+*Loaded by the base CLAUDE.md when `task_type = 'bug-fix'` (regression signal detected).*
+*Follow these steps in order. They replace the condensed Step 1 in the base module.*
+
+---
+
+## Regression Investigation
+
+A regression is any situation where something worked before and is now broken. The key
+capability that distinguishes Sia's regression support from generic memory retrieval is
+`sia_at_time`: it lets you query the graph as it existed at a point in the past, surfacing
+exactly what facts changed between then and now.
+
+**Step 1 — Initial search (current state)**
+
+```
+sia_search(symptom_description,
+  task_type='bug-fix',
+  node_types=['Bug', 'Solution', 'Decision'],
+  limit=10)
+```
+
+Scan results for entities matching the symptom, affected files, or known related
+components. Look for a prior instance of this bug, a Decision that was recently changed,
+or a Solution that should have prevented this.
+
+**Step 2 — Causal chain traversal (conditional)**
+
+If a relevant entity is found in Step 1, call:
+
+```
+sia_expand(entity_id, depth=1, edge_types=['supersedes', 'caused_by', 'solves'])
+```
+
+This surfaces what superseded the old fact, what caused the bug, and what solutions were
+previously applied. This call is optional — use it only when the Step 1 result points to
+a likely causal chain. It counts against the 2-call sia_expand session budget.
+
+**Step 3 — Temporal investigation (MANDATORY — never skip)**
+
+```
+// Initial call — use the default limit
+sia_at_time(
+  as_of='<estimated date regression began>',
+  tags=[<relevant tags>],
+  limit=20
+)
+```
+
+Important: `limit` applies to **both** `entities[]` and `invalidated_entities[]` simultaneously. Bumping `limit` to 50 on a re-call returns 50 current entities alongside 50 invalidated entities — the extra current entities are usually irrelevant to regression work and add response payload that may hit the `maxResponseTokens` cap. Prefer narrowed re-calls over blindly increasing `limit`.
+
+If the initial call returns `invalidated_count > invalidated_entities.length` (result is truncated), make a **narrowed follow-up** targeting causally relevant entity types rather than raising `limit` alone:
+
+```
+// Truncation follow-up — narrow by type to reduce current-entity noise
+sia_at_time(
+  as_of='<same date>',
+  entity_types=['Decision', 'Solution', 'Bug'],  // causally relevant types
+  tags=[<relevant tags>],
+  limit=50
+)
+```
+
+Without this call, the temporal investigation capability is completely unused. `sia_at_time`
+returns two arrays — read them in this order:
+
+`invalidated_entities[]` is the primary diagnostic signal. These are facts that ENDED on
+or before `as_of`. Each entry's `t_valid_until` is exactly when that fact stopped being
+true. **Entries with `t_valid_until` closest to `as_of` are the most temporally
+relevant** — they represent what changed most recently before the regression and are
+therefore the highest-priority root cause candidates. The array is sorted by
+`t_valid_until DESC` so the most relevant entries appear first.
+
+`entities[]` contains facts still valid at `as_of`. Compare these against the current
+`sia_search` output to see what has changed since that date.
+
+If `invalidated_count > invalidated_entities.length`, the result is truncated. Make
+additional narrowed calls using `entity_types` or `tags` to retrieve the remaining
+entries. Do not treat a truncated result as the complete picture.
+
+**Step 4 — Explain the delta**
+
+Present the findings to the developer with specific entity citations. The answer to
+"what caused the regression" should be grounded in one or more specific invalidated
+entities, not general speculation.
+
+**Step 5 — Flag if applicable**
+
+If flagging is enabled (`enableFlagging: true`) and the root cause is non-obvious:
+`sia_flag("Root cause: [description]")`. If flagging is disabled, skip this step.
+
+---
+
+## Edge Types for Regression Investigation
+
+When calling `sia_expand` during regression work, these edge types are most diagnostic:
+
+`supersedes` — what replaced the old Decision or Solution
+`caused_by` — what entity directly caused this Bug
+`solves` — what Solution was supposed to address this Bug
+`invalidates` — what action marked the old fact as no longer true
+
+Use `edge_types=['supersedes','caused_by','solves']` as the default filter for regression
+traversal. This keeps the neighborhood focused on causal relationships rather than
+structural dependencies, which tend to be less diagnostic for regression work.
+
+---
+
+## Tool Budget for This Playbook
+
+This playbook uses up to 4 tool calls, which is the permitted exception to the 3-tool
+invariant. The sequence is: `sia_search` (1) + conditional `sia_expand` (2) +
+`sia_at_time` (3) + one additional narrowed `sia_at_time` if truncated (4). If no
+causal entity is found in Step 1, skip `sia_expand` and stay within 3 calls.

package/src/agent/modules/sia-review.md

@@ -0,0 +1,64 @@
+# Sia — PR / Code Review Playbook
+
+*Loaded by the base CLAUDE.md when `task_type = 'review'`.*
+*Follow these steps in order. They replace the condensed Step 1 in the base module.*
+
+---
+
+## PR / Code Review
+
+Code review with Sia is convention-first: retrieve the full set of project-specific
+conventions before looking at a single line of code. Generic best-practice rules are
+secondary. What matters is whether the change conforms to the patterns this team has
+established in this project.
+
+**Step 1 — Convention retrieval**
+
+```
+sia_search("conventions standards style patterns",
+  task_type='review',
+  node_types=['Convention'],
+  limit=15)
+```
+
+Use `limit=15` here — this is one of the few contexts where maximum coverage matters
+more than latency. You need the full convention set before evaluating the code.
+
+**Step 2 — File-scoped retrieval**
+
+For each file in the PR:
+
+```
+sia_by_file(file_path)
+```
+
+This surfaces decisions, patterns, and prior bug history for each changed file. A file
+that has had recurring bugs around a specific pattern is worth scrutinising more closely.
+
+**Step 3 — Evaluate each change**
+
+Compare each change against the retrieved conventions and file-specific context. The
+evaluation question is: does this change conform to the conventions the team has
+established, and does it respect the decisions that constrain this file?
+
+**Step 4 — Report violations by entity ID**
+
+For each violation, cite the specific Convention entity that is breached. Do not
+paraphrase the convention — reference it by ID so the developer can look it up:
+
+> "Violation of Convention #conv-44: direct database query in service layer —
+> all DB access must go through the Repository layer per this convention."
+
+Never apply only general best-practice conventions. Project-specific conventions
+stored in Sia take precedence and are the primary review criteria.
+
+**Step 5 — Summarise**
+
+Provide a summary that distinguishes: convention violations (must fix), Sia-unaware
+patterns (worth noting), and items where no convention applies (developer discretion).
+
+---
+
+## Tool Budget for This Playbook
+
+This playbook uses 1 + N tool calls: `sia_search` (1) + `sia_by_file` once per changed file (N calls, one each). The per-file `sia_by_file` calls are permitted by the review exception in Invariant 1 of the base module — they do not count against the 3-tool limit. This exception applies exclusively to `task_type='review'` sessions. Review is inherently multi-file and this budget is appropriate.

package/src/agent/modules/sia-tools.md

@@ -0,0 +1,239 @@
+# Sia — Full Tool Parameter Reference
+
+*Read this module when you need complete parameter documentation for any Sia tool,*
+*or when the base module's condensed guidance is insufficient for the task at hand.*
+
+---
+
+## `sia_search` — General Memory Retrieval
+
+Your primary tool. Call at the start of every non-trivial task.
+
+```
+sia_search({
+  query: string,
+  // Conversational language works well: "session timeout expiry behavior"
+  // rather than keyword fragments: "timeout session".
+
+  task_type?: 'bug-fix' | 'feature' | 'review',
+  // Boosts entity types relevant to the task:
+  //   bug-fix  → Bug, Solution, Decision entities ranked higher
+  //   feature  → Concept, Decision entities ranked higher
+  //   review   → Convention entities ranked higher
+
+  node_types?: string[],
+  // Further narrow by type: ['Decision','Convention'], ['Bug','Solution'], etc.
+  // Use when you know the category of what you're looking for.
+
+  package_path?: string,
+  // Monorepo: scope to a specific package path. Reduces cross-package noise
+  // when working in a single package of a large monorepo.
+
+  workspace?: boolean,
+  // Default false. Set true ONLY for cross-repo tasks: API contracts between
+  // linked repositories, shared types, cross-service calls.
+  // Never use for single-repo tasks — adds 400ms latency and cross-repo noise.
+
+  paranoid?: boolean,
+  // Default false. Set true when auditing external dependencies or when you want
+  // to query the graph without surface-level exposure to Tier 4 content.
+  // Filters Tier 4 entities from retrieval results only — does NOT prevent Tier 4
+  // content from being captured into the graph, and does NOT guarantee memory
+  // integrity.
+  //
+  // If the developer expresses concern about memory poisoning or graph integrity,
+  // paranoid: true on queries is insufficient. Direct them to:
+  //   paranoidCapture: true in ~/.sia/config.json
+  // which quarantines Tier 4 at the chunker stage (the hard guarantee). For past
+  // captures, suggest: npx sia rollback to inspect and revert if needed.
+
+  limit?: number,
+  // Default 5. Use 10 for architectural queries. Use 15 ONLY for PR review
+  // (full convention coverage required). Never use 15 as a default.
+
+  include_provenance?: boolean,
+  // Default false. When true, adds extraction_method to entity results.
+  // WHEN TO USE — set true only when:
+  //   (a) two Tier 3 results contradict each other (spacy is more reliable
+  //       than llm-haiku — provenance lets you choose the more reliable one)
+  //   (b) the developer asks how a fact was captured
+  //   (c) you are about to use a Tier 3 entity as a hard constraint on a
+  //       security-critical or data-migration task
+  // DO NOT use by default — adds payload for no benefit on routine queries.
+  //
+  // Values when true:
+  //   'tree-sitter' = deterministic AST extraction (Tier 2, fully reliable)
+  //   'spacy'       = deterministic NLP (Tier 3, highly reliable)
+  //   'llm-haiku'   = probabilistic LLM extraction (Tier 3, can hallucinate)
+  //   'user-direct' = developer stated this explicitly (Tier 1)
+  //   'manifest'    = declared in .sia-manifest.yaml (Tier 1)
+  // Conflict rule: prefer 'spacy' over 'llm-haiku' for Tier 3 disambiguation.
+})
+```
+
+---
+
+## `sia_by_file` — File-Scoped Memory Retrieval
+
+Call before modifying any file you have not worked on recently. Returns everything
+Sia knows about that file: decisions made about it, bugs found in it, patterns it
+implements, conventions that apply to it. This is a complement to `sia_search`,
+not an alternative — use both.
+
+```
+sia_by_file({
+  file_path: string,   // relative path from project root
+  workspace?: boolean, // default false — include cross-repo edges for this file
+  limit?: number,      // default 10
+})
+```
+
+---
+
+## `sia_expand` — Graph Relationship Traversal
+
+Call when a search result is relevant but you need to understand how it connects to
+the rest of the graph. Use sparingly — the session budget is 2 calls.
+
+```
+sia_expand({
+  entity_id: string,             // the ID from a sia_search or sia_by_file result
+  depth?: 1 | 2 | 3,            // default 1; see depth guide below
+  edge_types?: string[],         // see edge type guide below
+  include_cross_repo?: boolean,  // default false
+})
+```
+
+**Depth guide:**
+`depth=1` — immediate neighbors only. Use for 90% of cases.
+`depth=2` — multi-step causal chains. Use for regression tracing and dependency audits.
+`depth=3` — full dependency impact. The 50-entity neighbor cap will usually bind here;
+use only when a complete impact analysis is explicitly needed.
+
+**Edge type guide:**
+Regression investigation: `edge_types=['supersedes', 'caused_by', 'solves']`
+Dependency analysis:      `edge_types=['calls', 'imports', 'depends_on']`
+Decision history:         `edge_types=['supersedes', 'elaborates', 'contradicts']`
+Bug-to-solution:          `edge_types=['solves', 'caused_by']`
+
+**Hard constraints:**
+Never expand all results from a `sia_search` — context overflow is guaranteed.
+Never call `sia_expand` on Community entities — they already contain synthesised summaries.
+Budget: 2 calls per session maximum.
+
+**Edge truncation:** `SiaExpandResult.edge_count` is the total active edges in the
+neighborhood. `edges[]` is capped at 200. If `edge_count > edges.length`, the traversal
+is incomplete. Narrow with an `edge_types` filter or reduce `depth` and re-call.
+
+---
+
+## `sia_community` — Architectural Summaries
+
+Use for broad structural questions, architectural orientation, and module-level
+understanding. Not for specific entity lookups — use `sia_search` for those.
+
+```
+sia_community({
+  query?: string,          // topic description for community selection
+  entity_id?: string,      // OR: get the community containing this specific entity
+  level?: 0 | 1 | 2,      // default 1; see level guide below
+  package_path?: string,   // monorepo: scope to a specific package
+})
+```
+
+**Level guide:**
+`level=2` — Coarse architectural overview. Use for: new developer orientation,
+system-wide design questions, "how does this system work?" queries.
+`level=1` — Subsystem / module level. Use for: "how does the auth module work?",
+before implementing a feature that spans a module.
+`level=0` — Fine-grained cluster view. Rarely needed by the agent; more useful
+from the CLI. Avoid in agent workflows.
+
+Never use `sia_search("architecture")` as a substitute for `sia_community` — it
+returns raw entity snippets (a list of class names) rather than synthesised summaries.
+
+---
+
+## `sia_at_time` — Temporal Graph Query
+
+Use for historical investigation: regressions, architecture evolution, "what changed
+about X?", "what was true before this broke?"
+
+```
+sia_at_time({
+  as_of: string,            // ISO 8601 OR relative: "7 days ago", "3 months ago", "January"
+  entity_types?: string[],  // narrow by entity type
+  tags?: string[],          // narrow by tag
+  limit?: number,           // default 20, max 50. Applies to BOTH entities[] and
+                            // invalidated_entities[]. Increase for large regressions
+                            // (many entities changed at once).
+})
+```
+
+**Output:** A `SiaTemporalResult` with two entity arrays and an edge array:
+- `invalidated_entities[]` — facts that ENDED on or before `as_of`. The change history.
+  Sorted by `t_valid_until DESC` (most recently ended first — highest priority for
+  regression diagnosis). Each entry's `t_valid_until` is exactly when that fact ended.
+- `entities[]` — facts still valid at `as_of`. Compare against current `sia_search`
+  output to see what has changed since.
+- `edges[]` — edges valid at `as_of`, capped at 50.
+- `edge_count` — total edges valid at `as_of` before the 50-cap truncation. If
+  `edge_count > edges.length`, the edge set is incomplete — narrow with `entity_types`
+  or `tags` to retrieve remaining edge context.
+
+When `invalidated_count > invalidated_entities.length`, entity results are truncated.
+Make additional narrowed calls with `entity_types` or `tags` filters to retrieve
+remaining entries. Do not assume you have the complete picture until
+`invalidated_count == invalidated_entities.length`.
+
+`sia_at_time` has no meaning in isolation. Always compare its output against the current
+graph (a current `sia_search` call) to identify what changed and what superseded each
+invalidated fact.
+
+**When `t_valid_from` is null in a result:** the entity was recorded but Sia could not
+determine when it became true in the world. Say "this was the state at some point before
+[as_of], but the exact start date is unknown."
+
+---
+
+## `sia_flag` — Mid-Session Capture Signal (If Enabled)
+
+Available only when `npx sia enable-flagging` has been run. See
+`src/agent/modules/sia-flagging.md` for full guidance.
+
+```
+sia_flag({ reason: string })   // max 100 characters after sanitization
+```
+
+The `reason` is sanitized before storage. Characters stripped: `<`, `>`, `{`, `}`,
+`[`, `]`, `\`, quotes, and control characters. Permitted: colons, backticks,
+underscores, forward slashes, `@`, and all standard punctuation. Natural root-cause
+descriptions pass through correctly.
+
+If the tool returns a disabled error, tell the developer: "This moment seems worth
+capturing. Run `npx sia enable-flagging` if you want in-session capture — otherwise
+Sia will attempt to capture it at session end via the Stop hook, with lower precision."
+
+---
+
+## Three Paranoid Modes — They Are Not Equivalent
+
+These are three distinct mechanisms that are frequently confused:
+
+**`paranoid: true` on `sia_search`** (or `npx sia search --paranoid` from CLI): filters
+Tier 4 facts from query results only. It does not prevent external content from being
+captured into the graph. A developer who uses this flag expecting "no external content
+will enter my graph" is mistaken — they have only filtered what they see, not what
+is stored.
+
+**`paranoidCapture: true` in `~/.sia/config.json`**: quarantines all Tier 4 content at
+the capture pipeline's chunker stage. This is the hard guarantee. External content never
+reaches staging, never reaches the main graph, and appears only as a `QUARANTINE` entry
+in the audit log.
+
+**`--paranoid` CLI flag**: equivalent to `paranoid: true` on `sia_search` — retrieval
+filtering only, not capture-side isolation.
+
+If a developer asks for the strongest isolation from external content, direct them to
+`paranoidCapture: true` in config, not the query-time flag. Both can be used together
+for defence in depth.

package/src/ast/extractors/c-include.ts

@@ -0,0 +1,189 @@
+// Module: c-include — C/C++ #include resolution with compile_commands.json support
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+import type { CandidateFact } from "@/capture/types";
+
+/** A single entry in compile_commands.json */
+interface CompileCommand {
+	file: string;
+	command?: string;
+	arguments?: string[];
+	directory?: string;
+}
+
+/**
+ * Parse `-I<path>` and `-I <path>` flags from a compilation command string.
+ */
+function extractIncludePathsFromCommand(command: string): string[] {
+	const paths: string[] = [];
+	const re = /-I\s*([^\s]+)/g;
+	let match = re.exec(command);
+	while (match !== null) {
+		paths.push(match[1]);
+		match = re.exec(command);
+	}
+	return paths;
+}
+
+/**
+ * Load compile_commands.json from repoRoot and find include paths for the
+ * given filePath.  Returns null if the file does not exist, [] if found but
+ * no matching entry or no -I flags.
+ */
+function loadIncludePaths(repoRoot: string, filePath: string): string[] | null {
+	const ccPath = join(repoRoot, "compile_commands.json");
+	if (!existsSync(ccPath)) {
+		return null;
+	}
+
+	try {
+		const raw = readFileSync(ccPath, "utf8") as string;
+		const commands: CompileCommand[] = JSON.parse(raw) as CompileCommand[];
+
+		const entry = commands.find((cmd) => {
+			const dir = cmd.directory ?? "";
+			const resolvedFile = dir ? join(dir, cmd.file) : cmd.file;
+			return resolvedFile === filePath || cmd.file === filePath;
+		});
+
+		if (!entry) {
+			return [];
+		}
+
+		if (entry.arguments && entry.arguments.length > 0) {
+			const paths: string[] = [];
+			for (let i = 0; i < entry.arguments.length; i++) {
+				const arg = entry.arguments[i];
+				if (arg === "-I" && i + 1 < entry.arguments.length) {
+					paths.push(entry.arguments[i + 1]);
+					i++;
+				} else if (arg.startsWith("-I") && arg.length > 2) {
+					paths.push(arg.slice(2));
+				}
+			}
+			return paths;
+		}
+
+		if (entry.command) {
+			return extractIncludePathsFromCommand(entry.command);
+		}
+
+		return [];
+	} catch {
+		return [];
+	}
+}
+
+/** Determine language tag based on file extension. */
+function langFromPath(filePath: string): string {
+	const ext = extname(filePath).toLowerCase();
+	if (ext === ".c" || ext === ".h") return "c";
+	return "cpp";
+}
+
+/**
+ * Extract `#include` directives from C/C++ source content.
+ *
+ * System includes (`<...>`) → confidence 0.80, tag `system-include`.
+ * Local includes (`"..."`) → resolved via compile_commands -I paths, then
+ * same-directory, then repo-root fallback.
+ * Resolved → confidence 0.85; unresolved → confidence 0.70.
+ */
+export function extractCIncludes(
+	content: string,
+	filePath: string,
+	repoRoot?: string,
+): CandidateFact[] {
+	if (!content) return [];
+
+	const includeRe = /^\s*#\s*include\s*(?:<([^>]+)>|"([^"]+)")/gm;
+	const directives: Array<{ name: string; isSystem: boolean; raw: string }> = [];
+	let m = includeRe.exec(content);
+	while (m !== null) {
+		if (m[1] !== undefined) {
+			directives.push({ name: m[1], isSystem: true, raw: m[0].trim() });
+		} else if (m[2] !== undefined) {
+			directives.push({ name: m[2], isSystem: false, raw: m[0].trim() });
+		}
+		m = includeRe.exec(content);
+	}
+
+	if (directives.length === 0) return [];
+
+	const lang = langFromPath(filePath);
+
+	let includePaths: string[] = [];
+
+	if (repoRoot) {
+		const loaded = loadIncludePaths(repoRoot, filePath);
+		if (loaded === null) {
+			console.warn(
+				`[c-include] compile_commands.json not found in ${repoRoot}; falling back to directory-based resolution`,
+			);
+		} else {
+			includePaths = loaded;
+		}
+	}
+
+	const facts: CandidateFact[] = [];
+
+	for (const directive of directives) {
+		if (directive.isSystem) {
+			facts.push({
+				type: "CodeEntity",
+				name: directive.name,
+				content: directive.raw,
+				summary: `System include: ${directive.name} in ${filePath}`,
+				tags: ["include", "system-include", lang],
+				file_paths: [filePath],
+				trust_tier: 2,
+				confidence: 0.8,
+				extraction_method: "c-include",
+			});
+		} else {
+			let resolvedPath: string | undefined;
+
+			for (const ip of includePaths) {
+				const candidate = join(ip, directive.name);
+				if (existsSync(candidate)) {
+					resolvedPath = candidate;
+					break;
+				}
+			}
+
+			if (!resolvedPath) {
+				const candidate = join(dirname(filePath), directive.name);
+				if (existsSync(candidate)) {
+					resolvedPath = candidate;
+				}
+			}
+
+			if (!resolvedPath && repoRoot) {
+				const candidate = join(repoRoot, directive.name);
+				if (existsSync(candidate)) {
+					resolvedPath = candidate;
+				}
+			}
+
+			const confidence = resolvedPath ? 0.85 : 0.7;
+			const filePaths = resolvedPath ? [filePath, resolvedPath] : [filePath];
+
+			facts.push({
+				type: "CodeEntity",
+				name: directive.name,
+				content: directive.raw,
+				summary: resolvedPath
+					? `Local include: ${directive.name} -> ${resolvedPath}`
+					: `Local include: ${directive.name} (unresolved) in ${filePath}`,
+				tags: ["include", lang],
+				file_paths: filePaths,
+				trust_tier: 2,
+				confidence,
+				extraction_method: "c-include",
+			});
+		}
+	}
+
+	return facts;
+}