tkersey/seq

seq

Mission

Use deterministic local session and memory evidence to answer:

what happened
where it happened
what evidence supports it
what remains unknown

For skill/workflow analysis distinguish:

presence
decision influence
downstream outcome
workflow governance

These are not interchangeable.

Source boundary

Primary local sources:

~/.codex/sessions
~/.codex/memories

seq is local-corpus forensics, not product-wide telemetry. State the denominator and exclusion policy before counts.

Capability-first rule

For current or post-change audits, run:

seq --version
seq capabilities --format json
<target-command> --help

Use the installed lifted surface as source of truth. Do not recreate a newer native classifier with broad transcript searches when the installed binary is old.

For session JSONL forensics, require:

streaming_session_scanner_v1

This capability means aggregate session or corpus size is not a scanner limit; the shared scanner retains one protocol record at a time and each command owns its semantic fold. The per-record fail-closed guard remains separate. If the capability is absent, upgrade Seq rather than substituting broad jq, rg, or ad hoc whole-file scans. A genuinely bounded native query is acceptable only when that narrower denominator fully answers the question.

Routing ladder

Skill decisions and tuning

skill-decision-audit
skill-evidence
skill-success-rank
skill-audit
skill-cohort
workflow-audit
workflow-overlap

Historical decisions and replay

decision-capsule
historical_decisions dataset
turns
session-detail
artifact-search

Review/workflow audits

review-compiler-audit
adjudication-audit
goal-audit
routing-gap

Session/artifact forensics

artifact-search
plan-search
find-session
session-prompts
sessions
turns
session-detail
tail

Tools and orchestration

tool-lifecycle
tool-audit
tool-search
session-tooling
session-graph
orchestration-concurrency

Memory

memory-inventory
memory-provenance
memory-map
memory-history
memory-extension-audit

Generic

message-search
message-audit
token-usage
token-window
token-cost
query-diagnose
query

Use generic query when no lifted surface owns the relation. See command-routing.md.

Skill-decision audit

Use when asking:

How did a skill affect decisions?
Was its decision contract followed?
Was activation missed?
What should $tune change?

seq skill-decision-audit \
  --root ~/.codex/sessions \
  --skill <skill> \
  --skill-root codex/skills \
  --repo <repo> \
  --last 30d \
  --exclude-current \
  --mode tune-packet \
  --format json

Modes:

summary
episodes
misses
clauses
outcomes
matched-cohort
tune-packet
delta

Evidence levels:

structured SDR-v1 receipt
explicit assistant attribution
contract-aligned action
associated outcome
co-occurrence only

Do not collapse these into one “used” count. A receipt proves attribution structure, not a good outcome. skill-decision-audit uses the shared streaming scanner and retains only activation, decision, and outcome evidence needed by its output contract.

Skill presence

Use skill-evidence for one watched session and skill-audit --mode activation for cohorts. Preserve:

explicit user call
implicit assistant declaration
injected skill block
manual skill-file read
target-skill lens use
outcome evidence
raw mention

Presence does not prove influence. skill-evidence uses the same scanner in a single pass for normalized messages, skill mentions, tool reads, outcomes, and session identity.

Decision contracts and receipts

Decision-oriented skills may carry:

references/decision-contract.yaml
skill_decision_contract / SKDC-v1

Authority order:

1. explicit --contract;
2. target skill contract under --skill-root;
3. no clause-level judgment. Do not invent contract semantics in the CLI. Strongest decision attribution:

skill_decision_receipt:
  receipt_version: SDR-v1
  decision_id:
  skill:
  skill_contract_fingerprint:
  trigger_refs: []
  clause_refs: []
  question:
  alternatives_considered: []
  selected_route:
  rejected_routes: []
  expected_outcome:
  artifact_state:

Decision capsules

Use decision-capsule to freeze one visible decision for $retrace.

seq decision-capsule \
  --root ~/.codex/sessions \
  --session-id <id> \
  --turn-index <n> \
  --anchor all \
  --outcome-policy conservative \
  --format json

Prefer --decision-id when candidate normalization produced one. When candidates are empty:

inspect turns/session-detail
locate the visible route boundary
use exact one-based turn index

DCP owns visible historical context and structural temporal anchors. It does not infer hidden rationale.

Review-compiler provenance

Aggregate counts are discovery only. Before a session-level claim:

1. select the exact denominator.included_sessions row;
2. preserve the row’s session ID/path/protocol/classification;
3. cite evidence for true workflow, required, entered, closed, and compression;
4. distinguish present signals from absence-derived evidence;
5. classify workflow and closure provenance;
6. only then use the row as a $retrace source. For controller-backed review-closure workflows, evidence roles are:

controller_invocation
controller_event
controller_state
controller_receipt
explicit_workflow_declaration
artifact_under_repair
filename_or_path_mention
historical_reference
generic_prose

Only controller-grade evidence proves authoritative governance. A path containing only a workflow name is not activation. Generic completion, merge, or land evidence is not controller closure. When evidence is incidental, exclude the row from the true workflow denominator rather than deriving required/entered/closed state. Use ordered lifecycle evidence when available:

begin
basis
candidate
ablation
proof
permit
realization
apply
commit
push
close/abort

See review-compiler-provenance.md.

$retrace source selection

When $retrace investigates a workflow:

aggregate audit
-> included session row
-> provenance classification
-> SGG-v1
-> DCP-v2

Do not select a replay source from aggregate counts or fallback transcript similarity. Allowed source-governance states:

authoritative
declared_uncontrolled
incidental
ambiguous
absent

Only the first two permit workflow-specific replay, with limitations preserved. See retrace-decision-capsules.md.

Protocol separation

Do not evaluate one protocol with another protocol’s vocabulary. For review-closure workflow audits, distinguish:

legacy-cleanroom
controller-backed
kernel-compression
mixed
none

Report:

expected protocol
detected protocol
mismatch

Keep controller lifecycle evidence separate from kernel/compression/recomposition evidence.

Churn, Git delta, and semantic surface

Never collapse:

mutation churn
final Git delta
semantic surface

Mutation churn:

patch operations
gross insertions/deletions
rewrites

Final Git delta:

base/head
path classes
production/test/docs/generated/config

Semantic surface:

metric name/version/unit
dimensions
baseline/head
value

Unknown units must be labeled UNIT_UNRESOLVED.

Corpus reproducibility

For comparative audits preserve:

sessions root
seq version
scanner/index version
candidate files
files opened
session-id/path digest
time window
worker inclusion
current-session exclusion

A fixed time window is not an immutable corpus snapshot.

Worker attribution

Use linked workers only when requested or when the relevant decision occurred there. Preserve:

root session
worker session
parent edge
lane/receipt ID
declared skills
decision receipt
outcome

Do not merge unlinked worker sessions into the root denominator.

Causality discipline

Report:

explicit decision delta
contract-consistent but causality unproven
associated outcome only
co-occurrence only

Matched cohorts are observational. Fork/retrace evidence is experimental but remains separate from historical source fact.

Privacy and contamination

Default to sanitized refs and bounded excerpts. Detect:

injected skill blocks
current audit prompts
generated reports
quoted transcripts
memory summaries
examples

A schema example inside a skill body is not a historical decision. Private reasoning must not be exposed as report evidence.

Current patterns

seq artifact-search --contains "<term>" --surface messages --format jsonl
seq plan-search --repo <repo> --include-body --format jsonl
seq skill-audit --skill <skill> --mode activation --last 30d --exclude-current
seq tool-lifecycle --session-id <id> --format json
seq session-detail --session-id <id> --format markdown
seq review-compiler-audit --protocol auto --repo <repo> --format json
seq decision-capsule --session-id <id> --mode candidates --format table

Hard rules

• Use the narrowest lifted command.
• Prove the installed CLI surface first for post-change questions.
• Require streaming_session_scanner_v1 for session JSONL forensics; do not fall back to broad whole-file scans when it is absent.
• State denominators and exclusions.
• Preserve protocol and evidence provenance.
• Aggregate counts do not authorize session-level claims.
• Artifact/path mentions are not workflow activations.
• Generic delivery completion is not controller closure.
• Presence is not influence.
• Outcome association is not causality.
• Historical source fact is not replay consensus.
• Use generic query only for relations not owned by lifted commands.
• Report unresolved units, identities, and evidence gaps honestly.