Observability

Two complementary layers

The harness observes execution at two levels. They answer different questions and use different stores.

Layer	Question	Store
Runtime trace	What did the agent do?	.sdlc/trace/events.jsonl
Cognitive trace	Where is the engineering process?	.sdlc/runs/{id}/manifest.yaml + trace UI

Conflating them loses either execution detail or procedural context.

---

Runtime trace

Observes the agent runtime directly:

• hook execution (sessionStart, beforeSubmitPrompt, afterFileEdit, stop)
• tool and MCP invocations
• shell commands
• file reads and edits
• token usage per turn
• subagent dispatch lifecycle
• agent thought spans (when exposed by runtime)

Collection: .cursor/hooks/hook_handler.py (or equivalent in other adapters) writes to .sdlc/trace/events.jsonl.

Visualization:

/api/events/stream

npx @jambu/ai-native-sdlc trace
# Dashboard URL injected at sessionStart

Runtime trace is execution telemetry — comparable to OpenTelemetry spans for agent actions.

Use cases:

• debug why an agent read a file or called a tool
• measure token consumption patterns
• audit hook firing order
• reconstruct agent action timeline

---

Cognitive trace

Observes the SDLC procedural process:

• run manifests and stage transitions
• ticket decomposition and wave ordering
• feature-flow stage completion per ticket
• gate pass/fail events
• handoff generation
• playbook provision events
• integration materialization steps
• evidence artifact paths

Primary artifacts:

.sdlc/runs/{run_id}/manifest.yaml    # orchestrator state machine
.sdlc/runs/ACTIVE                    # pointer to current run
.sdlc/handoffs/LATEST.md             # session continuity
.sdlc/evidence/{TICKET}/             # QA artifacts (worktree-local)
.sdlc/trace/events.jsonl             # cross-linked with runtime trace

Manifest updates flow through sdlc_e2e_manifest.py — preserving gate enforcement on every state change.

Cognitive trace is procedural observability — comparable to CI pipeline stage views, but for the full cognitive SDLC loop including decomposition, parallel ticket execution, and post-deploy reflection.

Use cases:

• audit why a run is blocked at execution stage
• verify all wave tickets passed feature-flow gates
• reconstruct orchestration lineage for a deployed product
• demonstrate end-to-end execution evidence

---

Trace correlation

Both layers share run_id, thread_id, and hook event metadata where available. A cognitive trace stage transition may correlate with a cluster of runtime trace spans (file edits, test runs, PR creation).

The trace UI presents the cognitive view. Runtime trace provides drill-down.

---

Token health

Context is an operational resource. /sdlc:token-health audits:

Metric	Meaning
Always-injected rules corpus	Baseline token cost per turn
Session hydration payload	sessionStart injection size
INDEX section density	Navigation overhead
Redundancy across rules/memories/DSL	Duplicate constraint expression

Remediation: bracket-notation compression via --fix. Goal is operational coherence across long executions — not cost minimization alone.

See Context Economics.

---

External observability integrations

When the observability lifecycle slot is materialized (Sentry, Datadog, etc.), production runtime events flow to external systems. This monorepo currently uses observability: none. Harness trace is separate from external observability:

System	Scope
Harness trace	Development-time procedural + runtime execution
External observability	Production application errors, analytics, session replay

Incident flow connects production signals back to the harness: GitHub issue → /fix-incident → incident-resolver agent → fix PR.

---

Evidence as observability artifact

QA evidence (screenshots, videos, manifests) is observability output of the cognitive trace:

• Generated in worktree: .sdlc/evidence/{TICKET}/
• Referenced in run manifest and feature-flow completion
• Uploaded to work-items provider post-merge (if policy enabled)
• Never committed to git

Evidence closes the loop between cognitive trace (“QA stage complete”) and auditable proof.

---

Operational consequences

Runtime trace without cognitive trace shows agent actions but not SDLC position.

Cognitive trace without runtime trace shows stage progress but not execution detail.

Both are required for procedural observability — auditable, navigable, replayable engineering workflows.

Trace is not input to agents by default. It is operator infrastructure. Injecting full trace into session context would recreate context explosion.