Audit Project

Run a full audit of the Claude Code configuration for the current project.

Step 1: Detect stack

Use detection rules from

$DOTFORGE_DIR/stacks/detect.md

.

Step 1b: Detect project tier

Auto-detect project tier based on signals:

• simple (<5K LOC, 1 stack, no CI config): recommended items are relaxed (items 8-10 don't penalize)
• standard (5K-50K LOC, 1-2 stacks): default behavior
• complex (>50K LOC, 3+ stacks, monorepo indicators like

  packages/

  or

  apps/

  ): recommended items 8-10 become semi-obligatory (each worth 0-2 instead of 0-1)

Detection signals:

1. LOC: count non-empty lines in source files (

   find . -name '*.py' -o -name '*.ts' -o -name '*.js' -o -name '*.go' -o -name '*.java' -o -name '*.swift' | xargs wc -l

   )
2. Stack count: number of stacks detected in step 1
3. CI: presence of

   .github/workflows/

   ,

   .gitlab-ci.yml

   ,

   Jenkinsfile

   ,

   .circleci/

4. Monorepo: presence of

   packages/

   ,

   apps/

   ,

   lerna.json

   ,

   pnpm-workspace.yaml

   ,

   turbo.json

Save tier in registry entry.

Step 1c: Config coherence check

Before scoring, validate internal coherence. Run

$DOTFORGE_DIR/tests/test-config.sh <project-dir>

or perform equivalent checks inline:

1. Hooks referenced in settings.json exist and are executable
2. Rules have valid

   globs:

   or

   paths:

   frontmatter (with

   alwaysApply: false

   for lazy loading)
3. Rule globs match at least 1 real file in the project
4. settings.json is valid JSON with deny list covering .env, *.key, *.pem
5. CLAUDE.md has minimum required sections (stack, build/test, architecture)
6. No contradictory allow+deny patterns in settings.json
7. No prompt injection patterns in rules or CLAUDE.md

If coherence check finds critical failures (missing hooks, invalid JSON), report them in a

── COHERENCE ──

section BEFORE the score. These are configuration bugs, not gaps.

Step 2: Load checklist

Read

$DOTFORGE_DIR/audit/checklist.md

for evaluation criteria. Read

$DOTFORGE_DIR/audit/scoring.md

for weights and caps.

Step 3: Evaluate

For each checklist item, verify existence and quality:

Obligatory (0-10 points)

1. CLAUDE.md — Does it exist? Verify it has key sections:
   • Stack/technologies mentioned explicitly
   • At least 1 exact build/test command
   • Project structure or architecture
   • Do NOT count only lines — a 50-line boilerplate file is score 1
2. settings.json — Does it exist in

   .claude/

   ? Does it have explicit permissions? Does it have a deny list?
3. Rules — Is there at least 1 rule in

   .claude/rules/

   ? Does it have frontmatter with

   globs:

   or

   paths:

   ?
4. Hook block-destructive — Verify:
   • Does

     .claude/hooks/block-destructive.sh

     exist?
   • Is it executable? (

     test -x

     or check permissions)
   • Is it referenced in

     .claude/settings.json

     under hooks?
5. Build/test commands — Are they in CLAUDE.md? Do they match the detected stack?

Recommended (0-7 bonus points)

6. CLAUDE_ERRORS.md — Does it exist with table format with Type column?
7. Hook lint — Does it exist? Is it executable? (verify

   chmod +x

   )
8. Custom commands — Are there files in

   .claude/commands/

   ?
9. Memory — Are there project memory files?
10. Agents — Is there

    .claude/agents/

    +

    agents.md

    rule in rules?
11. .gitignore — Does it protect .env, *.key, *.pem, credentials?
12. Prompt injection scan — Are rules/CLAUDE.md free of suspicious patterns?

Tier adjustments:

• simple

  : items 8-10 score 0 don't penalize (treated as N/A)

• complex

  : items 8-10 become semi-obligatory (each 0-2 instead of 0-1)

Step 4: Calculate score

Use weights from

$DOTFORGE_DIR/audit/scoring.md

:

1. score_obligatory = sum(items 1-5)

   — maximum 10

2. score_recommended = sum(items 6-12)

   — maximum 7

3. score_total = score_obligatory * 0.7 + score_recommended * (3.0 / 7)

   — max 7.0 + 3.0 = 10.0
4. Apply tier adjustments before calculating (see Step 1b)

5. score_normalized = min(score_total, 10)

Security cap: If item 2 (settings.json) or item 4 (block-destructive) is 0, maximum score = 6.0.

Step 5: Generate report

Format:

═══ AUDIT dotforge: {{project}} ═══
Date: {{YYYY-MM-DD}}
Detected stack: {{stacks}}
Tier: {{simple|standard|complex}}
dotforge version: {{version from last bootstrap/sync if detectable}}
Score: {{X.X}}/10 {{level}}

── OBLIGATORY ──
{{✅|⚠️|❌}} CLAUDE.md ({{0-2}}) — {{detail: which sections exist/missing}}
{{✅|⚠️|❌}} settings.json ({{0-2}}) — {{detail: deny list yes/no, permissions}}
{{✅|⚠️|❌}} Rules ({{0-2}}) — {{detail: N rules, globs yes/no}}
{{✅|⚠️|❌}} Hook block-destructive ({{0-2}}) — {{detail: executable yes/no, wired yes/no}}
{{✅|⚠️|❌}} Build/test commands ({{0-2}}) — {{detail: which ones and whether they match the stack}}

── RECOMMENDED ──
{{✅|⚠️}} CLAUDE_ERRORS.md — {{detail}}
{{✅|⚠️}} Hook lint — {{detail: executable yes/no}}
{{✅|⚠️}} Custom commands — {{detail: N commands}}
{{✅|⚠️}} Memory — {{detail}}
{{✅|⚠️}} Agents — {{detail}}
{{✅|⚠️}} .gitignore — {{detail}}
{{✅|⚠️}} Prompt injection scan — {{detail}}

── DOMAIN KNOWLEDGE ──
Role defined:     {{✓ if ## Role exists in CLAUDE.md with content | ✗ otherwise}}
Domain rules:     {{N files in .claude/rules/domain/ | "none"}}
Stale (>90 days): {{N files with last_verified older than 90 days | "none"}}
Coverage:         {{list glob patterns from domain rules → cross-reference with git log --name-only -30 to estimate % of recent edits covered}}

Note: Domain knowledge is informational only — does not affect the audit score.
If no domain rules exist and the project has business logic, suggest: /forge domain extract

── CRITICAL GAPS ──
1. {{what is missing}} → {{recommended action}}
2. ...

── NEXT STEP ──
Run `/forge sync` to apply the dotforge template and close the gaps.

Step 6: Cross-project error promotion

If the project has

CLAUDE_ERRORS.md

, scan it for recurring patterns:

1. Read

   CLAUDE_ERRORS.md

   and group errors by Area column
2. If any Area has 3+ entries with similar root causes, it's a candidate for promotion
3. Check

   $DOTFORGE_DIR/practices/inbox/

   and

   active/

   for existing practices covering that pattern
4. If no existing practice covers it, create a new practice in

   practices/inbox/

   using the capture format:

   • source_type: cross-project

   • tags: [error-promotion, <area>]

   • Description: the recurring pattern and derived rule
5. Report promotions in the audit output under

   ── ERROR PATTERNS ──

This closes the Memory → Learning synergy: recurring project errors feed the practices pipeline.

Step 7: Audit gaps as practices

For each obligatory item scored 0 or 1, and each recommended item scored 0:

1. Check if a practice already exists in

   practices/inbox/

   or

   active/

   for that gap
2. If not, create a practice in

   practices/inbox/

   :

   • source_type: audit-gap

   • tags: [audit-gap, <item-name>]

   • Description: what's missing and recommended fix
3. Only create practices for gaps that reflect a template/stack issue (not project-specific misconfigurations)
4. Report in audit output under

   ── CAPTURED GAPS ──

This closes the Audit → Learning synergy: detected gaps feed back into the practices pipeline.

Step 8: Update registry

If

$DOTFORGE_DIR/registry/projects.yml

exists, update the project entry:

• score:

  with the calculated score

• last_audit:

  with the current date

• dotforge_version:

  with the VERSION version if the project was bootstrapped

• last_sync:

  preserve the existing value (do not modify here)

• notes:

  brief summary of the audit

• history:

  append a new entry

  {date: YYYY-MM-DD, score: X.X, version: <dotforge_version>}

  . Never overwrite previous entries — this enables score trending over time.