kb-audit-query

name	kb-audit-query
description	Filter and summarise the cross-library KB audit log. Reports confidentiality events (attribution drops, synthesis aborts, dispatcher failures, no-evidence markers, cross-library promotions) over a date range, by event type, and by source handle.
disable-model-invocation	false
argument-hint	[--since <ISO-date>] [--until <ISO-date>] [--event-type <type>] [--source <handle>] [--summary]

Audit Log Query

Lightweight: This skill reads only index metadata (timestamps / audit log entries). Inline execution is acceptable.

Filter and summarise events from library/audit.log for the current project. The audit log is project-scope (lives in the project's library directory) and append-only; this skill is read-only.

Arguments

All optional:

• --since <ISO-date> — events at or after this timestamp (e.g., 2026-01-01T00:00:00Z)
• --until <ISO-date> — events at or before this timestamp
• --event-type <type> — one of: attribution_drop_retrieval, synthesis_aborted_attribution, synthesis_aborted_dispatcher_error, source_dispatch_failed, no_evidence_marker, cross_library_promotion
• --source <handle> — events for this library handle only
• --summary — emit count-by-type summary instead of detailed event list

Steps

Preflight: verify scripts package importable

python3 -c "
import sys, os, importlib.util
PLUGIN_ROOT = os.environ.get('CLAUDE_PLUGIN_ROOT', '')
SCRIPTS = os.path.join(PLUGIN_ROOT, 'scripts')
INIT = os.path.join(SCRIPTS, '__init__.py')
if os.path.isfile(INIT) and 'sdlc_knowledge_base_scripts' not in sys.modules:
    spec = importlib.util.spec_from_file_location(
        'sdlc_knowledge_base_scripts',
        INIT,
        submodule_search_locations=[SCRIPTS],
    )
    if spec and spec.loader:
        module = importlib.util.module_from_spec(spec)
        sys.modules['sdlc_knowledge_base_scripts'] = module
        spec.loader.exec_module(module)
try:
    import sdlc_knowledge_base_scripts.audit  # noqa: F401
    print('OK')
except ImportError:
    print('MISSING')
"

If output is MISSING, see kb-query for the install fallback. Otherwise prepend the importlib preamble to subsequent snippets.

1. Read and filter

python3 -c "
import sys, os, importlib.util, json
PLUGIN_ROOT = os.environ.get('CLAUDE_PLUGIN_ROOT', '')
SCRIPTS = os.path.join(PLUGIN_ROOT, 'scripts')
INIT = os.path.join(SCRIPTS, '__init__.py')
if os.path.isfile(INIT) and 'sdlc_knowledge_base_scripts' not in sys.modules:
    spec = importlib.util.spec_from_file_location(
        'sdlc_knowledge_base_scripts',
        INIT,
        submodule_search_locations=[SCRIPTS],
    )
    if spec and spec.loader:
        module = importlib.util.module_from_spec(spec)
        sys.modules['sdlc_knowledge_base_scripts'] = module
        spec.loader.exec_module(module)

from pathlib import Path
from sdlc_knowledge_base_scripts.audit import read_log

events = read_log(
    Path('library/audit.log'),
    event_type=<event-type or None>,
    source_handle=<source or None>,
    since=<since or None>,
    until=<until or None>,
)
print(json.dumps([e.__dict__ for e in events], indent=2))
"

Substitute the actual argument values into the read_log call. Quote string args; use Python None literal for unspecified ones.

2. Summarise (if --summary)

If --summary was specified, group results by event_type and count:

from collections import Counter
counts = Counter(e.event_type for e in events)
for event_type, count in counts.most_common():
    print(f"{event_type}: {count}")

3. Render results

Render either:

• Detailed view (default): one block per event with timestamp, event_type, source_handle, reason, detail summary
• Summary view (--summary): count by type, then "see kb-audit-query --event-type X for details"

Examples

Show all events in the last 90 days:

/sdlc-knowledge-base:kb-audit-query --since 2026-01-26T00:00:00Z

Count events by type for the last quarter:

/sdlc-knowledge-base:kb-audit-query --since 2026-01-01T00:00:00Z --summary

Investigate attribution drops on a specific source:

/sdlc-knowledge-base:kb-audit-query --event-type attribution_drop_retrieval --source corp-semi

What this skill does NOT do

• It does not modify the audit log (read-only)
• It does not query other projects' audit logs (project-scope)
• It does not export audit data to external systems (the JSON output can be redirected if needed)

Errors

• Audit log file missing — emit "No audit log at library/audit.log. Either no events have been logged yet, or this project has no library/ directory."
• Malformed log file — read_log skips malformed lines; the output may be smaller than expected