Roo-Code/docs/testing-traceability.md

Testing the AI-Native Git Layer (Traceability)

How to test the semantic tracking ledger and agent_trace.jsonl in the terminal.

Prerequisites

• From the repo root: .orchestration/active_intents.yaml must exist (it does in this repo).
• Node/pnpm: pnpm install already run.

1. Run the full hook test suite

Runs content-hash, context-loader, scope, pre-hook, post-hook, and middleware:

pnpm test:hooks

Or without pnpm:

npx tsx scripts/test-hooks.ts

2. Run the trace scenario (one flow end-to-end)

Simulates: select_active_intent → write_to_file (pre-hook) → post-hook appends to agent_trace.jsonl, then prints the last trace entry.

pnpm test:trace-scenario

Or:

npx tsx scripts/test-trace-scenario.ts

You should see:

• Intent INT-001 loaded
• write_to_file allowed (in scope)
• A new line in .orchestration/agent_trace.jsonl
• The last entry printed with intent_id, content_hash, and REQ-ID in related

3. Inspect the trace file yourself

After running the scenario (or after real agent writes):

# Last 3 trace entries (pretty-printed)
tail -n 3 .orchestration/agent_trace.jsonl | while read line; do echo "$line" | jq .; done

# Or just the raw last line
tail -n 1 .orchestration/agent_trace.jsonl

4. Create your own scenario

Copy scripts/test-trace-scenario.ts and change:

• intent_id (must exist in .orchestration/active_intents.yaml)
• path (must be under that intent’s owned_scope, e.g. src/api/**)
• content and mutation_class (AST_REFACTOR | INTENT_EVOLUTION | NEW_FILE)

Then run:

pnpm exec tsx scripts/your-scenario.ts

Summary

Command	What it does
pnpm test:hooks	All hook unit-style checks (content-hash, pre/post-hook, middleware).
pnpm test:trace-scenario	One full flow: select intent → write → append trace → print last entry.

Both run in the terminal with no VS Code or extension required.