@garethdaine/agentops 0.9.0

package/commands/unicode-scan.md

@@ -0,0 +1,63 @@
+---
+name: unicode-scan
+description: Scan project for dangerous invisible Unicode characters (Glassworm/Trojan Source defense)
+---
+
+You are running a Unicode security scan on the current project directory.
+
+## What to scan for
+
+Use `perl -CSD` to scan all source code files in the project (skip .git, node_modules, vendor, dist, build, lock files, .agentops). Detect these dangerous invisible Unicode character categories:
+
+1. **Zero-width / invisible chars**: U+200B–U+200F, U+2060–U+2064, U+FEFF (mid-file only)
+2. **Bidi overrides (Trojan Source)**: U+202A–U+202E, U+2066–U+2069
+3. **Variation selectors (Glassworm)**: U+FE00–U+FE0F
+4. **Tag characters**: U+E0001–U+E007F
+5. **Variation selectors supplement (Glassworm)**: U+E0100–U+E01EF
+
+The perl detection pattern is:
+```
+/[\x{200B}-\x{200F}\x{2060}-\x{2064}\x{FEFF}\x{202A}-\x{202E}\x{2066}-\x{2069}\x{FE00}-\x{FE0F}\x{E0001}-\x{E007F}\x{E0100}-\x{E01EF}]/
+```
+
+## Scan procedure
+
+1. Run a find + perl scan across the project to identify all affected files
+2. For each affected file, show:
+   - File path (relative to project root)
+   - Line numbers containing dangerous characters
+   - Character categories found (zero-width, bidi, variation selectors, tags)
+   - The visible context around the invisible characters (show 30 chars either side)
+   - A hex dump of the specific dangerous bytes found using: `perl -CSD -ne 'if (/[\x{200B}-\x{200F}\x{2060}-\x{2064}\x{FEFF}\x{202A}-\x{202E}\x{2066}-\x{2069}\x{FE00}-\x{FE0F}\x{E0001}-\x{E007F}\x{E0100}-\x{E01EF}]/) { while (/[\x{200B}-\x{200F}\x{2060}-\x{2064}\x{FEFF}\x{202A}-\x{202E}\x{2066}-\x{2069}\x{FE00}-\x{FE0F}\x{E0001}-\x{E007F}\x{E0100}-\x{E01EF}]/g) { printf "  U+%04X at col %d\n", ord($&), pos($_) } }'`
+3. Present a summary table
+
+## After scanning
+
+Present findings using this format:
+
+```
+## Unicode Security Scan Results
+
+**Status**: CLEAN | ⚠ FINDINGS
+**Files scanned**: N
+**Files flagged**: N
+
+### Findings
+
+| File | Line | Category | Codepoints |
+|------|------|----------|------------|
+| ... | ... | ... | ... |
+
+### Detail
+
+For each file, show the surrounding context and exact codepoints found.
+```
+
+If findings exist, ask the user: **"Would you like me to strip these dangerous characters? I will remove only the invisible Unicode — no visible content will change."**
+
+If the user confirms, use `perl -CSD -pi -e` to strip the characters in-place:
+```
+perl -CSD -pi -e 's/[\x{200B}-\x{200F}\x{2060}-\x{2064}\x{FEFF}\x{202A}-\x{202E}\x{2066}-\x{2069}\x{FE00}-\x{FE0F}\x{E0001}-\x{E007F}\x{E0100}-\x{E01EF}]//g'
+```
+
+After cleaning, re-run the scan to verify the files are now clean.

package/commands/verify.md

@@ -0,0 +1,41 @@
+---
+name: verify
+description: Verify task completion against plan, tests, and compliance gates
+---
+
+Verify that all work is complete and meets acceptance criteria.
+
+## Process
+
+1. **Read the plan** — load `tasks/todo.md` and identify the STAR Result criteria
+2. **Check completeness** — are all items marked `- [x]`?
+3. **Run tests** — execute the project's test suite
+4. **Check regressions** — verify existing functionality still works
+5. **Compliance gates:**
+   - Plan gate: plan exists if 3+ files modified
+   - Verification gate: all todo items checked
+   - Test gate: tests were run
+6. **Report results** — summarize what passed and what needs attention
+
+## Output Format
+
+```markdown
+## Verification Report
+
+### Completion: X/Y items checked
+- [x] Item 1
+- [ ] Item 2 (INCOMPLETE)
+
+### Tests: PASS/FAIL
+- Test suite: [result]
+- Regressions: [none found / details]
+
+### Compliance Gates
+| Gate | Status |
+|------|--------|
+| Plan | PASS   |
+| Verification | FAIL — 2 unchecked |
+| Test | PASS   |
+```
+
+Arguments: $ARGUMENTS

package/commands/workflow.md

@@ -0,0 +1,436 @@
+---
+name: workflow
+description: Workflow Mapper and Plan Executor - map workflows or execute structured plans
+---
+
+# Workflow Mapper
+
+You are an expert workflow mapping facilitator. You guide users through a structured process that supports two modes: **Workflow Mapping** (full 8-phase process producing Mermaid diagrams, structured YAML, narrative documentation, and AI-first automation recommendations) and **Plan Execution** (executing a structured plan from `tasks/todo.md`).
+
+## Mode Selection
+
+Before starting, determine the mode:
+
+1. If `$ARGUMENTS` contains "execute" or "run", or if the user explicitly asks to execute a plan, go to **Plan Execution Mode**.
+2. If `tasks/todo.md` exists and contains unchecked items (`- [ ]`), use `AskUserQuestion` to ask:
+   > "Found an existing plan in tasks/todo.md. What would you like to do?"
+   With options:
+   - **Execute the plan** — "Run through the tasks in tasks/todo.md"
+   - **Map a new workflow** — "I want to map out a workflow process"
+3. Otherwise, proceed to **Workflow Mapping Mode**.
+
+---
+
+# Plan Execution Mode
+
+Execute the plan defined in `tasks/todo.md`:
+
+1. Read `tasks/todo.md` and identify all unchecked items (`- [ ]`)
+2. For each item, in dependency order:
+   a. Mark it as in-progress (change `- [ ]` to `- [~]`)
+   b. Execute the task
+   c. Verify the result (run tests, check output)
+   d. Mark complete (change `- [~]` to `- [x]`)
+   e. Write a brief summary of what was done
+3. After all items complete, run full verification:
+   - Run test suite
+   - Check for regressions
+   - Verify against the STAR "Result" criteria in the plan
+4. Update `tasks/todo.md` with a review section at the bottom
+
+If any task fails, STOP and re-plan. Do not push forward on a broken foundation.
+
+---
+
+# Workflow Mapping Mode
+
+All workflow artifacts are stored in `./docs/workflows/{name}/` where `{name}` is either provided as `$ARGUMENTS` (kebab-cased) or auto-generated from the workflow description.
+
+## Storage
+
+You will create and maintain these files during the process:
+
+### Core Files
+1. `./docs/workflows/{name}/brief.md` — The workflow scope and objectives.
+2. `./docs/workflows/{name}/interrogation.md` — Running log of every question and answer, organized by phase and round.
+3. `./docs/workflows/{name}/state.yaml` — Session state for resumability.
+
+### Artifact Files (generated progressively)
+4. `./docs/workflows/{name}/workflow.yaml` — Structured workflow schema (actors, steps, decisions, automation scores).
+5. `./docs/workflows/{name}/diagrams/flowchart-as-is.md` — Mermaid flowchart of current-state process.
+6. `./docs/workflows/{name}/diagrams/swimlane-as-is.md` — Mermaid swimlane diagram of current-state process.
+7. `./docs/workflows/{name}/diagrams/state-as-is.md` — Mermaid state diagram of current-state process.
+8. `./docs/workflows/{name}/diagrams/flowchart-to-be.md` — Mermaid flowchart of future-state process.
+9. `./docs/workflows/{name}/diagrams/swimlane-to-be.md` — Mermaid swimlane diagram of future-state process.
+10. `./docs/workflows/{name}/diagrams/state-to-be.md` — Mermaid state diagram of future-state process.
+11. `./docs/workflows/{name}/narrative.md` — Full written narrative describing the workflow.
+12. `./docs/workflows/{name}/implementation.md` — Phased implementation plan with tool recommendations.
+
+Create the directory structure and `state.yaml` as soon as you have the workflow name.
+
+## Resume Detection
+
+Before starting, check if this is a resumption:
+
+1. If `$ARGUMENTS` is provided, check if `./docs/workflows/{arguments}/state.yaml` exists.
+2. If `state.yaml` exists: read it, summarize progress to the user, and use `AskUserQuestion` to ask:
+   > "Found an existing workflow mapping session. How would you like to proceed?"
+   With options:
+   - **Continue** — "Resume from where we left off (Phase {current_phase})."
+   - **Restart** — "Start fresh — discard previous progress."
+3. If `state.yaml` is missing but artifact files exist, infer the phase from file presence and offer to continue.
+4. If nothing exists, start fresh from Phase 0.
+
+When resuming, read all existing artifacts to rebuild context before continuing the interrupted phase.
+
+## State Tracking
+
+After completing each phase, update `state.yaml`:
+
+```yaml
+workflow_name: string
+slug: string
+current_phase: 0-8
+completed_phases: []
+started_at: datetime
+last_updated: datetime
+interrogation_source: string | null
+```
+
+Save state after every phase completion and after every Q&A round within a phase.
+
+## Phase 0: Discovery Integration
+
+Before mapping begins, check for prior interrogation work:
+
+1. Search `./docs/interrogation/` for directories whose brief matches the workflow topic.
+2. If a matching interrogation is found:
+   - Read the `brief.md`, `interrogation.md`, and `plan.md` from that interrogation.
+   - Extract key entities: actors, systems, triggers, data flows, constraints.
+   - Inform the user: *"Found existing interrogation at ./docs/interrogation/{match}/. Using this as context for the workflow mapping."*
+   - Record the path in `state.yaml` as `interrogation_source`.
+   - Use the extracted context to pre-populate questions and skip redundant discovery.
+3. If no matching interrogation is found:
+   - Inform the user: *"No prior interrogation found for this topic. Running discovery phase to gather context before workflow mapping."*
+   - Run the `/interrogate` command scoped to workflow mapping concerns. Wait for it to complete before proceeding.
+   - Once interrogation is complete, read its output and extract entities as in step 2.
+
+## Phase 1: Scope & Objectives
+
+**Goal:** Define what workflow we're mapping, why, and its boundaries.
+
+Use `AskUserQuestion` to ask questions covering:
+- What is the workflow being mapped? Describe it in a sentence.
+- Why are we mapping this workflow? What's the goal? (Efficiency? Compliance? Automation? All of the above?)
+- What triggers this workflow? (Event, schedule, request, condition?)
+- Where does the workflow start and end?
+- What does success look like for this workflow?
+- What is the goal of automating or improving this workflow?
+- Are there any known constraints? (Compliance, budget, tools, timeline?)
+
+Ask 4-6 questions per round. Push back on vague answers — demand specifics.
+
+**After this phase:**
+- Create `brief.md` with the scope and objectives.
+- Initialize `workflow.yaml` with:
+  ```yaml
+  workflow:
+    name: string
+    description: string
+    version: "1.0"
+    created: datetime
+    triggers: []
+    actors: []
+    steps: []
+    slas: []
+    exceptions: []
+    kpis: []
+  ```
+- Update `state.yaml` with `current_phase: 2, completed_phases: [1]`.
+
+## Phase 2: Stakeholder & Actor Mapping
+
+**Goal:** Identify every person, role, department, and system involved.
+
+Use `AskUserQuestion` to ask questions covering:
+- Who is involved in this workflow? List every role, person, or department.
+- What systems or tools are used at any point? (Software, platforms, databases, APIs, manual tools?)
+- Who initiates the workflow?
+- Who approves or signs off at decision points?
+- Who is affected by the workflow's output?
+- Are there external parties involved? (Vendors, customers, regulators?)
+- Who owns this workflow? Who is accountable for its performance?
+
+**After this phase:**
+- Populate the `actors` array in `workflow.yaml`:
+  ```yaml
+  actors:
+    - id: actor-slug
+      name: string
+      role: string
+      department: string
+      type: human | system | external
+  ```
+- Append Q&A to `interrogation.md`.
+- Update `state.yaml`.
+
+## Phase 3: Current-State (As-Is) Mapping
+
+**Goal:** Map every step of the workflow as it exists today.
+
+This is the most detailed phase. Walk through the workflow step by step.
+
+Use `AskUserQuestion` to walk through each step:
+- What happens first? Describe the very first action.
+- Who performs this step? Which system is used?
+- What data or information is needed as input?
+- What is produced as output?
+- How long does this step typically take?
+- What happens next? Are there any decision points?
+- If there's a decision, what are the possible paths?
+- Are there any handoffs between people or systems?
+- Continue until the user confirms we've reached the end of the workflow.
+
+For each step, ask about exceptions: *"What happens when this step fails or goes wrong?"*
+
+**After this phase:**
+- Populate the `steps` array in `workflow.yaml`:
+  ```yaml
+  steps:
+    - id: step-slug
+      name: string
+      description: string
+      actor: actor-id
+      system: string | null
+      inputs:
+        - name: string
+          source: string
+          type: string
+      outputs:
+        - name: string
+          destination: string
+          type: string
+      decisions:
+        - condition: string
+          true_branch: step-id
+          false_branch: step-id
+      duration: string
+      pain_points: []
+      automation_score: null
+      automation_recommendation: null
+  ```
+- Populate `exceptions` in `workflow.yaml`.
+- Generate **as-is diagrams** in `./docs/workflows/{name}/diagrams/`:
+  - `flowchart-as-is.md` — `graph TD` with steps, decisions, start/end nodes.
+  - `swimlane-as-is.md` — `graph TD` with `subgraph` blocks per actor/department.
+  - `state-as-is.md` — `stateDiagram-v2` with workflow states and transitions.
+- Update `state.yaml`.
+
+### Mermaid Diagram Guidelines
+- Keep node labels concise (max 5-6 words).
+- Use meaningful node IDs derived from step IDs.
+- Use decision diamonds (`{}`) for branching logic.
+- Color-code: green for start, red for end, yellow for decision points using `style` directives.
+- For swimlanes, group steps by actor using `subgraph "Actor Name"`.
+- Add edge labels for decision conditions.
+
+## Phase 4: Pain Point & Bottleneck Identification
+
+**Goal:** Identify where the current workflow breaks down, causes delays, or creates frustration.
+
+Use `AskUserQuestion` to ask about each major step/area:
+- Where are the biggest delays in this workflow?
+- Which steps are purely manual that feel like they shouldn't be?
+- Where do errors or mistakes happen most often?
+- Are there any bottlenecks — steps where work piles up waiting?
+- What's the most frustrating part of this workflow for the people involved?
+- Are there any compliance or audit risks in the current process?
+- Where is data re-entered, duplicated, or lost?
+- What steps have the most variance in how long they take?
+
+**After this phase:**
+- Add `pain_points` to each relevant step in `workflow.yaml`.
+- Update diagrams with pain point annotations (add `:::painPoint` class and style it red/orange).
+- Append Q&A to `interrogation.md`.
+- Update `state.yaml`.
+
+## Phase 5: Automation Opportunity Assessment
+
+**Goal:** Score each pain point and step for automation potential.
+
+For each pain point or manual step identified, use `AskUserQuestion` to discuss:
+- Could this step be automated? Fully or partially?
+- What would the impact be if this step were automated? (Time saved, errors reduced, cost saved?)
+- How feasible is automation here? (Technical complexity, data availability, integration difficulty?)
+- What are the risks of automating this step? (Quality, compliance, edge cases?)
+- Is there an AI/LLM approach that could handle this? (Document processing, decision support, data extraction, generation?)
+
+**After this phase:**
+- Add `automation_score` to each assessed step in `workflow.yaml`:
+  ```yaml
+  automation_score:
+    impact: 1-5      # 1=minimal, 5=transformative
+    feasibility: 1-5  # 1=very hard, 5=straightforward
+  ```
+- Present a summary matrix to the user: steps ranked by impact x feasibility.
+- Identify quick wins (high impact + high feasibility) vs. strategic investments (high impact + lower feasibility).
+- Append Q&A to `interrogation.md`.
+- Update `state.yaml`.
+
+## Phase 6: Future-State (To-Be) Design
+
+**Goal:** Design the improved workflow with automation and AI integration.
+
+Using the automation assessment, use `AskUserQuestion` to discuss:
+- For each high-scoring automation opportunity: what does the automated version look like?
+- Which steps are fully automated (no human)? Which are AI-augmented (human + AI)? Which stay manual?
+- What new steps are needed? (e.g., review/approval of AI output, exception handling?)
+- What's the human role in the new workflow? Where do humans add the most value?
+- How does data flow change in the new process?
+- What monitoring or oversight is needed for automated steps?
+
+**After this phase:**
+- Add a `future_state` section to `workflow.yaml` with the redesigned steps.
+- Generate **to-be diagrams** in `./docs/workflows/{name}/diagrams/`:
+  - `flowchart-to-be.md` — future-state flowchart.
+  - `swimlane-to-be.md` — future-state swimlane (new actors for AI/automation).
+  - `state-to-be.md` — future-state state diagram.
+- Color-code automated steps green, AI-augmented steps blue, manual steps default in to-be diagrams.
+- Append Q&A to `interrogation.md`.
+- Update `state.yaml`.
+
+## Phase 7: Tool & Stack Recommendations
+
+**Goal:** Recommend specific tools and technologies for each automation opportunity.
+
+First, use `AskUserQuestion` to confirm constraints:
+- What is the budget range for tooling? (Free/open-source only? SMB budget? Enterprise?)
+- What tools or platforms are already in use that we must integrate with?
+- Are there any compliance requirements that restrict tool choices? (SOC2, HIPAA, GDPR, on-prem only?)
+- What is the team's technical capability? (No-code preferred? Can handle custom development?)
+- Are there any tools already under consideration or ruled out?
+
+Then, for each automation opportunity, recommend tools using an **AI-first** approach:
+- **AI/LLM-powered solutions first** — Where an LLM, AI agent, or AI-powered tool could handle the task.
+- **No-code/low-code second** — Where platforms like Zapier, Make, n8n, Retool, or similar can automate without custom code.
+- **Custom development third** — Where a bespoke solution is warranted.
+
+For each recommendation, provide:
+- Tool/approach name
+- Why this fits (rationale tied to the specific step and pain point)
+- Estimated effort to implement
+- Pros and cons
+- Alternatives considered
+
+**After this phase:**
+- Add `automation_recommendation` to each step in `workflow.yaml`:
+  ```yaml
+  automation_recommendation:
+    approach: ai | no-code | custom | hybrid
+    tool: string
+    rationale: string
+    effort: string
+    alternatives: [string]
+  ```
+- Begin writing `implementation.md` with tool recommendations section.
+- Append Q&A to `interrogation.md`.
+- Update `state.yaml`.
+
+## Phase 8: Implementation Plan
+
+**Goal:** Create a phased rollout plan to get from as-is to to-be.
+
+Use `AskUserQuestion` to discuss:
+- What are the top priorities? What should be automated first?
+- Are there quick wins we can deliver in the first 1-2 weeks?
+- What are the dependencies between automation changes?
+- Who will own implementation of each phase?
+- What are the risks of the transition? How do we mitigate them?
+- How do we measure success? What KPIs should we track?
+- What does the rollback plan look like if something goes wrong?
+- What training or change management is needed?
+
+**After this phase:**
+- Complete `implementation.md` with:
+
+  ### Structure of implementation.md:
+  ```
+  # Implementation Plan: {workflow name}
+
+  ## Executive Summary
+  One-paragraph overview of the transformation.
+
+  ## Phase 1: Quick Wins (Week 1-2)
+  - What changes
+  - Tools needed
+  - Effort estimate
+  - Dependencies
+  - Risks & mitigations
+  - Success criteria
+
+  ## Phase 2: Medium-Term Improvements (Week 3-6)
+  [Same structure]
+
+  ## Phase 3: Strategic Automation (Month 2-3+)
+  [Same structure]
+
+  ## KPIs & Success Metrics
+  | Metric | Current | Target | How Measured |
+  |--------|---------|--------|--------------|
+
+  ## Risk Register
+  | Risk | Likelihood | Impact | Mitigation |
+  |------|-----------|--------|------------|
+
+  ## Change Management
+  - Training requirements
+  - Communication plan
+  - Stakeholder buy-in steps
+
+  ## Tool & Stack Summary
+  | Step | Current | Proposed | Approach |
+  |------|---------|----------|----------|
+  ```
+
+- Populate `slas` and `kpis` in `workflow.yaml`.
+- Generate the complete `narrative.md` with sections:
+  - Overview
+  - Actors & Stakeholders
+  - Current Process Flow
+  - Pain Points & Bottlenecks
+  - Automation Opportunities
+  - Future-State Design
+  - Tool Recommendations
+  - Implementation Roadmap
+- Update `state.yaml` with `current_phase: complete, completed_phases: [1,2,3,4,5,6,7,8]`.
+
+## Final Deliverable Summary
+
+Present the user with a summary of all generated artifacts:
+
+> **Workflow mapping complete.** Here's what was produced:
+>
+> - `brief.md` — Scope and objectives
+> - `workflow.yaml` — Structured workflow data (actors, steps, decisions, automation scores)
+> - `diagrams/` — 6 Mermaid diagrams (as-is and to-be: flowchart, swimlane, state)
+> - `narrative.md` — Full written narrative
+> - `implementation.md` — Phased implementation plan with tool recommendations
+> - `interrogation.md` — Complete Q&A log
+>
+> All files are in `./docs/workflows/{name}/`
+
+## Rules
+
+- Always use the `AskUserQuestion` tool for all user interaction — never just print questions as plain text.
+- Ask 3-6 questions per round. Batch questions well to keep the session moving.
+- Push back on vague answers. *"It depends"* is not a workflow step. *"Someone handles it"* is not an actor. Demand specifics.
+- After each Q&A round, append to `interrogation.md` with the phase number and round.
+- Update `state.yaml` after every phase and after significant progress within a phase.
+- Generate diagrams as soon as you have enough data (after Phase 3 for as-is, after Phase 6 for to-be).
+- AI-first recommendations must be substantive and specific — not generic lists. Tie each recommendation to the specific step, pain point, and context of this workflow.
+- Keep Mermaid diagrams clean and readable. Split complex workflows into multiple focused diagrams if needed.
+- The goal is a complete, actionable workflow mapping that a client could immediately use to plan their automation journey.
+- Target session completion in 60-90 minutes across all 8 phases.
+- All artifacts should be professional quality suitable for client presentation or screen-share demo.
+
+Arguments: $ARGUMENTS

package/hooks/ai-guardrails.sh

@@ -0,0 +1,114 @@
+#!/bin/bash
+set -uo pipefail
+# AI guardrails hook — detects common AI-assisted development pitfalls.
+# PostToolUse on Write/Edit. Non-blocking: additionalContext guidance only.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/feature-flags.sh"
+
+INPUT=$(cat) || exit 0
+
+# Check feature flag
+agentops_enterprise_enabled "ai_workflows" || exit 0
+
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+[ -z "$TOOL" ] && exit 0
+
+# Only process Write and Edit
+case "$TOOL" in
+  Write|Edit) ;;
+  *) exit 0 ;;
+esac
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE_PATH" ] && exit 0
+
+# Get content for Write operations
+CONTENT=""
+if [ "$TOOL" = "Write" ]; then
+  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null)
+fi
+
+FILENAME=$(basename "$FILE_PATH")
+EXTENSION="${FILENAME##*.}"
+DIR=$(dirname "$FILE_PATH")
+CWD=$(echo "$INPUT" | jq -r '.cwd // "."' 2>/dev/null)
+
+MESSAGES=()
+
+# ── Detector 1: Untested Generated Code ──────────────────────────────────────
+# When a new source file is created, check if a test file exists
+
+if [ "$TOOL" = "Write" ]; then
+  # Only check source code files
+  if echo "$EXTENSION" | grep -qE '^(ts|tsx|js|jsx)$'; then
+    # Skip test files, config files, type declarations
+    if ! echo "$FILENAME" | grep -qE '\.(test|spec|stories|config|d)\.(ts|tsx|js|jsx)$' && \
+       ! echo "$FILENAME" | grep -qE '^(index|env|next-env|jest|vitest|playwright|eslint|prettier)'; then
+      # Check if a test file exists
+      BASENAME="${FILENAME%.*}"
+      TEST_EXISTS=false
+      for TEST_SUFFIX in ".test.ts" ".test.tsx" ".spec.ts" ".spec.tsx" ".test.js" ".test.jsx"; do
+        if [ -f "${DIR}/${BASENAME}${TEST_SUFFIX}" ] || \
+           [ -f "${DIR}/__tests__/${BASENAME}${TEST_SUFFIX}" ]; then
+          TEST_EXISTS=true
+          break
+        fi
+      done
+      if [ "$TEST_EXISTS" = "false" ]; then
+        MESSAGES+=("New source file '${FILENAME}' has no corresponding test. Consider adding '${BASENAME}.test.${EXTENSION}'.")
+      fi
+    fi
+  fi
+fi
+
+# ── Detector 2: Generic Placeholders ─────────────────────────────────────────
+# Flag TODO, FIXME, placeholder values in written content
+
+if [ -n "$CONTENT" ]; then
+  PLACEHOLDER_COUNT=0
+
+  # Count generic placeholders
+  if echo "$CONTENT" | grep -qiE '\bTODO\b'; then
+    PLACEHOLDER_COUNT=$((PLACEHOLDER_COUNT + 1))
+  fi
+  if echo "$CONTENT" | grep -qiE '\bFIXME\b'; then
+    PLACEHOLDER_COUNT=$((PLACEHOLDER_COUNT + 1))
+  fi
+  if echo "$CONTENT" | grep -qiE '\blorem ipsum\b'; then
+    PLACEHOLDER_COUNT=$((PLACEHOLDER_COUNT + 1))
+  fi
+  if echo "$CONTENT" | grep -qE 'example\.com|your-api-key|changeme|password123|REPLACE_ME'; then
+    PLACEHOLDER_COUNT=$((PLACEHOLDER_COUNT + 1))
+  fi
+
+  if [ "$PLACEHOLDER_COUNT" -ge 2 ]; then
+    MESSAGES+=("This file contains ${PLACEHOLDER_COUNT} generic placeholders (TODO, FIXME, example values). Verify all values are project-specific before committing.")
+  fi
+fi
+
+# ── Detector 3: Hallucinated Dependencies (package.json) ────────────────────
+# When package.json is modified, flag for verification
+
+if [ "$FILENAME" = "package.json" ] && [ "$TOOL" = "Write" ]; then
+  MESSAGES+=("package.json was written. Verify all dependencies exist on npm before running install. Run 'npm info <package>' for any unfamiliar packages.")
+fi
+
+# ── Detector 4: Large Unstructured Files ─────────────────────────────────────
+# Flag files that are suspiciously large for a single write (may indicate copy-paste)
+
+if [ "$TOOL" = "Write" ] && [ -n "$CONTENT" ]; then
+  LINE_COUNT=$(echo "$CONTENT" | wc -l | tr -d ' ')
+  if [ "$LINE_COUNT" -gt 300 ]; then
+    MESSAGES+=("This file is ${LINE_COUNT} lines — unusually large for a single write. Consider breaking into smaller, focused modules.")
+  fi
+fi
+
+# ── Output ───────────────────────────────────────────────────────────────────
+
+if [ ${#MESSAGES[@]} -gt 0 ]; then
+  GUIDANCE=$(printf "AI Guardrails: %s" "$(IFS='; '; echo "${MESSAGES[*]}")")
+  jq -nc --arg msg "$GUIDANCE" '{additionalContext: $msg}'
+fi
+
+exit 0

package/hooks/audit-log.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/feature-flags.sh"
+
+INPUT=$(cat) || exit 0
+LOG_DIR="${CLAUDE_PROJECT_DIR:-.}/.agentops"
+LOG_FILE="$LOG_DIR/audit.jsonl"
+mkdir -p "$LOG_DIR" 2>/dev/null
+
+TS=$(date -u +%FT%TZ)
+SESSION=$(echo "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null) || SESSION="unknown"
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // "unknown"' 2>/dev/null) || EVENT="unknown"
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) || TOOL=""
+TOOL_INPUT=$(echo "$INPUT" | jq -r '.tool_input // {} | tostring | .[:500]' 2>/dev/null) || TOOL_INPUT="{}"
+
+# Redact secrets using canonical shared function
+TOOL_INPUT=$(echo "$TOOL_INPUT" | agentops_redact)
+
+jq -nc \
+  --arg ts "$TS" \
+  --arg session "$SESSION" \
+  --arg event "$EVENT" \
+  --arg tool "$TOOL" \
+  --arg input "$TOOL_INPUT" \
+  '{ts:$ts, session:$session, event:$event, tool:$tool, input:$input}' >> "$LOG_FILE" 2>/dev/null || true