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

> Resolve L007 legacy quiz schema and L010 broken internal links errors in your AI Engineering curriculum. Learn how to fix these common audit script issues and ensure lesson integrity.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: troubleshooting
- Published: 2026-08-29

---

**L007 indicates legacy quiz schema violations while L010 signals broken internal links, both enforced by the [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) follows this exact structure:

```json
{
  "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:

```json
{
  "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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/../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:

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

```

The corrected version ensures the target exists:

```markdown
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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) script is the validation gatekeeper located in the `scripts/` directory that parses every lesson's [`quiz.json`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/quiz.json) and [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.