ln-601-semantic-content-auditor

Semantic Content Auditor (L3 Worker)

Specialized worker auditing semantic accuracy of project documentation.

Purpose & Scope

• Worker in ln-600 coordinator pipeline - invoked by ln-600-docs-auditor for each project document
• Verify document content matches stated SCOPE (document purpose)
• Check content aligns with project goals (value contribution)
• Validate facts against codebase (accuracy and freshness)
• Return structured findings to coordinator with severity, location, fix suggestions

Target Documents

Called ONLY for project documents (not reference/tasks):

Excluded: docs/tasks/, docs/reference/, docs/presentation/, tests/

Inputs (from Coordinator)

{
  "doc_path": "docs/project/architecture.md",
  "project_root": "/path/to/project",
  "tech_stack": {
    "language": "TypeScript",
    "frameworks": ["Express", "React"]
  }
}

Workflow

Phase 1: SCOPE EXTRACTION

1. Read document first 20 lines
2. Parse <!-- SCOPE: ... --> comment
3. If no SCOPE tag, infer from document type (see Verification Rules)
4. Record stated purpose/boundaries

Phase 2: CONTENT-SCOPE ALIGNMENT

Analyze document sections against stated scope:

Scoring:

• 10/10: All content serves scope, scope fully covered
• 8-9/10: Minor off-topic content or small gaps
• 6-7/10: Some sections not aligned, partial coverage
• 4-5/10: Significant misalignment, major gaps
• 1-3/10: Document does not serve its stated purpose

Phase 3: FACT VERIFICATION

Per document type, verify claims against codebase:

Finding Types:

• OUTDATED_PATH: File/folder path no longer exists
• WRONG_VERSION: Documented version differs from package file
• MISSING_ENDPOINT: Documented API endpoint not found in code
• BEHAVIOR_MISMATCH: Described behavior differs from implementation
• STALE_REFERENCE: Reference to removed/renamed entity

Scoring:

• 10/10: All facts verified against code
• 8-9/10: Minor inaccuracies (typos, formatting)
• 6-7/10: Some paths/names outdated, core info correct
• 4-5/10: Functional mismatches (wrong behavior described)
• 1-3/10: Critical mismatches (architecture wrong, APIs broken)

Phase 4: SCORING & REPORT

Calculate final scores and compile findings:

scope_alignment_score = weighted_average(coverage, relevance, focus)
fact_accuracy_score = (verified_facts / total_facts) * 10

overall_score = (scope_alignment * 0.4) + (fact_accuracy * 0.6)

Fact accuracy weighted higher because incorrect information is worse than scope drift.

Output Format

Return JSON to coordinator:

{
  "doc_path": "docs/project/architecture.md",
  "scope": {
    "stated": "System architecture with C4 diagrams, component interactions",
    "coverage_percent": 85
  },
  "scores": {
    "scope_alignment": 8,
    "fact_accuracy": 6,
    "overall": 7
  },
  "summary": {
    "total_issues": 4,
    "high": 1,
    "medium": 2,
    "low": 1
  },
  "findings": [
    {
      "severity": "HIGH",
      "type": "BEHAVIOR_MISMATCH",
      "location": "line 45",
      "issue": "Architecture shows 3-tier (Controller->Service->Repository) but code has Controller->Repository direct calls",
      "evidence": "src/controllers/UserController.ts:23 imports UserRepository directly",
      "fix": "Update diagram to show actual pattern OR refactor code to match docs"
    },
    {
      "severity": "MEDIUM",
      "type": "OUTDATED_PATH",
      "location": "line 78",
      "issue": "References src/services/legacy/ which was removed",
      "evidence": "Folder does not exist: ls src/services/legacy/ returns error",
      "fix": "Remove reference or update to current path"
    }
  ]
}

Verification Rules by Document Type

See references/verification_rules.md for detailed per-document verification patterns.

Critical Rules

• Read before judge: Always read full document and relevant code before reporting issues
• Evidence required: Every finding must include evidence field with verification command/result
• Code is truth: When docs contradict code, document is wrong (unless code is a bug)
• Scope inference: If no SCOPE tag, use document filename to infer expected scope
• No false positives: Better to miss an issue than report incorrectly
• Location precision: Always include line number for findings
• Actionable fixes: Every finding must have concrete fix suggestion

Definition of Done

• Document read completely
• SCOPE extracted or inferred
• Content-scope alignment analyzed
• Facts verified against codebase (with evidence)
• Both scores calculated
• JSON result returned to coordinator

---

Version: 1.0.0 Last Updated: 2026-01-28