audit

name	audit
description	Run a diff-scoped code audit for architecture, dead code, and test quality. Uses the change from main to focus feature reviews; request a repository audit for whole-codebase discovery.
allowed-tools	*

Audit

Run a diff-scoped code audit. Execute checks and report results by severity.

Reviewer class: class-2 — independent observation: every check confirms an observable fact, so no cross-model reviewer applies. Judging whether the architecture is sound is not audit's job — that lives in the Architecture Review Gate (ARCHITECTURE.md) and quality-review.

Invocation log

This skill is required before marking a feature ticket done. The line below appends a current-run entry to skill-invocations.log under the project namespace root (.project/, or legacy .safeword-project/ where that exists) so the done-gate hook can verify /audit was actually invoked. Claude Code expands the ! line automatically and passes ${CLAUDE_SESSION_ID} when available. The helper also resolves Claude remote-container ids from the runtime environment, and on Cursor and Codex the pre-shell hook (beforeShellExecution / PreToolUse) bridges the session id to the helper — so on all three runtimes the fallback runs without hand-picking an id. Hand-writing audit results cannot produce this feature-gate proof.

!PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}" && bun "$PROJECT_DIR/.safeword/hooks/record-skill-invocation.ts" "$PROJECT_DIR" audit "${CLAUDE_SESSION_ID:-}" || echo "[skill-invocation-log] FAILED - no current-run proof logged"

If no [skill-invocation-log] audit ✓ line appears above, run this fallback before continuing:

PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2> /dev/null || pwd)}"
bun "$PROJECT_DIR/.safeword/hooks/record-skill-invocation.ts" "$PROJECT_DIR" audit "${CLAUDE_SESSION_ID:-}"

If the automatic line or fallback prints [skill-invocation-log] FAILED, prints no run identity, or still does not print audit ✓: a feature ticket can't be marked done without this proof — don't hand-write audit results as a substitute. Report the failure to the user (most likely cause: inline shell execution was denied, the runtime did not expose a usable run identity, or Bun could not run the installed helper) and ask them to resolve it before re-invoking /audit.

For task, patch, or no-ticket work, this proof isn't required — note it's missing and continue.

Scope

Default to the current working tree's change from origin/main, falling back to local main. The shared scope helper prints its exact merge-base SHA and changed files. Treat that printed list as the audit boundary for every review below.

• Review changed source, tests, agent configuration, documentation, and learning files; follow direct references from them when a missing reference could make the change invalid.
• Deleted and type-changed paths are evidence for broken-reference review, never analyzer inputs. The helper prints them under Reference review scope.
• Whole-workspace Knip, repository clone totals, and dependency-freshness discovery are intentionally skipped in this mode because their pre-existing findings are noise for a feature diff.

Run a repository audit only when the user explicitly asks for a full, repository-wide, or baseline audit, or when neither origin/main nor main exists. In that mode retain the prior whole-project checks and report the mode prominently. Do not silently widen a Git-aware diff audit.

For an explicit repository audit, set AUDIT_SCOPE_REQUEST=repository in the environment of every executable audit block below. That is what widens code, agent configuration, learnings, tests, documentation, and domain docs together. Leave the variable unset for the default diff audit; do not edit the blocks' commands.

Instructions

1. Code Quality Checks

Run the block below verbatim, as ONE bash invocation. Do not extract or paraphrase individual commands — the manifest gates, package-manager routing, and tool-absence messages are load-bearing, and a hand-rolled subset silently skips whole check families.

# Ensure we're in the project root regardless of prior CWD state, then load the
# same scope contract every executable audit block uses.
PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2> /dev/null || pwd)}"
cd "$PROJECT_DIR" || exit 1
source "$PROJECT_DIR/.safeword/hooks/lib/audit-scope.sh"
audit_scope_initialize "$PROJECT_DIR"
audit_scope_print

AUDIT_HAS_JS_CHANGE=false
AUDIT_HAS_PYTHON_CHANGE=false
AUDIT_HAS_GO_CHANGE=false
AUDIT_HAS_RUST_CHANGE=false
if [ "$AUDIT_SCOPE_MODE" = "diff" ]; then
  audit_scope_has_path_matching '(^|/)(package\.json|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|knip(\.config)?\.(json|jsonc|js|ts)|\.knip\.jsonc?|\.dependency-cruiser\.(cjs|js|mjs|json))$|\.(cjs|cts|js|jsx|mjs|mts|ts|tsx|vue|svelte)$' && AUDIT_HAS_JS_CHANGE=true
  audit_scope_has_path_matching '(^|/)(pyproject\.toml|requirements\.txt|setup\.py|setup\.cfg|Pipfile|uv\.lock|poetry\.lock)$|\.py$' && AUDIT_HAS_PYTHON_CHANGE=true
  audit_scope_has_path_matching '(^|/)(go\.mod|go\.sum)$|\.go$' && AUDIT_HAS_GO_CHANGE=true
  audit_scope_has_path_matching '(^|/)(Cargo\.toml|Cargo\.lock)$|\.rs$' && AUDIT_HAS_RUST_CHANGE=true
fi
AUDIT_HAS_CODE_OR_MANIFEST_CHANGE=false
if [ "$AUDIT_SCOPE_MODE" = "repository" ] || [ "$AUDIT_HAS_JS_CHANGE" = true ] || [ "" =  ] || [  =  ] || [  =  ]; 
  AUDIT_HAS_CODE_OR_MANIFEST_CHANGE=









() {
   [ -f bun.lock ] || [ -f bun.lockb ]; 
     bun
    
  
   [ -f pnpm-lock.yaml ]; 
     pnpm
    
  
   [ -f yarn.lock ]; 
     yarn
    
  
   [ -f package-lock.json ]; 
     npm
    
  
  node -e 
}




() {
  find . \
    - d \( -name .git -o -name node_modules -o -name .venv -o -name venv -o -name vendor -o -name target \) -prune -o \
    
}

() {
  find_audit_files \
    - f \(  \) - 2> /dev/null \
    |  IFS=  -r manifest;   ;  \
    | LC_ALL=C  -u
}

PYTHON_PROJECT_DIRS=
GO_MODULE_DIRS=
RUST_CRATE_DIRS=




 [  =  ]; 
   [  =  ]; 
    PYTHON_PROJECT_DIRS=
  
    PYTHON_PROJECT_DIRS=
  
   [  =  ]; 
    GO_MODULE_DIRS=
  
    GO_MODULE_DIRS=
  
   [  =  ]; 
    RUST_CRATE_DIRS=
  
    RUST_CRATE_DIRS=
  




() {
   IFS=  -r project_dir; 
    [ -n  ] || 
      
      ./apps/*/*)    ;;
      ./jobs/*)    ;;
      *)    ;;
    
   | LC_ALL=C  -u
}

PYTHON_AUDIT_DIRS=





() {
  find_audit_files \
    - f \( -name knip.json -o -name knip.jsonc -o -name .knip.json -o -name .knip.jsonc -o -name knip.ts -o -name knip.js -o -name knip.config.ts -o -name knip.config.js \) - 2> /dev/null \
    | LC_ALL=C 
}

() {
   config  knip.json knip.jsonc .knip.json .knip.jsonc knip.ts knip.js knip.config.ts knip.config.js; 
    [ -f  ] && {
        
      
    }
  
}

KNIP_CONFIG_FILES=

() {
  root_config=
   [ -n  ]; 
     
    bunx knip --config  2>&1 || 
   [ -n  ]; 
     IFS=  -r config_path; 
      [ -n  ] || 
      config_dir=
      config_name=
       
      (  && bunx knip --config  2>&1 || )
     << 
  
     
    bunx knip 2>&1 || 
  
}

() {
  YARN_VERSION=
    
    0.* | 1.*)
       
      yarn outdated 2>&1 || 
      ;;
    )
       
      ;;
    *)
       
      ;;
  
}

() {
  project_dir=
  (
      ||  0
     [ -f uv.lock ]; 
      uv pip list --outdated 2>&1 || 
     [ -f poetry.lock ] || grep -q  pyproject.toml 2> /dev/null; 
      poetry show --outdated 2>&1 || 
     [ -f Pipfile ]; 
      pipenv update --outdated 2>&1 || 
    
      python -m pip list --outdated 2>&1 || pip list --outdated 2>&1 || 
    
  )
}

 [  !=  ]; 
   

  [ -n  ] ||  
  [ -n  ] ||  
  [ -n  ] ||  

  
  
  

  
  
  
  
   [  =  ] || [  =  ]; 
     [ -x node_modules/.bin/safeword ]; 
      SW=
     [ -f packages/cli/src/cli.ts ]; 
      SW=
     SW=; 
     project sync-config --check 2>&1 ||  

    
    
    
    ([ -n  ] || [ -n  ] || [ -n  ]) &&  
  

  
  
  

  
  DEPCRUISE_CONFIG=
  [ -f .dependency-cruiser.cjs ] && DEPCRUISE_CONFIG=
  [ -f .dependency-cruiser.js ] && DEPCRUISE_CONFIG=
   [ -n  ] && { [  =  ] || [  =  ]; }; 
     [  =  ]; 
      bunx depcruise --output-type err --config  --affected  . 2>&1 || 
    
      bunx depcruise --output-type err --config  . 2>&1 || 
    
  

  
  
  
  
  
   [ -n  ]; 
     IFS=  -r project_dir; 
      [ -n  ] || 
      (
          ||  0
         [ -f .importlinter ] || grep -q  setup.cfg 2> /dev/null || grep -q  pyproject.toml 2> /dev/null; 
            -v lint-imports > /dev/null 2>&1; 
            lint-imports 2>&1 || 
          
             
          
        
           
        
      )
     << 
  

  
  
  
  
  
  
   [ -n  ]; 
     IFS=  -r module_dir; 
      [ -n  ] &&  
     << 
  

  
  
  
  
  
  
   [ -n  ]; 
     IFS=  -r crate_dir; 
      [ -n  ] &&  
     << 
  

  
  
  

  
  
  
  
  
   [  =  ]; 
    ([ -f package.json ] || [ -n  ]) && run_knip_check
   [  =  ]; 
     
  

  
  
  
   [ -n  ]; 
      -v deadcode > /dev/null 2>&1; 
       IFS=  -r project_dir; 
        [ -n  ] || 
         
        (  && deadcode . 2>&1 || )
       << 
    
       
    
  

  
   [ -n  ]; 
      -v golangci-lint > /dev/null 2>&1; 
       IFS=  -r module_dir; 
        [ -n  ] || 
         
        (  && golangci-lint run -- unused 2>&1 || )
       << 
    
       
    
  

  
  
  
  
   [ -n  ]; 
      -v cargo-clippy > /dev/null 2>&1; 
       IFS=  -r crate_dir; 
        [ -n  ] || 
         
        (  && cargo clippy --all-targets --all-features -- -D warnings 2>&1 || )
       << 
    
       
    
  

  
  
  

  
  
  
  
  
  
  
  
   [  =  ]; 
    bunx jscpd . --min-lines 10 --reporters console --ignore  2>&1 || 
   [  =  ]; 
     
  

  
  
  

  
  
  
   [  =  ]; 
    
    [ -f package.json ] && {
        
        bun) bun outdated 2>&1 ||  ;;
        npm) npm outdated 2>&1 ||  ;;
        pnpm) pnpm outdated 2>&1 ||  ;;
        yarn) run_yarn_outdated_check ;;
        *)   ;;
      
    } ||  

    
     [ -n  ]; 
       IFS=  -r project_dir; 
        [ -n  ] || 
         
        run_python_outdated_check 
       << 
    

    
     [ -n  ]; 
       IFS=  -r module_dir; 
        [ -n  ] || 
         
        (  && (go list -m -u all 2>&1 | grep  ||  ))
       << 
    

    
     [ -n  ]; 
       IFS=  -r crate_dir; 
        [ -n  ] || 
         
        (  && cargo update --dry-run 2>&1 || )
       << 
    
   [  =  ]; 
     
  

Outdated Package Triage (repository audits only)

After running the outdated checks above, classify each outdated package using this matrix:

Dep Type	Bump	Risk	Action
dev	patch	Low	Safe to update now
dev	minor	Low	Safe to update now
prod	patch	Low	Safe to update — run tests after
prod	minor	Medium	Review changelog, then update
dev	major	Medium	Research breaking changes, may need config updates
prod	major	High	Defer to dedicated task — investigate migration path
any	0.x minor	Medium	Treat as major (semver allows breaking changes in 0.x)

Present results as a structured table:

| Package | Current | Latest | Type | Bump | Risk |
|---------|---------|--------|------|------|------|
| knip | 5.86.0 | 5.88.1 | dev | patch | Low |
| eslint | 9.39.4 | 10.0.3 | dev | major | High |

Then give a verdict per risk tier:

• Low risk: "Safe to update now — dev-only tools, patch/minor bumps"
• Medium risk: "Review changelogs before updating" (list specific packages)
• High risk: "Defer to dedicated task — major version bumps need migration research" (list specific packages)

If all packages are up to date, report: ✅ All packages up to date

Knip Configuration Hints (W005, repository audits only)

Check the knip output above for "Configuration hints" lines. If knip reports configuration hints (unused entries in ignoreDependencies, ignoreBinaries, ignoreUnresolved, or ignoreWorkspaces), flag each as:

- [W005] Stale config: `knip.json` — `{entry}` can be removed from {list}

These mean the ignore override no longer matches anything knip would flag — the suppression is dead config. Cleaning them up reduces noise for future readers.

If no configuration hints are found, skip this section.

Findings triage — baselines, not re-litigation

• Knip: knip.json's ignore lists ARE the accepted-false-positive baseline — persist confirmed FPs there instead of re-triaging them every run (W005 flags any entry that goes stale, so the baseline self-cleans). Report only findings not already covered by the ignore lists.
• jscpd: record the clone count in the audit summary with its scope named next to the count — e.g. Clones: 416 (8.9%) [repo minus .safeword,.project] — and compare against the previous audit's recorded count at the SAME scope (last verify.md/audit record, if any). A count whose scope differs from the prior record is a new baseline, not a delta (issue #825: unscoped counts spanning 84→594 proved incomparable). Deltas are the findings; a flat count is the baseline, not a finding. Never report a raw total as if it were new.

2. Agent Config Checks

In a diff audit, find and check changed agent configuration files (excluding .safeword/) and direct references from them. In a repository audit, check every matching configuration file.

Files to check:

• CLAUDE.md, AGENTS.md (root and subdirectories)
• .claude/CLAUDE.md (root and subdirectories)
• .cursor/rules/*.mdc or .cursor/rules/*/ (root and subdirectories)
• .cursorrules (legacy)

For each changed config file, check:

Check	Criteria	Severity
Size limit	CLAUDE.md/AGENTS.md: ~150-200 instructions; Cursor rules: 500 lines	warn
Structure	Has WHAT/WHY/HOW sections	warn
Dead refs	All referenced files/paths exist (skip URLs starting with http)	error
Staleness	Do not report date-only staleness in a diff audit; use a repository audit	n/a

3. Learning Files Check

Changed project learnings in the resolved namespace root's learnings/*.md must have a Covers: line on line 3 — the auto-generated INDEX.md is built from these lines, and files without them don't appear in the index. In a repository audit, check every learning as before.

PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2> /dev/null || pwd)}"
source "$PROJECT_DIR/.safeword/hooks/lib/audit-scope.sh"
audit_scope_initialize "$PROJECT_DIR"
NS_ROOT="$(bun "$PROJECT_DIR/.safeword/hooks/resolve-namespace-root.ts" "$PROJECT_DIR")"

learning_is_in_audit_scope() {
  [ "$AUDIT_SCOPE_MODE" = "repository" ] && return 0
  learning_path="${1#"$PROJECT_DIR"/}"
  audit_scope_path_changed "$learning_path"
}

if [ -d "$NS_ROOT/learnings" ]; then
  for f in "$NS_ROOT"/learnings/*.md; do
    [ -e "$f" ] || continue
    [ "$(basename "$f")" = "INDEX.md" ] && continue
    learning_is_in_audit_scope "$f" || continue
    line3=$(sed -n '3p' "$f")
    case "$line3" in
      Covers:*) ;;
      *) echo  ;;
    
  

Flag each non-conforming file as:

- [W006] Learning file missing Covers: — `{path}` (absent from INDEX.md)

If all files conform, skip this section.

4. Test Quality Review

Review changed test files for quality issues, plus a changed source file's co-located test when present. Check them against the iron laws and anti-patterns in .claude/skills/testing/SKILL.md. A repository audit may use the former project-wide sample.

Find test files:

# Start with test files named in the printed audit scope. For a changed
# `src/foo.ts`, also inspect `src/foo.test.ts` / `src/foo.spec.ts` when present.
# Repository audit fallback (common patterns):
find . -name "*.test.*" -o -name "*.spec.*" -o -name "*_test.*" | grep -v node_modules | grep -v dist | head -20

For each sampled test file, check:

The criteria are language-neutral; the parenthetical idioms are examples — map them to the project's test framework (Jest/Vitest, pytest, Go testing, Rust #[test], …).

Check	Criteria	Severity
Meaningful assertions	Every test asserts specific values/behavior — not bare existence/truthiness/no-error checks (toBeTruthy, bare assert result, only err == nil, assert!(x.is_ok()))	error
Behavior over implementation	Tests assert observable outcomes, not internal state or mock call args	error
Independence	No test depends on another test's side effects; fresh state per test	error
No arbitrary timeouts	No sleeps or hardcoded delays (sleep, waitForTimeout, time.Sleep, thread::sleep)	error
Edge case coverage	Tests include error paths and boundary cases, not just happy path	error
No duplicate tests	Similar tests use parameterized/table-driven patterns (it.each, pytest.mark.parametrize, Go table-driven subtests, rstest)	error
Test naming	Names describe behavior, not implementation ("returns 401 when..." not "works correctly")	error

Report format:

Test Quality:
- Files reviewed: N
- Issues found: N (E errors)
- [E] file.test.ts:42 — Weak assertion: `expect(result).toBeTruthy()` → assert specific value
- [E] file.test.ts:15 — Shared mutable state: `user` modified across tests
- [E] file.test.ts — Happy-path only: no error case tests for `processOrder()`

5. Project Documentation Checks

Docs source inventory:

• Read .safeword/config.json first. If top-level docs.sources exists, treat it as the authoritative documentation inventory:
  • { "type": "local", "path": "..." } — inspect that file or directory. Relative paths resolve from the project root.
  • { "type": "url", "url": "..." } — fetch the page/site when browsing or network access is available. If unavailable, report it under coverage limitations.
  • { "type": "git", "repo": "...", "path": "..." } — inspect the repo/path when it is already available or can be fetched without credentials. If unavailable, report it under coverage limitations.
• If docs.sources is absent, prompt the user: "Where should audit look for project documentation? I can add local paths, URLs, git repos, or set docs.sources: [] to keep fallback discovery and stop asking." Wait for the answer before continuing unless the run is explicitly autonomous; in autonomous runs, use fallback discovery and report that no decision was recorded.
• If the user chooses not to configure documentation sources, write docs.sources: [] in .safeword/config.json. Treat that explicit empty list as a durable no-prompt decision in future audits.
• If docs.sources: [] is configured, do not prompt. Fall back to local discovery: README.md, docs/, documentation/, package docs folders, and known docs-site configs.
• Always report docs coverage: configured vs fallback, sources checked, and sources skipped. In a diff audit, inspect sources directly affected by changed code or changed docs. In a repository audit, inspect the entire configured or fallback source inventory; date-only staleness and a last-20-commits sweep belong there too.

ARCHITECTURE.md (the architecture narrative):

• Resolve the narrative location first: the paths.architecture target in .safeword/config.json when set — a file is the narrative itself; a directory holds decision records, read them all — else the root ARCHITECTURE.md. A configured location wins outright: do not fall back to a root file the host deliberately moved away from. Every check below applies to the resolved narrative.
• If missing → create from .safeword/templates/architecture-template.md (at the configured location when paths.architecture is set, else root ARCHITECTURE.md)
• If exists → check for drift and gaps along TWO axes — dependency drift (what tech) and structural drift (what modules/layers):
  • Dependency drift:
    • Drift (error): Documented tech contradicts the code's actual dependencies (e.g., doc says "Redux" but package.json has "zustand"; doc says "Flask" but pyproject.toml has "fastapi")
    • Gap (error): Major dependencies not documented
  • Structural drift — reconcile ARCHITECTURE.md's STRUCTURAL claims against architecture.generated.md, the deterministic, always-fresh module/package map (kept current by the architecture hooks). Read the generated doc as ground truth — NOT package.json:
    • Read the namespace-root architecture.generated.md (resolve the namespace root the same way as other audit checks; default .project/). Its ### <name> headings under ## Modules (single-repo) or ## Packages (monorepo) ARE the project's real top-level units. This machine list is the source of structural truth, so the verdict is deterministic-by-reading, not guessed.
    • Orphaned (error): ARCHITECTURE.md documents a module/layer — including a layer→directory mapping in its "Layers & Boundaries" table — that no longer appears in the generated map (renamed or removed).
    • Drifted layer→dir (error): A "Layers & Boundaries" directory entry that matches no module path in the generated map.
    • Inventory omissions are not findings: The generated document owns the structural inventory. Never require the human narrative or decision records to mention every generated module/package; those documents own the architectural "why," not a duplicate package-by-package list.
    • Report only — never auto-overwrite prose. Cite the generated-doc evidence and propose narrative edits for the user to review; the human "why" is human-owned, and only a person can judge whether a paragraph is still true. The deterministic structural facts come from reading the generated doc; the narrative judgment stays with the human/agent.

README.md:

• Check changed claims and impacted references. Check date-only staleness only in a repository audit.

Docs site (if changed or directly impacted):

• Detect docs/, documentation/ with Starlight/Docusaurus/etc config
• Check staleness of docs content

Documentation impact check:

Review the changed area from the printed scope. For each significantly changed area, check if related docs, readmes, or guides need updating. Flag stale, missing, or contradictory impacted documentation as errors. Documentation drift is never a warning; date-only staleness with no changed-code contradiction is repository-audit context, not a diff finding.

6. Principle Trace Integrity

For the active ticket, when impl-plan.md declares project-principle alignment, resolve the source using paths.principles (default <namespace-root>/principles.md) and check the principle trace as observable facts only:

• The named principle exists in the configured source.
• The trace contains a non-empty concrete consequence and proof.
• The proof reference resolves to recorded test, verification, or manual evidence; an intentional conflict is named in Known deviations.

Report a missing source entry, incomplete mapping, dead evidence reference, or unrecorded conflict as [E010] Broken principle trace. Do not judge whether a principle was applicable, whether the consequence was a wise interpretation, or whether an experience was genuinely delightful—those are adversarial quality-review judgments. A plan with no declared applicable principle is not an audit finding.

Run the factual checker below verbatim. Its sentinel keeps the executable audit contract testable without turning semantic review into shell heuristics.

# principle-trace-check — E010 objective trace integrity only.
PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2> /dev/null || pwd)}"
bun "$PROJECT_DIR/.safeword/hooks/audit-principle-trace.ts" "$PROJECT_DIR"

7. Namespace Domain Docs

When a changed feature/spec or changed domain doc references them, reconcile the three namespace domain docs — personas.md, surfaces.md, glossary.md — against those changed references and report empty scaffolds. A repository audit reconciles the whole corpus. This check is read-only and class-2 (observable facts only): it reports and offers, it never rewrites a doc. Run the block below verbatim, as ONE bash invocation.

# domain-docs-check — read-only reconciliation of the namespace domain docs.
# Class-2: observable facts only. Emits W008 (empty). Never writes the tree.
cd "${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2> /dev/null || pwd)}" || exit 1
PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2> /dev/null || pwd)}"
source "$PROJECT_DIR/.safeword/hooks/lib/audit-scope.sh"
audit_scope_initialize "$PROJECT_DIR"

# Resolve the namespace root (honors config paths.projectRoot in real runs).
# Fall back on directory existence — robust when the resolver hook is absent.
NS_ROOT="$(bun "$PROJECT_DIR/.safeword/hooks/resolve-namespace-root.ts" "$PROJECT_DIR" 2> /dev/null)"
[ -d "$NS_ROOT" ] || {
  if [ -d "$PROJECT_DIR/.project" ]; then NS_ROOT="$PROJECT_DIR/.project"; else NS_ROOT="$PROJECT_DIR/.safeword-project"; fi
}
PERSONAS_FILE="$(bun "$PROJECT_DIR/.safeword/hooks/resolve-namespace-root.ts" "$PROJECT_DIR" personas personas.md 2> /dev/null)"
SURFACES_FILE="$(bun "$PROJECT_DIR/.safeword/hooks/resolve-namespace-root.ts" "$PROJECT_DIR" surfaces surfaces.md 2> /dev/null)"
GLOSSARY_FILE=
[ -n  ] || PERSONAS_FILE=
[ -n  ] || SURFACES_FILE=
[ -n  ] || GLOSSARY_FILE=



 [  =  ] && ! audit_scope_has_review_path_matching ; 
  domain_path_changed=
   configured_domain_file    ; 
    configured_domain_path=
    audit_scope_path_changed  && domain_path_changed=
  
  [  =  ] ||  0










strip_html_comments=





() {
  sed   | grep -cE 
}




 doc  personas surfaces glossary; 
    
    personas) dd_file= ;;
    surfaces) dd_file= ;;
    glossary) dd_file= ;;
  
  [ -f  ] || 
  domain_doc_path=
  [  =  ] || audit_scope_path_changed  || 
   [  -eq 0 ]; 
     
  







() {
   [ -x  ]; 
     feature-directories
   [ -f  ]; 
    bun  feature-directories
    -v bunx > /dev/null 2>&1; 
    bunx safeword feature-directories
  
     127
  
}
surfaces_file=
dd_file=
surfaces_path=
 [  =  ] || audit_scope_path_changed ; 
   ! FEATURE_DIRECTORIES=; 
     
    FEATURE_DIRECTORIES=
  
  SURFACE_FEATURE_FILES=

  SURFACE_FEATURE_FILES=

 [ -f  ] && [  -gt 0 ] && [ -n  ]; 
  
  
  defined_slugs=
  
  
  referenced_slugs=
   slug  ; 
     !    | grep -qxF ; 
       
    
  





personas_file=
tickets_dir=
dd_file=
personas_path=
 [  =  ] || audit_scope_path_changed ; 
  PERSONA_SPEC_FILES=

  PERSONA_SPEC_FILES=

 [ -f  ] && [  -gt 0 ] && [ -n  ]; 
  
  
  
  
  defined_codes=utf8\n```<!----><!---->)( ## 
  
  referenced_codes=
   code  ; 
     !    | grep -qxF ; 
       
    
  

Content is human-owned — advisory only, never an error. This check judges references (a slug/code that is or isn't defined) and emptiness — observable facts. Whether a glossary term's meaning, or a persona/surface description, is still accurate is a human judgment: raise it as an advisory note at most, never as an error code. Only the three codes above (E008, E009, W008) are emitted here.

Empty-doc offer (W008): report the empty doc and point the user to its template — do not draft entries or write the file during the audit pass (read-only). Filling it is a follow-up the user approves.

Coverage limitation: configured paths.personas, paths.surfaces, and paths.glossary are resolved before reconciliation. safeword doctor separately reports missing configured files and orphaned defaults. If the safeword feature-directory resolver is unavailable, W009 says E008 fell back to root features/ only. Persona drift reads spec **Persona:** lines only — feature lineage tags are not a reliable persona source.

---

Report Format

Report findings by severity with codes:

Errors (must fix)

• [E001] Dead ref: CLAUDE.md references missing file src/foo.ts
• [E002] Drift: ARCHITECTURE.md documents Redux, code uses Zustand
• [E003] Structural drift: ARCHITECTURE.md documents module legacy-sync — absent from architecture.generated.md (orphaned; renamed or removed)
• [E004] Documentation drift: Codex Stop hook behavior changed, but README.md or docs still describe only PreToolUse coverage
• [E005] Dependency gap: @tanstack/query is a major dependency but is not documented in ARCHITECTURE.md
• [E007] Drifted layer→dir: ARCHITECTURE.md maps domain → src/core/ but no such module path is in architecture.generated.md
• [E008] Surface drift: @surface.safeword-cli is referenced in features/ but has no matching entry in surfaces.md
• [E009] Persona drift: persona code DEV is named in a spec **Persona:** line but has no matching entry in personas.md
• [E010] Broken principle trace: Delight the user points to verify.md#persona-walkthrough, but that evidence record does not exist

Warnings (should review)

• [W001] Size: CLAUDE.md has 245 instructions (recommended: 150-200)
• [W002] Structure: AGENTS.md missing recommended WHAT/WHY/HOW sections
• [W003] Staleness: README.md last modified 45 days ago (12 commits since)
• [W005] Stale config: knip.json — lodash can be removed from ignoreDependencies
• [W006] Learning file missing Covers: — <namespace-root>/learnings/foo.md (absent from INDEX.md)
• [W007] Stale .safeword/depcruise-config.cjs — run safeword project sync-config to refresh and commit
• [W008] Empty domain doc: surfaces.md has no uncommented entries — fill from its template (BDD intake references degrade until filled)
• [W009] Feature-directory resolver unavailable — E008 scanned root features/ only

Code Quality

Architecture:

• Circular dependencies: [None / show cycle path]
• Layer violations: [None / show invalid import]

Dead Code:

• Knip findings: [list unused items to review — verify before removing, knip cannot see packages consumed via Astro/Vite/Wrangler config]

Duplication:

• Clone count: X (Y% of codebase; delta vs previous audit: +N/-N/flat)

Outdated Packages: the table + per-tier verdict from "Outdated Package Triage" above (or ✅ All packages up to date).

Test Quality:

• Files reviewed: N
• Issues: [None / list by severity]

---

Summary

Errors: N | Warnings: N | Passed: N

[Audit passed | Audit passed with warnings | Audit failed]

**Next:** [imperative — which fix to start, which package to upgrade, which file to update].

Close with the **Next:** line even on a clean pass — name the immediate move (commit, mark ticket done, open a follow-up for warnings) so the reader isn't left guessing which finding to start with (the stop hook reads it for the re-entry brief).

Voice: plainspoken and concise — write to be scanned.