"Initial release: code-hq v1.0.0

Author: trentbrew

.\out\windows-style.json

@@ -0,0 +1,77 @@
+# Copilot Instructions — TQL / EAV • Datalog • EQL-S • Graph
+
+**What this is.** Schema-agnostic querying over JSON via an **EAV store**, a **Datalog evaluator**, and the **EQL-S** DSL. Exposed through a **TQL CLI**, optional **NL orchestrator**, and a **graph engine** for agentic workflows.
+
+## Files you should know first
+- Store: `src/eav-engine.ts` — JSON → `attr(e,a,v)` facts, indexes (**EAV/AEV/AVE**), optional `link(e1,rel,e2)`.
+- Evaluator: `src/query/datalog-evaluator.ts` — semi-naive Datalog; attr/link/string/regex/numeric/date ops.
+- DSL/Compiler: `src/query/**` — parses EQL-S to evaluator IR.
+- CLI: `src/cli/tql.ts` — loads files/URLs → builds one store → runs EQL-S → prints table/json/csv.
+- Orchestrator: `src/ai/orchestrator.ts` — NL → EQL-S (used by `--nl`).
+- Agent graph runtime: `src/graph/**` — deterministic node/edge engine, budgets/timeouts, per-step traces, pluggable executors & tools.
+
+## Conventions (don't fight these)
+- **Entity IDs:** `type:id` (e.g., `post:123`). Namespaces are distinct (`user:1` ≠ `post:1`).
+- **Attributes:** JSON dot paths (`"address.city"`, `"reactions.likes"`). Arrays → multiple facts.
+- **Imports:** TypeScript bundler mode → always use **`.js`** in relative imports:
+  ```ts
+  import { EAVStore } from '../eav-engine.js'
+  import data from './seed.json' assert { type: 'json' }
+  ```
+- **Planner intent:** push filters before joins; prefer **AVE/link** indexes over scans/regex.
+
+## Daily workflows
+- Type check: `bun run typecheck`
+- Demos: `bun run examples/eav-demo.ts` · `bun run examples/tql-demo.ts`
+- CLI help: `bun run tql --help`
+
+## EQL-S quick patterns (copy/paste)
+```eql
+-- Basic
+FIND post AS ?p RETURN ?p
+
+-- Project attributes (compiler injects attr goals)
+FIND post AS ?p RETURN ?p.id, ?p.title
+
+-- Filtered
+FIND post AS ?p WHERE ?p.views > 1000 RETURN ?p.id, ?p.title ORDER BY ?p.views DESC LIMIT 10
+
+-- Attribute join
+FIND post AS ?p, user AS ?u WHERE ?p.userId = ?u.id RETURN ?u.name, ?p.title
+
+-- With links (if ingested)
+FIND post AS ?p, user AS ?u WHERE LINK(?p,"BY",?u) RETURN ?u.name, ?p.title
+
+-- Anti-join
+FIND user AS ?u WHERE NOT EXISTS LINK(?p,"BY",?u) RETURN ?u.id, ?u.name
+```
+
+## CLI examples
+```bash
+# Local file
+bun run tql -d data/posts.json -q "FIND post AS ?p WHERE ?p.title CONTAINS \"dolor\" RETURN ?p.id, ?p.title"
+
+# Remote URL
+bun run tql -d https://jsonplaceholder.typicode.com/users -q "FIND user AS ?u RETURN ?u.id, ?u.email"
+
+# Natural language (routes through orchestrator)
+bun run tql -d data/posts.json -q "show posts with >1000 views" --nl
+```
+
+## Agent graph runtime (for LLM workflows)
+- Engine: `src/graph/engine.ts` yields **per-step traces** (async generator) and enforces **maxSteps/perNodeMs**.
+- Node kinds: `Agent` (LLM), `Tool` (function), `Router`, `Guard`, `MemoryRead/Write`, `End`.
+- Deterministic routing: edge labels unique per source node; validated in `validators.ts`.
+- Streaming/logging: subscribe to step events; emit structured traces for UIs/logs.
+- Handy tool: `tql_query` to run EQL-S against an in-memory store inside a graph flow.
+
+## Project-specific gotchas
+- **Case matters for data**, not for keywords: keep `type`/attribute strings exactly as in the data (e.g., `post`, not `POST`).
+- Returning `?x.path` can **fan out** if multi-valued; the runner's projection policy controls this.
+- Always add `.js` in local TS imports; missing suffix breaks Bun/ts-bundler.
+- Arrays are not single entities: create one entity per element on ingest.
+
+## When extending
+- New data → use `jsonEntityFacts(...)`, keep `type:id`, then query.
+- New predicate → register in evaluator (arity + handler) and keep recursion monotone.
+- Cross-entity joins → either `?a.fk = ?b.id` or synthesize `LINK` edges at ingest (faster and cleaner).

.github/copilot-instructions.md

@@ -0,0 +1,43 @@
+---
+description: Execute the implementation planning workflow for TQL EAV Datalog Engine features using the plan template.
+---
+
+Given the TQL feature implementation details provided as an argument, do this:
+
+1. Run `.specify/scripts/bash/setup-plan.sh --json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute.
+2. Read and analyze the feature specification to understand:
+   - EAV engine requirements and query patterns
+   - AI orchestration and natural language processing needs
+   - Datalog evaluation and external predicate requirements
+   - CLI integration and data ingestion patterns
+   - Cross-domain compatibility and schema-agnostic features
+
+3. Read the TQL constitution at `.specify/memory/constitution.md` to understand TQL-specific architectural principles.
+
+4. Execute the TQL implementation plan template:
+   - Load `.specify/templates/plan-template.md` (already copied to IMPL_PLAN path)
+   - Set Input path to FEATURE_SPEC
+   - Run the Execution Flow (main) function steps 1-9
+   - Focus on TQL-specific patterns:
+     * EAV fact generation and ingestion workflows
+     * Query engine integration (Datalog + external predicates)
+     * AI orchestrator integration for natural language processing
+     * CLI tool extension patterns
+     * Cross-component data flow validation
+   - The template is self-contained and executable
+   - Follow error handling and gate checks as specified
+   - Let the template guide artifact generation in $SPECS_DIR:
+     * Phase 0 generates research.md (focusing on EAV patterns and Datalog requirements)
+     * Phase 1 generates data-model.md, contracts/, quickstart.md
+     * Phase 2 generates tasks.md (with TQL development workflow)
+   - Incorporate user-provided details from arguments into Technical Context: $ARGUMENTS
+   - Update Progress Tracking as you complete each phase
+
+5. Verify execution completed:
+   - Check Progress Tracking shows all phases complete
+   - Ensure all required artifacts were generated
+   - Confirm no ERROR states in execution
+
+6. Report results with branch name, file paths, and generated artifacts.
+
+Use absolute paths with the repository root for all file operations to avoid path issues.

.github/prompts/plan.prompt.md

@@ -0,0 +1,18 @@
+---
+description: Create or update the TQL feature specification from a natural language feature description, focusing on EAV engine capabilities.
+---
+
+Given the TQL feature description provided as an argument, do this:
+
+1. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
+2. Load `.specify/templates/spec-template.md` to understand required sections for TQL features.
+3. Write the specification to SPEC_FILE using the template structure, focusing on TQL-specific aspects:
+   - EAV data ingestion patterns and entity modeling
+   - Query requirements (Datalog patterns, external predicates)
+   - AI orchestration needs (natural language processing, intent analysis)
+   - CLI integration and cross-domain compatibility
+   - Performance considerations for in-memory triple store operations
+   Replace placeholders with concrete details derived from the feature description while preserving section order and headings.
+4. Report completion with branch name, spec file path, and readiness for the TQL planning phase.
+
+Note: The script creates and checks out the new branch and initializes the spec file before writing.

.github/prompts/specify.prompt.md

@@ -0,0 +1,63 @@
+---
+description: Generate actionable, dependency-ordered tasks.md for TQL features based on EAV engine architecture and AI orchestration patterns.
+---
+
+Given the TQL feature context provided as an argument, do this:
+
+1. Run `.specify/scripts/bash/check-task-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+2. Load and analyze available design documents with TQL context:
+   - Always read plan.md for EAV patterns, query engine integration, and AI orchestrator usage
+   - IF EXISTS: Read data-model.md for entity schemas and fact generation patterns
+   - IF EXISTS: Read contracts/ for API endpoints and external predicate definitions
+   - IF EXISTS: Read research.md for Datalog evaluation and performance decisions
+   - IF EXISTS: Read quickstart.md for cross-domain query scenarios
+
+   Note: TQL features may focus on different components:
+   - EAV engine features might not need contracts/
+   - Query engine features focus on datalog-evaluator.ts patterns
+   - AI features emphasize orchestrator.ts integration
+   - CLI features extend src/cli/tql.ts patterns
+
+3. Generate TQL-specific tasks following the template:
+   - Use `.specify/templates/tasks-template.md` as the base
+   - Replace example tasks with TQL-appropriate tasks:
+     * **Setup tasks**: Bun dependencies, TypeScript configuration, TQL build setup
+     * **Test tasks [P]**: EAV fact ingestion tests, query evaluation tests, orchestrator tests
+     * **Core tasks**: Entity fact generation, query pattern implementation, external predicates
+     * **Integration tasks**: AI model integration, CLI command integration, cross-component data flow
+     * **Polish tasks [P]**: Demo creation (examples/), performance benchmarks, documentation
+
+4. TQL task generation rules:
+   - Each EAV ingestion pattern → fact generation test task marked [P]
+   - Each query pattern in data-model → query implementation task marked [P]
+   - Each external predicate → predicate test and implementation (not parallel if shared evaluator)
+   - Each AI orchestration scenario → integration test marked [P]
+   - Each CLI command → command test and implementation
+   - Different TQL components = can be parallel [P] (eav-engine.ts, query/, ai/)
+   - Same file = sequential (no [P])
+
+5. Order tasks by TQL architecture dependencies:
+   - Setup before everything (Bun, TypeScript, dependencies)
+   - EAV engine tests before query engine (fact generation foundation)
+   - Query engine tests before AI orchestrator (query patterns foundation)
+   - Core implementation before CLI integration
+   - Component tests before cross-component integration
+   - Everything before demos and polish
+
+6. Include TQL-specific parallel execution examples:
+   - Group [P] tasks for independent TQL components
+   - Show examples using TQL demo patterns (bun run demo:eav, etc.)
+   - Reference TQL CLI workflows (bun run tql commands)
+
+7. Create FEATURE_DIR/tasks.md with:
+   - Correct TQL feature name from implementation plan
+   - TQL-specific task patterns and dependencies
+   - Integration with existing TQL architecture (src/eav-engine.ts, src/query/, src/ai/, src/cli/)
+   - Numbered tasks (T001, T002, etc.)
+   - Clear file paths for each task
+   - Dependency notes
+   - Parallel execution guidance
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.

.github/prompts/tasks.prompt.md

@@ -0,0 +1,27 @@
+name: CI
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: stable
+
+      - name: Install deps
+        run: bun install
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Run tests
+        run: bun run test

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+_.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store
+.tql-cache