How to Fix L007 and L010 Audit Script Errors in AI Engineering Curriculum

L007 indicates legacy quiz schema violations while L010 signals broken internal links, both enforced by the audit_lessons.py validation script to maintain curriculum integrity.

The rohitg00/ai-engineering-from-scratch repository uses automated auditing to enforce strict lesson-authoring standards. When contributors submit lessons that violate the canonical data contracts, the audit script emits specific error codes that block integration. Understanding the root causes of L007 (legacy quiz schema) and L010 (broken internal links) helps you write compliant lessons that pass continuous integration checks.

Understanding L007 Legacy Quiz Schema Errors

The validation logic in scripts/audit_lessons.py (lines 60-66) strictly enforces a canonical key structure for all quiz entries. When the parser encounters deprecated field names, it immediately flags the violation as L007.

What Triggers L007 Errors

The audit script expects quiz objects to use exactly five canonical keys: stage, question, options, correct, and explanation. If your JSON contains legacy keys such as q, choices, or answer, the script reports L007. This typically happens when contributors copy-paste from older lesson templates that predate the schema migration, mistakenly assume that choices is synonymous with options, or mix JSON formats within the same lesson directory.

How to Fix L007 Violations

Replace every legacy key with its canonical counterpart. Ensure your quiz.json follows this exact structure:

{
  "stage": "check",
  "question": "What is the output of 2 + 2?",
  "options": ["3", "4", "5", "6"],
  "correct": 1,
  "explanation": "2 + 2 equals 4."
}

Avoid these deprecated patterns that trigger L007:

{
  "stage": "check",
  "question": "Select the activation function.",
  "choices": ["sigmoid", "relu", "tanh"],
  "answer": 1
}

Resolving L010 Broken Internal Links

The auditor validates all markdown hyperlinks in phases/*/*/docs/en.md by resolving each href against the repository root (lines 100-111 of audit_lessons.py). When the target file or directory does not exist on disk, the script emits L010.

Common Causes of L010 Failures

Typographical errors in paths, such as [Guide](../doc/guide.md) instead of ../docs/guide.md, are the most frequent culprit. Moved or renamed files without corresponding reference updates also trigger this error, as does relative-path confusion where ./ or ../ resolves outside the lesson directory. Additionally, missing leading slashes in absolute paths prevent the resolver from locating files in the phases/ hierarchy.

Validating and Repairing Internal Links

Before committing changes, verify that every markdown link points to an existing file. This example demonstrates a broken reference that fails the audit:

For more details see [Back-prop tutorial](../docs/backprop-tutorial.md).

The corrected version ensures the target exists:

For more details see [Back-prop tutorial](../docs/backpropagation.md).

Run the audit script locally after editing to confirm path resolution succeeds before pushing to remote.

Summary

• L007 errors occur when quiz.json files use legacy keys (q, choices, answer) instead of the canonical schema (stage, question, options, correct, explanation) validated in scripts/audit_lessons.py.
• L010 errors indicate unresolved internal links in markdown files, typically caused by typos, moved files, or incorrect relative paths in docs/en.md.
• Fixing L007 requires replacing deprecated JSON keys with their modern equivalents and ensuring all quiz objects include the explanation field.
• Resolving L010 demands filesystem verification that each href target exists relative to the repository root, using absolute paths with leading slashes when referencing other lesson phases.

Frequently Asked Questions

What is the audit_lessons.py script?

The audit_lessons.py script is the validation gatekeeper located in the scripts/ directory that parses every lesson's quiz.json and docs/en.md files. It enforces data integrity rules by checking for schema compliance and resolvable file paths, emitting error codes like L007 and L010 when lessons violate the authoring contract.

How do I convert legacy quiz keys to the canonical format?

Map each deprecated key to its modern equivalent: change q to question, choices to options, and answer to correct. Additionally, ensure every quiz object includes the required stage and explanation fields that legacy schemas often omitted. Validate your JSON syntax before running the audit to prevent parsing errors.

Why does a link work in my editor but fail the audit?

Your editor may resolve relative paths differently than the audit script, which evaluates all links from the repository root. The audit script in scripts/audit_lessons.py performs strict filesystem checks against the actual directory structure, so links that rely on your editor's working directory or preview mode will fail if the absolute path does not exist in the committed codebase.

Can I run the audit script locally before submitting?

Yes, execute python scripts/audit_lessons.py from the repository root to validate your changes before opening a pull request. Local execution catches L007 schema violations and L010 broken links immediately, preventing CI failures and allowing you to fix path errors or JSON formatting issues in your development environment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}