attckdigital/smith/smith-audit

SpecKit Audit — Umbrella Command

Run a full-spectrum audit on a specific system or across all systems. This command orchestrates all sub-audits and produces a unified report.

Arguments: $ARGUMENTS

Vault Logging

Throughout this action, log significant events to the vault session log. Read the session log path from .smith/vault/.current-session. If the file is missing or the vault is not initialized, skip all logging silently.

Timestamps are UTC. HH:MM:SS comes from date -u +%H:%M:%S — never a local clock, never a time from memory. The append already runs through a shell, so read the clock in that same command (TS=$(date -u +%H:%M:%S)) and spend no extra tool call. Substitute the resulting value: an unexpanded $(...) reaching the log is a known regression and will not parse. Every hook-written stamp in this log is date -u, so a local-clock entry lands hours away from its neighbours and skews the workflow window hooks/workflow_summary_lib.py derives from them.

Append entries using this format:

### [HH:MM:SS] /smith-audit <event>
 
**User Request:**
> <verbatim user message that triggered this action>
 
**Synthesized Input:** <brief summary>
**Outcome:** <what happened>
**Findings:** <summary>
**Systems affected:** <system IDs>

Log at these points:

1. On invocation — which system(s) selected, full audit or specific sub-audit
2. After each sub-audit completes — sub-audit name, finding count by severity (critical/high/medium/low)
3. After unified report generated — path to report, total findings across all sub-audits
4. If action plan generated — count of remediation items by priority

Phase 0: Scheduled Mode & Marker Bootstrap

/smith-audit writes report files (specs/audits/*.md, per-system specs/system-XX-*/audits/*.md) but has no workflow-gate marker handling of its own — hooks/workflow-gate.sh denies any file-modifying tool call without an active-workflow marker present. This phase closes that gap for BOTH invocation modes: a non-interactive --scheduled dispatch from the scheduler, and a plain interactive /smith-audit run.

Parse --scheduled and its subset list

If $ARGUMENTS contains --scheduled, this is a scheduled-mode invocation. --scheduled is followed immediately by a bare comma-separated subset list, no further flag — e.g.:

/smith-audit --all --scheduled requirements,codequality,security,dependencies,workflow

SCHEDULED_MODE=""
SCHEDULED_SUBSETS=""
case "$ARGUMENTS" in
    *--scheduled*)
        SCHEDULED_MODE=1
        SCHEDULED_SUBSETS=$(echo "$ARGUMENTS" | sed -n 's/.*--scheduled[[:space:]]*\([^ ]*\).*/\1/p')
        ;;
esac

Extract the comma-separated list and validate each token against the 11 named sub-audit categories already enumerated in "Sub-Audit Orchestration" below. Reuses the same unquoted-tr-split idiom scheduler/smith-scheduler.sh already uses for its own comma-separated depends_on field, not a new parsing convention:

VALID_SUBSETS="requirements codequality performance security accessibility ux dependencies infrastructure workflow seo feature"
REFUSE_REASON=""
for tok in $(echo "$SCHEDULED_SUBSETS" | tr ',' '\n' | tr -d ' '); do
    [ -z "$tok" ] && continue
    case " $VALID_SUBSETS " in
        *" $tok "*) ;;
        *) REFUSE_REASON="unrecognized subset: $tok" ;;
    esac
    if [ "$tok" = "feature" ]; then
        REFUSE_REASON="feature sub-audit is not permitted in --scheduled mode (requires interactive interview)"
    fi
done

Refusal checks — BEFORE any marker creation or sub-audit dispatch

Three refusal conditions, checked in this order, all before the marker bootstrap below runs:

1. Unrecognized token. Any subset token not in the 11-category vocabulary above is a refused invocation. FR-9.
2. `feature` anywhere in the list. feature is NEVER permitted in --scheduled mode, regardless of configuration — it has a user interview phase with no non-interactive substitute. This is unconditional; no scheduled_audits config field can permit it. FR-10, US-4.
3. Missing `--all` / system identifier. A --scheduled invocation whose $ARGUMENTS, once --scheduled and its subset list are set aside, resolves to neither --all nor a system identifier (see "System Selection" below) is refused rather than falling through to the empty-args interactive prompt — this is the one prompt branch a non-interactive claude -p invocation could otherwise hang on indefinitely. FR-8.

Any of these three refusals is a logged failure (to the vault session log per "Vault Logging" above, and to stdout/stderr so the scheduler's own dispatch capture sees it) with a clear reason — no active-workflow marker is created, no report file is written, and /smith-audit returns without further action. All three checks run before marker bootstrap, so none of them requires a clear-active-workflow.sh call — there is nothing yet to clear.

Marker bootstrap — BOTH --scheduled and plain interactive invocations

Once the refusal checks above pass (or don't apply — a plain interactive invocation triggers none of them), bootstrap a maintenance active-workflow marker before writing any report file. This applies unconditionally to every /smith-audit invocation, not only --scheduled ones — the exact same create-active-workflow.sh/clear-active-workflow.sh code path already has to exist for --scheduled, so gating it behind --scheduled would leave interactive runs relying on whatever marker happens to already be active from an unrelated workflow, or failing closed with no marker at all, for zero additional implementation cost. This mirrors skills/smith-update/SKILL.md's own Phase 0 pattern verbatim:

TS=$(date -u +"%Y-%m-%dT%H-%M-%SZ")
if [ -n "$SCHEDULED_MODE" ]; then
    LABEL="scheduled-audit-${TS}"
else
    LABEL="audit-${TS}"
fi
PROJECT_DIR=$(pwd)
if [ -d "$PROJECT_DIR/.smith" ]; then
    ~/.smith/scripts/create-active-workflow.sh \
      --branch "$LABEL" --workflow maintenance --slug "$LABEL" \
      --worktree "$PROJECT_DIR"
    # (Falls back to scripts/create-active-workflow.sh in repo-dev layouts.)
    MARKER_PATH="$PROJECT_DIR/.smith/vault/active-workflows/${LABEL}.yaml"
fi

maintenance is the existing --workflow allowlist entry on scripts/create-active-workflow.sh — reused unchanged, no new enum value added. The --branch "$LABEL" value is a synthetic label naming no real git ref — /smith-audit never creates a worktree or branch; it exists solely to satisfy create-active-workflow.sh's required --branch argument and to give the marker file a unique, sortable name. FR-11, FR-18, A-2.

Clearing the marker — EVERY exit path

Because /smith-audit's orchestration spans multiple separately-invoked bash blocks and Claude tool calls (subagent dispatch, report writes), not one OS process, a single shell trap ... EXIT cannot span the whole flow — the same constraint skills/smith-update/SKILL.md already solves the identical way. Clear the marker via the shipped helper at every documented exit point below, mirroring smith-update's own per-early-return "cleanup marker, exit cleanly" comment pattern:

[ -n "${MARKER_PATH:-}" ] && [ -f "$MARKER_PATH" ] && \
    "$PROJECT_DIR/.specify/scripts/bash/clear-active-workflow.sh" "$LABEL" 2>/dev/null || true

Documented exit points requiring this call:

• Normal completion — call clear-active-workflow.sh "$LABEL" after the report (and, for --scheduled, the Drift block, rolling-log append, and state-file write — see "Report Generation" below) is fully written.
• A sub-audit crash — call clear-active-workflow.sh "$LABEL" immediately, log the failure, and return without a partial or incomplete report.
• A report/drift/log-write failure — call clear-active-workflow.sh "$LABEL" immediately, log the failure, and return.
• Pre-marker refusals need no clearing — the three refusal checks above occur before marker creation, so there is nothing to clear on that path.

A lingering marker is never an acceptable outcome — leaving one active silently disables the workflow-gate for every other file-modifying tool call in that project until hooks/active-workflow-janitor.sh's 1-hour-minimum-grace-period sweep eventually removes it. FR-9, FR-10, FR-12, US-3.

System Selection

If $ARGUMENTS contains --all:

• Run audits across ALL systems (full-spectrum mode)
• Reports go to individual system folders + a global summary at specs/audits/<date>-full-spectrum.md
• Use subagents per system to manage context

If $ARGUMENTS contains a system identifier (e.g., system-15, command-center, 014):

• Match it to the correct system spec directory
• Run all sub-audits on that system only

If $ARGUMENTS is empty:

• Note: a --scheduled invocation with no --all/system identifier never reaches this branch — Phase 0 above refuses it before System Selection runs, so this interactive prompt only ever fires for a plain interactive invocation.
• Scan for all system spec directories:

``bash ls -d specs/system-*/spec.md specs/[0-9]*/spec.md 2>/dev/null ``

• Present a numbered list to the user:

``` Which system would you like to audit?

1. system-00-config-isolation
2. system-01-core-infrastructure
3. system-03-email-archive-contact-graph

...

1. system-15-command-center

Or type --all for a full-spectrum audit across all systems. ```

• Wait for user selection before proceeding.

System-to-Code Mapping

Each system audit needs to know which code directories and files belong to it. Determine this by:

1. Reading the system's `spec.md` — look for file paths, service names, directory references
2. Known mappings (from CLAUDE.md Architecture section):

• system-00-config-isolation → docker-compose.yml, .env, scripts/
• system-01-core-infrastructure → docker-compose.yml, scripts/, infrastructure configs
• system-02-ai-models-layer → Ollama configs, model files
• system-03-email-archive-contact-graph → services/email-pipeline/, Qdrant collections, Neo4j schemas
• system-04-personal-voice → services/voice-training/
• system-05-communication-triage → services/communication-triage/, services/command-center/routes/triage.js
• system-06-communication-learning-loop → N8N workflows, training pipeline
• system-09-meeting-intelligence → meeting-related services
• system-10-social-listening → social signal services
• system-13-trend-intelligence → trend analysis services
• system-15-command-center → services/command-center/ (full frontend + Express backend)

1. Fallback: Grep the codebase for references to the system name/number

Documentation Sources

Every sub-audit MUST also review these documentation sources for the target system:

1. Session logs: docs/sessions/*.md — filter for sessions tagged with the system name/number. Check if decisions made in sessions are reflected in the current code.
2. System questions: specs/system-XX-*/questions.md — check for unanswered questions (blank **Answer:** fields). Flag as unresolved decisions.
3. Pre-implementation questions: specs/questions/*.md — check for questions related to the target system. Verify answered questions were implemented.
4. Feature specs: specs/[0-9]*-*/spec.md — check for feature specs that reference the target system. Verify those features are implemented.

Ledger Context (Optional)

If .smith/vault/ledger/ exists and contains non-empty files, load relevant Ledger sections to inform this audit. If the directory is missing, empty, or unreadable, skip silently — the Ledger is purely additive and never required.