@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/codex/db-adjacency-list/SKILL.md

@@ -0,0 +1,199 @@
+# Adjacency List
+
+> The simplest hierarchical model where each row stores a reference to its parent, traversed with recursive CTEs for subtree and ancestor queries.
+
+## When to Use
+
+- Organizational charts and reporting hierarchies
+- Category trees for e-commerce or content management
+- Comment threads and discussion forums
+- File system directory structures
+- Any hierarchy where writes are frequent and full-tree reads are uncommon
+
+## Instructions
+
+### Key Concepts
+
+Each row has a `parent_id` foreign key pointing to the same table. Root nodes have `parent_id IS NULL`:
+
+```sql
+CREATE TABLE categories (
+  id        serial PRIMARY KEY,
+  name      varchar NOT NULL,
+  parent_id int REFERENCES categories(id)
+);
+
+CREATE INDEX idx_categories_parent ON categories (parent_id);
+```
+
+**Direct parent/child queries** are trivial:
+
+```sql
+-- Direct children of category 5:
+SELECT * FROM categories WHERE parent_id = 5;
+
+-- Parent of category 12:
+SELECT p.* FROM categories p
+JOIN categories c ON c.parent_id = p.id
+WHERE c.id = 12;
+```
+
+**Subtree queries** require recursive CTEs:
+
+```sql
+WITH RECURSIVE subtree AS (
+  -- Anchor: start from the target node
+  SELECT id, name, parent_id, 0 AS depth
+  FROM categories WHERE id = 5
+
+  UNION ALL
+
+  -- Recursive: find children of current level
+  SELECT c.id, c.name, c.parent_id, s.depth + 1
+  FROM categories c
+  JOIN subtree s ON c.parent_id = s.id
+)
+SELECT * FROM subtree ORDER BY depth, name;
+```
+
+**Ancestor queries** reverse the join direction:
+
+```sql
+WITH RECURSIVE ancestors AS (
+  SELECT id, name, parent_id, 0 AS depth
+  FROM categories WHERE id = 42
+
+  UNION ALL
+
+  SELECT c.id, c.name, c.parent_id, a.depth + 1
+  FROM categories c
+  JOIN ancestors a ON a.parent_id = c.id
+)
+SELECT * FROM ancestors ORDER BY depth DESC;
+```
+
+The `depth` counter enables level-aware formatting and depth-limited queries (`WHERE depth < 3` in the recursive term).
+
+### Worked Example
+
+Category tree for an e-commerce site:
+
+```sql
+INSERT INTO categories (id, name, parent_id) VALUES
+  (1, 'Electronics', NULL),
+  (2, 'Computers', 1),
+  (3, 'Laptops', 2),
+  (4, 'Desktops', 2),
+  (5, 'Phones', 1),
+  (6, 'Accessories', 1),
+  (7, 'USB-C Cables', 6);
+```
+
+**All subcategories of Electronics (id=1):**
+
+```sql
+WITH RECURSIVE tree AS (
+  SELECT id, name, parent_id, 1 AS depth FROM categories WHERE id = 1
+  UNION ALL
+  SELECT c.id, c.name, c.parent_id, t.depth + 1
+  FROM categories c JOIN tree t ON c.parent_id = t.id
+)
+SELECT * FROM tree WHERE depth > 0 ORDER BY depth, name;
+```
+
+Returns: Accessories, Computers, Phones (depth 1), then Desktops, Laptops, USB-C Cables (depth 2).
+
+**Ancestors of USB-C Cables (id=7) up to root:**
+
+```sql
+WITH RECURSIVE path AS (
+  SELECT id, name, parent_id FROM categories WHERE id = 7
+  UNION ALL
+  SELECT c.id, c.name, c.parent_id
+  FROM categories c JOIN path p ON p.parent_id = c.id
+)
+SELECT * FROM path;
+```
+
+Returns: USB-C Cables -> Accessories -> Electronics.
+
+**Depth-limited query (max 2 levels from Electronics):**
+
+Add `WHERE t.depth < 2` in the recursive term to stop at depth 2.
+
+### Anti-Patterns
+
+1. **Multiple self-JOINs for fixed-depth trees.** Hard-coding `JOIN categories c2 ON c1.parent_id = c2.id JOIN categories c3 ON c2.parent_id = c3.id` breaks when depth changes. Use recursive CTEs.
+2. **Not indexing `parent_id`.** The recursive CTE does a lookup per level. Without an index, each step triggers a sequential scan.
+3. **Infinite loop risk without cycle detection.** Corrupt data with circular references causes infinite recursion. Use PostgreSQL 14+ `CYCLE` clause or track visited nodes in an array.
+4. **Fetching the entire tree when only a subtree is needed.** Always anchor the recursive CTE to the target node, not the root.
+
+### PostgreSQL Specifics
+
+PostgreSQL 14+ provides built-in cycle detection and traversal control:
+
+```sql
+WITH RECURSIVE tree AS (
+  SELECT id, name, parent_id FROM categories WHERE id = 1
+  UNION ALL
+  SELECT c.id, c.name, c.parent_id
+  FROM categories c JOIN tree t ON c.parent_id = t.id
+)
+SEARCH DEPTH FIRST BY id SET ordercol
+CYCLE id SET is_cycle USING path
+SELECT * FROM tree WHERE NOT is_cycle ORDER BY ordercol;
+```
+
+- `CYCLE id SET is_cycle USING path` -- automatic cycle detection
+- `SEARCH BREADTH FIRST BY id SET ordercol` -- level-order traversal
+- `SEARCH DEPTH FIRST BY id SET ordercol` -- pre-order traversal
+
+An index on `parent_id` is critical. Without it, each recursive step performs a sequential scan on the entire table.
+
+## Details
+
+### Advanced Topics
+
+**Materialized path hybrid:** Store a `path` column (e.g., `/1/6/7/`) alongside `parent_id`. Subtree queries become `WHERE path LIKE '/1/6/%'` -- no recursion needed. The `ltree` extension in PostgreSQL provides native path operations with GiST indexing. See db-hierarchical-data for a full comparison.
+
+**Performance characteristics:** Subtree queries cost O(depth) recursive steps, each scanning indexed child rows. For balanced trees this is efficient. For deep chains (depth > 100), performance degrades. Consider closure tables for deep hierarchies with frequent subtree reads.
+
+**Combining with closure table:** Use adjacency list for writes (simple parent_id update) and maintain a closure table for reads. This hybrid offers the best of both models at the cost of maintaining two data structures.
+
+### Engine Differences
+
+MySQL 8.0+ supports `WITH RECURSIVE` with compatible syntax. Earlier MySQL versions require stored procedures or application-layer recursion for tree traversal.
+
+Key MySQL differences:
+
+- MySQL lacks `CYCLE` and `SEARCH` clauses -- cycle detection must be done manually by tracking visited IDs in a VARCHAR path column
+- MySQL has a `cte_max_recursion_depth` system variable (default 1000, configurable) that limits recursion depth
+- MySQL recursive CTE performance is comparable to PostgreSQL for shallow trees (depth < 20)
+
+### Real-World Case Studies
+
+**Reddit-style comment threading with 50M comments.** Maximum thread depth of 20 levels. Adjacency list with a recursive CTE fetches a full thread (average 200 comments) in 8ms using a composite index on `(parent_id, created_at)`. The team evaluated migrating to nested sets but abandoned the effort: every new comment would require renumbering O(n) rows in the thread, and comments are inserted frequently. The adjacency list's O(1) insert was the deciding factor.
+
+## Source
+
+- [PostgreSQL WITH Queries](https://www.postgresql.org/docs/current/queries-with.html)
+- [SQL Antipatterns by Bill Karwin -- Naive Trees chapter](https://pragprog.com/titles/bksqla/sql-antipatterns/)
+
+## Process
+
+1. Read the key concepts to understand adjacency list structure and recursive CTE traversal.
+2. Apply the pattern with proper indexing on `parent_id` and cycle detection for untrusted data.
+3. Verify with EXPLAIN ANALYZE that recursive CTEs use index scans at each level.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+- **related_skills:** db-nested-sets, db-closure-table, db-hierarchical-data, db-query-rewriting
+
+## Success Criteria
+
+- Adjacency list tables have an index on `parent_id`.
+- Subtree and ancestor queries use recursive CTEs, not hard-coded multi-level JOINs.
+- Cycle detection is in place for hierarchies with untrusted or user-generated data.
+- Depth limits are applied to prevent runaway recursion.

package/dist/agents/skills/codex/db-adjacency-list/skill.yaml

@@ -0,0 +1,40 @@
+name: db-adjacency-list
+version: "1.0.0"
+description: Parent-child hierarchies via self-referencing foreign key, recursive CTEs, and depth queries
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-nested-sets
+  - db-closure-table
+  - db-hierarchical-data
+  - db-query-rewriting
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - adjacency-list
+  - parent-child
+  - self-referencing-fk
+  - recursive-CTE
+  - hierarchy
+  - tree-structure
+  - WITH-RECURSIVE
+metadata:
+  author: community
+  upstream: "postgresql.org/docs/current/queries-with.html"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/db-audit-trail/SKILL.md

@@ -0,0 +1,244 @@
+# Audit Trail
+
+> Recording who changed what, when, and why, using trigger-based or application-level change tracking with immutable append-only logs.
+
+## When to Use
+
+- Regulatory compliance (SOX, HIPAA, GDPR right-to-know)
+- Security audit requirements -- tracking privileged access and data modifications
+- Debugging production data issues ("who changed this row and when?")
+- Undo/rollback functionality at the application level
+- Change approval workflows that require before/after comparison
+
+## Instructions
+
+### Key Concepts
+
+Two approaches to change tracking:
+
+**1. Trigger-based audit:**
+
+Database triggers fire on every INSERT/UPDATE/DELETE and write to an audit table automatically. Advantages: catches all changes including raw SQL, migrations, and admin console queries. Disadvantages: tight coupling to schema, performance overhead on high-write tables, cannot capture application context (which user, which API endpoint).
+
+**2. Application-level audit:**
+
+Application code writes audit records before or after data changes. Advantages: captures business context (user ID, request ID, reason for change), can be asynchronous. Disadvantages: bypassable by raw SQL or migrations, requires discipline in every write path.
+
+**Audit table schema:**
+
+```sql
+CREATE TABLE audit_log (
+  id          bigserial PRIMARY KEY,
+  table_name  varchar NOT NULL,
+  record_id   varchar NOT NULL,
+  action      varchar NOT NULL CHECK (action IN ('INSERT', 'UPDATE', 'DELETE')),
+  old_values  jsonb,
+  new_values  jsonb,
+  changed_by  varchar,
+  changed_at  timestamptz NOT NULL DEFAULT now(),
+  context     jsonb
+);
+
+CREATE INDEX idx_audit_table_record ON audit_log (table_name, record_id, changed_at);
+```
+
+**Immutability enforcement** -- the audit table must never allow UPDATE or DELETE:
+
+```sql
+CREATE RULE no_update_audit AS ON UPDATE TO audit_log DO INSTEAD NOTHING;
+CREATE RULE no_delete_audit AS ON DELETE TO audit_log DO INSTEAD NOTHING;
+```
+
+Alternatively, use row-level security policies to prevent modifications by all roles except a dedicated audit reader role.
+
+### Worked Example
+
+Financial transactions table with trigger-based audit:
+
+**1. Generic audit trigger function:**
+
+```sql
+CREATE OR REPLACE FUNCTION audit_trigger_func()
+RETURNS trigger AS $$
+BEGIN
+  IF TG_OP = 'INSERT' THEN
+    INSERT INTO audit_log (table_name, record_id, action, new_values, changed_by)
+    VALUES (TG_TABLE_NAME, NEW.id::text, 'INSERT', to_jsonb(NEW),
+            current_setting('app.current_user', true));
+    RETURN NEW;
+
+  ELSIF TG_OP = 'UPDATE' THEN
+    INSERT INTO audit_log (table_name, record_id, action, old_values, new_values, changed_by)
+    VALUES (TG_TABLE_NAME, NEW.id::text, 'UPDATE', to_jsonb(OLD), to_jsonb(NEW),
+            current_setting('app.current_user', true));
+    RETURN NEW;
+
+  ELSIF TG_OP = 'DELETE' THEN
+    INSERT INTO audit_log (table_name, record_id, action, old_values, changed_by)
+    VALUES (TG_TABLE_NAME, OLD.id::text, 'DELETE', to_jsonb(OLD),
+            current_setting('app.current_user', true));
+    RETURN OLD;
+  END IF;
+END;
+$$ LANGUAGE plpgsql;
+```
+
+**2. Attach trigger to the transactions table:**
+
+```sql
+CREATE TRIGGER audit_transactions
+  AFTER INSERT OR UPDATE OR DELETE ON transactions
+  FOR EACH ROW EXECUTE FUNCTION audit_trigger_func();
+```
+
+**3. Performing an update and viewing the audit record:**
+
+```sql
+-- Set application context before the transaction
+SET LOCAL app.current_user = 'user_42';
+SET LOCAL app.request_id = 'req_abc123';
+
+UPDATE transactions SET amount = 150.00 WHERE id = 1;
+```
+
+**4. Querying the audit trail:**
+
+```sql
+SELECT action, old_values->>'amount' AS old_amount,
+       new_values->>'amount' AS new_amount, changed_by, changed_at
+FROM audit_log
+WHERE table_name = 'transactions' AND record_id = '1'
+ORDER BY changed_at;
+```
+
+Returns the full change history: who changed the amount, from what value, to what value, and when.
+
+### Anti-Patterns
+
+1. **Mutable audit logs.** If UPDATE or DELETE is allowed on the audit table, the audit trail can be tampered with. Enforce immutability with rules, triggers, or row-level security.
+2. **Storing only new values without old values.** Without the old values, you cannot determine what changed -- only what the current state is.
+3. **Per-table audit tables.** Creating `transactions_audit`, `accounts_audit`, `users_audit` leads to schema explosion. Use a single generic audit table with `table_name` and JSONB values.
+4. **Synchronous audit writes on hot paths.** If the audited table handles thousands of writes per second, the synchronous trigger adds latency. Consider asynchronous CDC for high-throughput tables.
+5. **Not partitioning the audit table.** Audit tables grow unbounded. Without time-based partitioning, queries slow down and storage becomes unmanageable.
+
+### PostgreSQL Specifics
+
+**hstore for row diffs** -- compute only changed columns:
+
+```sql
+CREATE EXTENSION hstore;
+
+-- In the trigger function, log only changed fields:
+INSERT INTO audit_log (table_name, record_id, action, old_values, new_values)
+VALUES (
+  TG_TABLE_NAME, NEW.id::text, 'UPDATE',
+  to_jsonb(hstore(OLD) - hstore(NEW)),  -- removed/changed fields
+  to_jsonb(hstore(NEW) - hstore(OLD))   -- new/changed fields
+);
+```
+
+This stores only the diff, dramatically reducing audit log storage for tables with many columns where most updates touch only 1-2 fields.
+
+**pg_audit extension** for statement-level audit logging -- records which SQL statements were executed and by which database role. Complementary to row-level audit triggers.
+
+**Passing application context to triggers:**
+
+```sql
+-- In the application, before each transaction:
+SET LOCAL app.current_user = 'user_42';
+SET LOCAL app.request_id = 'req_abc123';
+
+-- In the trigger, read the context:
+current_setting('app.current_user', true)  -- true = return NULL if not set
+```
+
+`SET LOCAL` scopes the setting to the current transaction. This bridges the gap between application context and database triggers.
+
+## Details
+
+### Advanced Topics
+
+**Change Data Capture (CDC)** with logical replication avoids trigger overhead entirely:
+
+- PostgreSQL's logical replication (`pgoutput` plugin) streams row changes to consumers
+- Debezium connects to PostgreSQL's replication slot and publishes changes to Kafka
+- CDC captures all changes (including raw SQL) without trigger performance penalty
+- Tradeoff: CDC is asynchronous -- there is a lag between the change and the audit record
+
+**Event sourcing** (see microservices-event-sourcing) is an audit-native architecture where the event log IS the source of truth. Rather than auditing a mutable table, every state change is an immutable event. Consider event sourcing when audit is a primary requirement, not an afterthought.
+
+**Audit log partitioning** by month with automated retention:
+
+```sql
+CREATE TABLE audit_log (
+  -- columns as above
+) PARTITION BY RANGE (changed_at);
+
+-- Create monthly partitions, drop after retention period
+-- Use pg_partman for automation
+```
+
+**JSONB diff computation** for efficient storage:
+
+```sql
+-- Store only changed fields instead of entire row snapshots
+-- Reduces audit storage by 80-90% for wide tables
+```
+
+### Engine Differences
+
+MySQL triggers use `OLD` and `NEW` row references similar to PostgreSQL:
+
+```sql
+CREATE TRIGGER audit_transactions
+AFTER UPDATE ON transactions
+FOR EACH ROW
+BEGIN
+  INSERT INTO audit_log (table_name, record_id, action, old_values, new_values)
+  VALUES ('transactions', OLD.id, 'UPDATE',
+          JSON_OBJECT('amount', OLD.amount), JSON_OBJECT('amount', NEW.amount));
+END;
+```
+
+MySQL lacks `hstore` -- use `JSON_OBJECT()` to serialize row values to JSON.
+
+MySQL does not support `CREATE RULE` for immutability. Enforce with a BEFORE trigger:
+
+```sql
+CREATE TRIGGER prevent_audit_delete
+BEFORE DELETE ON audit_log
+FOR EACH ROW
+SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Audit log rows cannot be deleted';
+```
+
+MySQL binlog serves as a CDC source -- the Debezium MySQL connector reads binlog events for change data capture.
+
+MySQL lacks `SET LOCAL` for passing application context to triggers. Use session variables (`SET @app_user = 'user_42'`) and read them in the trigger, but note these persist for the entire session, not just the current transaction.
+
+### Real-World Case Studies
+
+**Fintech platform with SOX compliance.** All changes to `accounts`, `transactions`, and `users` tables tracked via the generic trigger function. Audit table partitioned by month, retained for 7 years (regulatory requirement). Volume: 50M audit rows per month. Query pattern: "all changes to account X in last 90 days" completes in 15ms using the composite index on `(table_name, record_id, changed_at)` with partition pruning. Application context (request_id, user_id, IP address) passed via `SET LOCAL` before each transaction, stored in the audit `context` JSONB column. During a SOX audit, the team reconstructed the complete state of an account at any point in the past 7 years by replaying the audit log.
+
+## Source
+
+- [PostgreSQL PL/pgSQL Triggers](https://www.postgresql.org/docs/current/plpgsql-trigger.html)
+- [pgAudit Extension](https://www.pgaudit.org/)
+
+## Process
+
+1. Read the key concepts to understand trigger-based vs application-level audit and the tradeoffs.
+2. Apply the appropriate audit strategy based on compliance requirements and write throughput.
+3. Verify that the audit table is immutable, captures both old and new values, and is partitioned by time.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+- **related_skills:** db-temporal-data, db-time-series, db-denormalization, microservices-event-sourcing
+
+## Success Criteria
+
+- Audit table is immutable -- UPDATE and DELETE are blocked via rules, triggers, or RLS.
+- Both old and new values are captured for UPDATE operations.
+- Audit table is partitioned by time with a defined retention policy.
+- Application context (user, request ID) is recorded in audit entries.

package/dist/agents/skills/codex/db-audit-trail/skill.yaml

@@ -0,0 +1,41 @@
+name: db-audit-trail
+version: "1.0.0"
+description: Change tracking via triggers or application-level logging with immutable append-only audit logs
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-temporal-data
+  - db-time-series
+  - db-denormalization
+  - microservices-event-sourcing
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - audit-trail
+  - change-tracking
+  - trigger-based-audit
+  - audit-log
+  - immutable-log
+  - compliance
+  - change-data-capture
+  - CDC
+metadata:
+  author: community
+  upstream: "postgresql.org/docs/current/plpgsql-trigger.html"
+state:
+  persistent: false
+  files: []
+depends_on: []