Update docs for v2026.01.00

[nsaulnier-ti]

No description provided.

[qodo-code-review]

Review Summary by Qodo

(Agentic_describe updated until commit a2b1d71)

Update documentation for v2026.01.00 and improve contribution guidelines

📝 Documentation ✨ Enhancement

Walkthroughs

Description

• Remove outdated pru_dependencies scripts no longer maintained
• Update documentation for PRU Academy v2026.01.00 release
• Add new guide for creating MCU+ projects in OpenPRU repo
• Enhance contributing guidelines with AI-agent documentation requirements
• Clarify project structure and build infrastructure patterns

Diagram

flowchart LR
  A["v2026.01.00 Updates"] --> B["README.md"]
  A --> C["Contributing Guide"]
  A --> D["Project Creation Docs"]
  B --> E["Training Section"]
  B --> F["CCS Build Steps"]
  C --> G["AI Documentation Requirements"]
  C --> H["Build Verification Steps"]
  D --> I["New MCU+ Project Guide"]
  D --> J["Organization Reference"]
  K["Remove Scripts"] --> L["pru_dependencies.bat"]
  K --> M["pru_dependencies.sh"]
  K --> N["pru_dependencies_readme.md"]

Loading

File Changes

1. docs/pru_dependencies.bat 📝 Documentation +0/-255

Remove outdated Windows dependency installation script

docs/pru_dependencies.bat

---

2. docs/pru_dependencies.sh 📝 Documentation +0/-397

Remove outdated Linux dependency installation script

docs/pru_dependencies.sh

---

3. docs/pru_dependencies_readme.md 📝 Documentation +0/-129

Remove documentation for deprecated dependency scripts

docs/pru_dependencies_readme.md

---

View more (8)

4. README.md 📝 Documentation +52/-31

Add training section and update build documentation

README.md

---

5. best_practices.md 📝 Documentation +42/-17

Separate PRU and MCU+ C code best practices sections

best_practices.md

---

6. docs/contributing.md 📝 Documentation +157/-46

Restructure with AI-agent requirements and detailed checklists

docs/contributing.md

---

7. docs/open_pru_create_new_project.md 📝 Documentation +386/-44

Expand with prerequisites, makefile overview, and CCS details

docs/open_pru_create_new_project.md

---

8. docs/open_pru_create_new_mcuplus_project.md 📝 Documentation +276/-0

Create new guide for adding MCU+ code to OpenPRU projects

docs/open_pru_create_new_mcuplus_project.md

---

9. docs/open_pru_organization.md 📝 Documentation +22/-1

Clarify project structure and add directory organization details

docs/open_pru_organization.md

---

10. imports.mak.default 📝 Documentation +4/-0

Add clarifying comments for compiler toolchain variables

imports.mak.default

---

11. pr_compliance_checklist.yaml 📝 Documentation +78/-1

Add new compliance checks for documentation and contribution requirements

pr_compliance_checklist.yaml

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (4) 📘 Rule violations (6) 📎 Requirement gaps (0)

1. Tabs added in code block 📘 Rule violation ⚙ Maintainability ⭐ New

Description

New lines in docs/open_pru_organization.md use tab characters for indentation inside a code block,
which violates the repo formatting guidance that disallows tabs in source files. Tabs can render
inconsistently across editors and break formatting rules.

Code

docs/open_pru_organization.md[R18-23]

+	Projects sit either directly under academy/ or under a topic subdirectory:
+	  academy/<project>              (e.g., getting_started_labs)
+	  academy/<topic>/<project>      (e.g., mac/mac_multiply, uart/uart_echo)
+	academy/makefile lists entries as <topic>/<project> for topic projects
+	and as <project> for top-level projects. There is no intermediate
+	per-topic makefile.

Evidence

PR Compliance ID 15 forbids disallowed whitespace such as tabs. The added repository tree lines in
docs/open_pru_organization.md are indented with tabs (visible before the text in the fenced
block).

docs/open_pru_organization.md[18-23]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/open_pru_organization.md` adds tab-indented lines inside a fenced code block. Compliance requires avoiding tabs.

## Issue Context
Tabs render inconsistently and violate the repo formatting/whitespace requirements.

## Fix Focus Areas
- docs/open_pru_organization.md[18-23]

## Suggested approach
- Replace leading tab characters with spaces (e.g., 4-space indentation) while keeping the visual tree structure aligned.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Trailing space after Projects** 📘 Rule violation ⚙ Maintainability

Description

A trailing space was introduced at the end of the Using SDK with CCS Projects line, which can
cause inconsistent Markdown rendering and violates documentation hygiene. Trailing whitespace also
creates noisy diffs and can break strict linting.

Code

README.md[125]

+  MCU+ SDK documentation: **Developer Guides > Using SDK with CCS Projects** 

Evidence

PR Compliance ID 24 requires documentation to avoid trailing spaces for render stability.
README.md line 125 ends with trailing whitespace after **Using SDK with CCS Projects**, which is
visible in the modified line.

README.md[125-125]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A trailing space was added at the end of a Markdown line, which can cause inconsistent rendering and violates documentation hygiene requirements.
## Issue Context
This was introduced in the README under the CCS build documentation.
## Fix Focus Areas
- README.md[125-125]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Tab rule unenforceable 🐞 Bug ☼ Reliability

Description

The new compliance check "Tabs in Assembly and C Source Files" requires that .asm/.inc/.c/.h files
contain no tab characters, but the repository already contains tabs in these file types. If enforced
as written, this will create perpetual compliance failures unless the rule is scoped to changed
lines/files or the repo is reformatted.

Code

pr_compliance_checklist.yaml[R206-213]

+  - title: "Tabs in Assembly and C Source Files"
+    compliance_label: true
+    objective: "Ensure assembly and C source files use spaces for indentation, not tab characters (best_practices.md §General Remarks)"
+    success_criteria: |
+      - "All .asm, .inc, .c, and .h source files use spaces only — no tab characters"
+      - "Exempt file types: linker.cmd, makefile, makefile_projectspec, makefile_ccs_bootimage_gen, and other build infrastructure files — tab characters are acceptable in those files"
+    failure_criteria: |
+      - "Any .asm, .inc, .c, or .h file containing tab characters"

Evidence

The compliance checklist adds a strict "no tabs" requirement for all .asm/.inc/.c/.h files, but
existing C source already uses tab indentation/alignment, meaning the repo does not satisfy the
requirement today.

pr_compliance_checklist.yaml[206-213]
examples/empty_c/firmware/main.c[8-11]
source/rpmsg/pru_rpmsg.c[34-41]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A new compliance rule bans tab characters in all `.asm`, `.inc`, `.c`, and `.h` files, but the existing repository already contains tabs in these file types. If the compliance system evaluates the whole repo or whole files, this requirement becomes impossible to satisfy without a repo-wide reformat.
## Issue Context
The rule text currently reads as a global property ("All .asm, .inc, .c, and .h source files...") and does not state that it applies only to files/lines modified in the PR.
## Fix Focus Areas
- pr_compliance_checklist.yaml[206-213]
## Desired fix
Choose one path and update the checklist text accordingly:
1) **Scope the rule to the PR diff** (recommended): change success/failure criteria to explicitly apply only to *new/modified lines* or *files changed in the PR*.
2) **Repo-wide cleanup**: perform a repo-wide conversion of tabs to spaces in all affected source files *before* enabling the global requirement.
3) **Defer/soften enforcement**: make it informational until cleanup is completed.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (5)

4. Broken docs/... links ☑ 📘 Rule violation ≡ Correctness

Description

docs/open_pru_create_new_mcuplus_project.md links to docs/open_pru_create_new_project.md and
docs/open_pru_organization.md, which will resolve to docs/docs/... and break when rendered. This
violates the requirement for portable, correct doc paths.

Code

docs/open_pru_create_new_mcuplus_project.md[R12-13]

+First, create the new PRU firmware project by completing
+[Creating a New Project in the OpenPRU Repo](docs/open_pru_create_new_project.md).

Evidence

PR Compliance ID 24 requires correct, portable link paths. The added links use a docs/ prefix from
within a docs/ file, creating incorrect relative paths.

docs/open_pru_create_new_mcuplus_project.md[12-13]
docs/open_pru_create_new_mcuplus_project.md[55-56]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/open_pru_create_new_mcuplus_project.md` uses `docs/...` relative links even though it is already under `docs/`, resulting in broken `docs/docs/...` paths.
## Issue Context
These links should be relative to the current file (for example, `./open_pru_create_new_project.md`).
## Fix Focus Areas
- docs/open_pru_create_new_mcuplus_project.md[12-13]
- docs/open_pru_create_new_mcuplus_project.md[55-56]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. e.g. and tabs used 📘 Rule violation ⚙ Maintainability

Description

The updated docs/open_pru_organization.md uses disallowed shorthand (e.g.) and introduces tab
characters in the code block indentation. This violates the repo-wide terminology/whitespace hygiene
requirements.

Code

docs/open_pru_organization.md[R17-23]

getting started & training labs
+	Projects sit either directly under academy/ or under a topic subdirectory:
+	  academy/<project>              (e.g., getting_started_labs)
+	  academy/<topic>/<project>      (e.g., mac/mac_multiply, uart/uart_echo)
+	academy/makefile lists entries as <topic>/<project> for topic projects
+	and as <project> for top-level projects. There is no intermediate
+	per-topic makefile.

Evidence

PR Compliance ID 19 forbids e.g. in favor of “for example” and disallows non-space whitespace
characters like tabs. The added lines include both e.g., and tab-indented text.

docs/open_pru_organization.md[17-23]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The updated documentation contains `e.g.` and uses tab characters for indentation.
## Issue Context
Repo terminology and whitespace hygiene rules require “for example” instead of `e.g.` and spaces instead of tabs.
## Fix Focus Areas
- docs/open_pru_organization.md[17-23]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. ../docs/open_pru_organization.md bad link 📘 Rule violation ⚙ Maintainability

Description

best_practices.md links to ../docs/open_pru_organization.md, which resolves outside the repo
root from this file location and will break navigation. This violates the requirement that
documentation links be portable and correctly pathed.

Code

best_practices.md[R499-500]

+See [docs/open_pru_organization.md](../docs/open_pru_organization.md) for the
+authoritative project and repository layout.

Evidence

PR Compliance ID 25 requires documentation links to use correct, portable paths. The added link in
best_practices.md uses ../docs/... even though best_practices.md is at the repo root, so the
referenced path does not match the actual location.

best_practices.md[499-500]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`best_practices.md` contains a broken/incorrect relative link to `docs/open_pru_organization.md`.
## Issue Context
`best_practices.md` is in the repository root, so linking to `../docs/...` points outside the repo root.
## Fix Focus Areas
- best_practices.md[499-500]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. docs/-prefixed links in docs ☑ 📘 Rule violation ⚙ Maintainability

Description

docs/open_pru_create_new_project.md uses docs/...-prefixed relative links even though the file
itself is already under docs/, producing broken docs/docs/... paths. This violates the
requirement that documentation links be portable and correctly pathed.

Code

docs/open_pru_create_new_project.md[R24-28]

+### Set up the repo
+
+Before creating a new OpenPRU project, set up the OpenPRU repo by following the
+steps at [Getting Started with OpenPRU](docs/getting_started.md).
+

Evidence

PR Compliance ID 25 requires documentation links to match correct paths. In
docs/open_pru_create_new_project.md, the new link target includes an extra docs/ prefix, which
will not resolve correctly from within the docs/ directory.

docs/open_pru_create_new_project.md[24-28]
docs/open_pru_create_new_project.md[169-172]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Relative links inside `docs/open_pru_create_new_project.md` incorrectly include a leading `docs/`, causing broken `docs/docs/...` paths.
## Issue Context
Because the file is already located under `docs/`, links to other docs should typically be `./<file>.md` (or just `<file>.md`).
## Fix Focus Areas
- docs/open_pru_create_new_project.md[24-28]
- docs/open_pru_create_new_project.md[169-172]
- docs/open_pru_create_new_project.md[446-449]
- docs/open_pru_create_new_project.md[471-474]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

8. Missing docs_ai runbooks 🐞 Bug ☼ Reliability

Description

The PR adds contribution guidance and compliance checks that require docs_ai/ runbooks (e.g.,
docs_ai/task_create_project.md), but the repository contains no docs_ai/ directory, making the
requirement impossible to satisfy. This can confuse contributors and can also break any automated
enforcement that assumes those files exist.

Code

docs/contributing.md[R43-56]

+### Update AI-agent documentation
+
+If your PR changes any of the following, check whether `docs_ai/` needs
+updating before submitting:
+
+* Project directory structure or file naming conventions
+* Makefile patterns (project `makefile`, core makefile, parent `makefile`)
+* CCS build infrastructure (`example.projectspec` patterns)
+* Adding support for a new device or board
+* Adding or removing a shared library in `source/`
+
+If the existing runbooks in `docs_ai/` still accurately describe the patterns
+after your change, no update is needed. If they no longer match, update the
+relevant runbook(s) as part of the same PR.

Evidence

docs/contributing.md newly instructs contributors to update docs_ai/, and
pr_compliance_checklist.yaml introduces compliance criteria that reference specific docs_ai/...
files; however, no such runbooks are present in the repository contents of this PR.

docs/contributing.md[43-56]
pr_compliance_checklist.yaml[194-204]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The documentation and compliance checklist reference a `docs_ai/` directory and specific runbooks that are not present in the repo, making the new requirements non-actionable.
## Issue Context
Either the PR must introduce the referenced `docs_ai/` directory + the runbooks it names, or the contributing guidelines/compliance checks must be updated to reference documentation that actually exists.
## Fix Focus Areas
- docs/contributing.md[43-56]
- pr_compliance_checklist.yaml[194-204]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

9. Contributing TOC formatting broken 🐞 Bug ⚙ Maintainability ⭐ New

Description

The new TOC entries for the "Reference" sections in docs/contributing.md are not formatted as list
items and lack Markdown line breaks, so they will render as a single wrapped paragraph instead of a
readable TOC. This makes navigation significantly harder and inconsistent with the rest of the TOC
formatting.

Code

docs/contributing.md[R15-19]

+[Reference: project documentation](#reference-project-documentation):
+[Project-level readme](#project-level-readme),
+[Update the section-level readme](#update-the-section-level-readme)
+[Reference: build verification](#reference-build-verification):
+[Testing the build](#testing-the-build)

Evidence

The TOC lines for the reference subsections are plain lines without list markers or trailing
double-spaces, unlike the earlier TOC entries that use proper line breaks; in standard Markdown,
those lines will be merged into one paragraph.

docs/contributing.md[9-20]
docs/contributing.md[15-19]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The TOC in `docs/contributing.md` renders incorrectly because several entries aren’t formatted as a list and don’t include Markdown line breaks.

### Issue Context
The TOC currently mixes `two-space line breaks` and plain lines with colons/commas, which Markdown will fold into a single paragraph.

### Fix Focus Areas
- docs/contributing.md[9-20]

### Suggested change
Convert the TOC to a proper bulleted list with nested bullets for the reference subsections, e.g.:
- [Reference: project documentation](#reference-project-documentation)
 - [Project-level readme](#project-level-readme)
 - [Update the section-level readme](#update-the-section-level-readme)
- [Reference: build verification](#reference-build-verification)
 - [Testing the build](#testing-the-build)
(Or add explicit line breaks consistently, but a list is clearer.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

10. Drift check too broad 🐞 Bug ⚙ Maintainability

Description

The "Contributing Requirements Drift" success criteria triggers on any edit to docs/contributing.md,
even typo/format-only changes, forcing unrelated edits to pr_compliance_checklist.yaml. This does
not match the stated objective of syncing only when contribution requirements change and will cause
unnecessary churn.

Code

pr_compliance_checklist.yaml[R185-192]

+  - title: "Contributing Requirements Drift"
+    compliance_label: true
+    objective: "Keep pr_compliance_checklist.yaml in sync when contribution requirements change in docs/contributing.md"
+    success_criteria: |
+      - "If docs/contributing.md was not modified, this check is not applicable"
+      - "If docs/contributing.md was modified, pr_compliance_checklist.yaml was also modified in the same PR"
+    failure_criteria: |
+      - "PR modifies docs/contributing.md without a corresponding change to pr_compliance_checklist.yaml"

Evidence

The objective says to sync the checklist when requirements change, but the success criteria requires
checklist edits whenever docs/contributing.md is modified at all.

pr_compliance_checklist.yaml[185-192]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The drift compliance rule currently requires updating `pr_compliance_checklist.yaml` whenever `docs/contributing.md` is modified, regardless of whether any contribution requirements changed. This will add friction to routine doc fixes.
## Issue Context
Objective is narrower than the trigger condition in success criteria.
## Fix Focus Areas
- pr_compliance_checklist.yaml[185-192]
## Desired fix
Adjust the success/failure criteria to better match the objective, e.g.:
- Make it a **manual-review** item rather than an automatic condition.
- Reword criteria to apply when **requirements/checklists change** (acknowledging automation limits).
- Or remove the check and rely on reviewer guidance in `docs/contributing.md`.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

11. Training URLs exceed line limits 📘 Rule violation ⚙ Maintainability

Description

The newly added Training links are extremely long single-line URLs, which hurts markdown readability
and violates the render-stability line-length guidance. Consider using reference-style links or
otherwise formatting to keep lines within the documented limits.

Code

README.md[R59-62]

+TI provides additional training for programming the PRU subsystem in
+processor-specific academies. The currently published PRU Academies are:
+[PRU Academy for AM243x](https://dev.ti.com/tirex/explore/node?isTheia=false&node=A__AB.mSUi9ihL.a5hIt1grfw__AM24X-ACADEMY__ZPSnq-h__LATEST)  
+[PRU Academy for AM64x](https://dev.ti.com/tirex/explore/node?isTheia=false&node=A__AB.mSUi9ihL.a5hIt1grfw__AM64-ACADEMY__WI1KRXP__LATEST)  

Evidence

PR Compliance ID 27 requires documentation to be render-stable and to keep lines within the
documented limits (about 79 chars) by reflowing where needed. The added markdown link lines contain
very long URLs on a single line.

README.md[59-62]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`README.md` adds very long inline URLs in the Training section, creating overly long lines.
## Issue Context
The docs compliance guidance asks to keep markdown lines reasonably short for stable rendering and reviewability.
## Fix Focus Areas
- README.md[59-62]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (1)

12. e.g., used in create-project doc 📘 Rule violation ⚙ Maintainability

Description

The updated document uses the disallowed abbreviation e.g., instead of for example. This
violates the repository text standardization requirement.

Code

docs/open_pru_create_new_project.md[R247-251]

+> [!NOTE]
+> Update the path to match your project's actual MCU+ directory structure.
+> Some projects place MCU+ code under `mcuplus/<board>/` (e.g., `examples/empty`);
+> others place it directly under `<board>/` at the project root
+> (e.g., `academy/intc/intc_mcu`).

Evidence

PR Compliance ID 20 prohibits e.g. in repository text and requires using for example instead.
The cited lines include e.g., in the NOTE block.

docs/open_pru_create_new_project.md[247-251]
docs/open_pru_create_new_project.md[309-311]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/open_pru_create_new_project.md` contains `e.g.,` which is disallowed.
## Issue Context
The repository documentation standard requires `for example` instead of `e.g.`.
## Fix Focus Areas
- docs/open_pru_create_new_project.md[247-251]
- docs/open_pru_create_new_project.md[309-311]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Previous review results

Review updated until commit a2b1d71

Results up to commit a2b1d71

🐞 Bugs (3) 📘 Rule violations (5) 📎 Requirement gaps (0)

1. Trailing space after Projects** 📘 Rule violation ⚙ Maintainability ⭐ New

Description

A trailing space was introduced at the end of the Using SDK with CCS Projects line, which can
cause inconsistent Markdown rendering and violates documentation hygiene. Trailing whitespace also
creates noisy diffs and can break strict linting.

Code

README.md[125]

+  MCU+ SDK documentation: **Developer Guides > Using SDK with CCS Projects** 

Evidence

PR Compliance ID 24 requires documentation to avoid trailing spaces for render stability.
README.md line 125 ends with trailing whitespace after **Using SDK with CCS Projects**, which is
visible in the modified line.

README.md[125-125]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A trailing space was added at the end of a Markdown line, which can cause inconsistent rendering and violates documentation hygiene requirements.

## Issue Context
This was introduced in the README under the CCS build documentation.

## Fix Focus Areas
- README.md[125-125]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Tab rule unenforceable 🐞 Bug ☼ Reliability ⭐ New

Description

The new compliance check "Tabs in Assembly and C Source Files" requires that .asm/.inc/.c/.h files
contain no tab characters, but the repository already contains tabs in these file types. If enforced
as written, this will create perpetual compliance failures unless the rule is scoped to changed
lines/files or the repo is reformatted.

Code

pr_compliance_checklist.yaml[R206-213]

+  - title: "Tabs in Assembly and C Source Files"
+    compliance_label: true
+    objective: "Ensure assembly and C source files use spaces for indentation, not tab characters (best_practices.md §General Remarks)"
+    success_criteria: |
+      - "All .asm, .inc, .c, and .h source files use spaces only — no tab characters"
+      - "Exempt file types: linker.cmd, makefile, makefile_projectspec, makefile_ccs_bootimage_gen, and other build infrastructure files — tab characters are acceptable in those files"
+    failure_criteria: |
+      - "Any .asm, .inc, .c, or .h file containing tab characters"

Evidence

The compliance checklist adds a strict "no tabs" requirement for all .asm/.inc/.c/.h files, but
existing C source already uses tab indentation/alignment, meaning the repo does not satisfy the
requirement today.

pr_compliance_checklist.yaml[206-213]
examples/empty_c/firmware/main.c[8-11]
source/rpmsg/pru_rpmsg.c[34-41]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A new compliance rule bans tab characters in all `.asm`, `.inc`, `.c`, and `.h` files, but the existing repository already contains tabs in these file types. If the compliance system evaluates the whole repo or whole files, this requirement becomes impossible to satisfy without a repo-wide reformat.

## Issue Context
The rule text currently reads as a global property ("All .asm, .inc, .c, and .h source files...") and does not state that it applies only to files/lines modified in the PR.

## Fix Focus Areas
- pr_compliance_checklist.yaml[206-213]

## Desired fix
Choose one path and update the checklist text accordingly:
1) **Scope the rule to the PR diff** (recommended): change success/failure criteria to explicitly apply only to *new/modified lines* or *files changed in the PR*.
2) **Repo-wide cleanup**: perform a repo-wide conversion of tabs to spaces in all affected source files *before* enabling the global requirement.
3) **Defer/soften enforcement**: make it informational until cleanup is completed.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Broken docs/... links ☑ 📘 Rule violation ≡ Correctness

Description

docs/open_pru_create_new_mcuplus_project.md links to docs/open_pru_create_new_project.md and
docs/open_pru_organization.md, which will resolve to docs/docs/... and break when rendered. This
violates the requirement for portable, correct doc paths.

Code

docs/open_pru_create_new_mcuplus_project.md[R12-13]

+First, create the new PRU firmware project by completing
+[Creating a New Project in the OpenPRU Repo](docs/open_pru_create_new_project.md).

Evidence

PR Compliance ID 24 requires correct, portable link paths. The added links use a docs/ prefix from
within a docs/ file, creating incorrect relative paths.

docs/open_pru_create_new_mcuplus_project.md[12-13]
docs/open_pru_create_new_mcuplus_project.md[55-56]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/open_pru_create_new_mcuplus_project.md` uses `docs/...` relative links even though it is already under `docs/`, resulting in broken `docs/docs/...` paths.
## Issue Context
These links should be relative to the current file (for example, `./open_pru_create_new_project.md`).
## Fix Focus Areas
- docs/open_pru_create_new_mcuplus_project.md[12-13]
- docs/open_pru_create_new_mcuplus_project.md[55-56]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (4)

4. e.g. and tabs used 📘 Rule violation ⚙ Maintainability

Description

The updated docs/open_pru_organization.md uses disallowed shorthand (e.g.) and introduces tab
characters in the code block indentation. This violates the repo-wide terminology/whitespace hygiene
requirements.

Code

docs/open_pru_organization.md[R17-23]

getting started & training labs
+	Projects sit either directly under academy/ or under a topic subdirectory:
+	  academy/<project>              (e.g., getting_started_labs)
+	  academy/<topic>/<project>      (e.g., mac/mac_multiply, uart/uart_echo)
+	academy/makefile lists entries as <topic>/<project> for topic projects
+	and as <project> for top-level projects. There is no intermediate
+	per-topic makefile.

Evidence

PR Compliance ID 19 forbids e.g. in favor of “for example” and disallows non-space whitespace
characters like tabs. The added lines include both e.g., and tab-indented text.

docs/open_pru_organization.md[17-23]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The updated documentation contains `e.g.` and uses tab characters for indentation.
## Issue Context
Repo terminology and whitespace hygiene rules require “for example” instead of `e.g.` and spaces instead of tabs.
## Fix Focus Areas
- docs/open_pru_organization.md[17-23]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. ../docs/open_pru_organization.md bad link 📘 Rule violation ⚙ Maintainability

Description

best_practices.md links to ../docs/open_pru_organization.md, which resolves outside the repo
root from this file location and will break navigation. This violates the requirement that
documentation links be portable and correctly pathed.

Code

best_practices.md[R499-500]

+See [docs/open_pru_organization.md](../docs/open_pru_organization.md) for the
+authoritative project and repository layout.

Evidence

PR Compliance ID 25 requires documentation links to use correct, portable paths. The added link in
best_practices.md uses ../docs/... even though best_practices.md is at the repo root, so the
referenced path does not match the actual location.

best_practices.md[499-500]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`best_practices.md` contains a broken/incorrect relative link to `docs/open_pru_organization.md`.
## Issue Context
`best_practices.md` is in the repository root, so linking to `../docs/...` points outside the repo root.
## Fix Focus Areas
- best_practices.md[499-500]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. docs/-prefixed links in docs ☑ 📘 Rule violation ⚙ Maintainability

Description

docs/open_pru_create_new_project.md uses docs/...-prefixed relative links even though the file
itself is already under docs/, producing broken docs/docs/... paths. This violates the
requirement that documentation links be portable and correctly pathed.

Code

docs/open_pru_create_new_project.md[R24-28]

+### Set up the repo
+
+Before creating a new OpenPRU project, set up the OpenPRU repo by following the
+steps at [Getting Started with OpenPRU](docs/getting_started.md).
+

Evidence

PR Compliance ID 25 requires documentation links to match correct paths. In
docs/open_pru_create_new_project.md, the new link target includes an extra docs/ prefix, which
will not resolve correctly from within the docs/ directory.

docs/open_pru_create_new_project.md[24-28]
docs/open_pru_create_new_project.md[169-172]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Relative links inside `docs/open_pru_create_new_project.md` incorrectly include a leading `docs/`, causing broken `docs/docs/...` paths.
## Issue Context
Because the file is already located under `docs/`, links to other docs should typically be `./<file>.md` (or just `<file>.md`).
## Fix Focus Areas
- docs/open_pru_create_new_project.md[24-28]
- docs/open_pru_create_new_project.md[169-172]
- docs/open_pru_create_new_project.md[446-449]
- docs/open_pru_create_new_project.md[471-474]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. Missing docs_ai runbooks 🐞 Bug ☼ Reliability

Description

The PR adds contribution guidance and compliance checks that require docs_ai/ runbooks (e.g.,
docs_ai/task_create_project.md), but the repository contains no docs_ai/ directory, making the
requirement impossible to satisfy. This can confuse contributors and can also break any automated
enforcement that assumes those files exist.

Code

docs/contributing.md[R43-56]

+### Update AI-agent documentation
+
+If your PR changes any of the following, check whether `docs_ai/` needs
+updating before submitting:
+
+* Project directory structure or file naming conventions
+* Makefile patterns (project `makefile`, core makefile, parent `makefile`)
+* CCS build infrastructure (`example.projectspec` patterns)
+* Adding support for a new device or board
+* Adding or removing a shared library in `source/`
+
+If the existing runbooks in `docs_ai/` still accurately describe the patterns
+after your change, no update is needed. If they no longer match, update the
+relevant runbook(s) as part of the same PR.

Evidence

docs/contributing.md newly instructs contributors to update docs_ai/, and
pr_compliance_checklist.yaml introduces compliance criteria that reference specific docs_ai/...
files; however, no such runbooks are present in the repository contents of this PR.

docs/contributing.md[43-56]
pr_compliance_checklist.yaml[194-204]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The documentation and compliance checklist reference a `docs_ai/` directory and specific runbooks that are not present in the repo, making the new requirements non-actionable.
## Issue Context
Either the PR must introduce the referenced `docs_ai/` directory + the runbooks it names, or the contributing guidelines/compliance checks must be updated to reference documentation that actually exists.
## Fix Focus Areas
- docs/contributing.md[43-56]
- pr_compliance_checklist.yaml[194-204]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

8. Drift check too broad 🐞 Bug ⚙ Maintainability ⭐ New

Description

The "Contributing Requirements Drift" success criteria triggers on any edit to docs/contributing.md,
even typo/format-only changes, forcing unrelated edits to pr_compliance_checklist.yaml. This does
not match the stated objective of syncing only when contribution requirements change and will cause
unnecessary churn.

Code

pr_compliance_checklist.yaml[R185-192]

+  - title: "Contributing Requirements Drift"
+    compliance_label: true
+    objective: "Keep pr_compliance_checklist.yaml in sync when contribution requirements change in docs/contributing.md"
+    success_criteria: |
+      - "If docs/contributing.md was not modified, this check is not applicable"
+      - "If docs/contributing.md was modified, pr_compliance_checklist.yaml was also modified in the same PR"
+    failure_criteria: |
+      - "PR modifies docs/contributing.md without a corresponding change to pr_compliance_checklist.yaml"

Evidence

The objective says to sync the checklist when requirements change, but the success criteria requires
checklist edits whenever docs/contributing.md is modified at all.

pr_compliance_checklist.yaml[185-192]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The drift compliance rule currently requires updating `pr_compliance_checklist.yaml` whenever `docs/contributing.md` is modified, regardless of whether any contribution requirements changed. This will add friction to routine doc fixes.

## Issue Context
Objective is narrower than the trigger condition in success criteria.

## Fix Focus Areas
- pr_compliance_checklist.yaml[185-192]

## Desired fix
Adjust the success/failure criteria to better match the objective, e.g.:
- Make it a **manual-review** item rather than an automatic condition.
- Reword criteria to apply when **requirements/checklists change** (acknowledging automation limits).
- Or remove the check and rely on reviewer guidance in `docs/contributing.md`.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

9. Training URLs exceed line limits 📘 Rule violation ⚙ Maintainability

Description

The newly added Training links are extremely long single-line URLs, which hurts markdown readability
and violates the render-stability line-length guidance. Consider using reference-style links or
otherwise formatting to keep lines within the documented limits.

Code

README.md[R59-62]

+TI provides additional training for programming the PRU subsystem in
+processor-specific academies. The currently published PRU Academies are:
+[PRU Academy for AM243x](https://dev.ti.com/tirex/explore/node?isTheia=false&node=A__AB.mSUi9ihL.a5hIt1grfw__AM24X-ACADEMY__ZPSnq-h__LATEST)  
+[PRU Academy for AM64x](https://dev.ti.com/tirex/explore/node?isTheia=false&node=A__AB.mSUi9ihL.a5hIt1grfw__AM64-ACADEMY__WI1KRXP__LATEST)  

Evidence

PR Compliance ID 27 requires documentation to be render-stable and to keep lines within the
documented limits (about 79 chars) by reflowing where needed. The added markdown link lines contain
very long URLs on a single line.

README.md[59-62]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`README.md` adds very long inline URLs in the Training section, creating overly long lines.
## Issue Context
The docs compliance guidance asks to keep markdown lines reasonably short for stable rendering and reviewability.
## Fix Focus Areas
- README.md[59-62]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

10. e.g., used in create-project doc 📘 Rule violation ⚙ Maintainability

Description

The updated document uses the disallowed abbreviation e.g., instead of for example. This
violates the repository text standardization requirement.

Code

docs/open_pru_create_new_project.md[R247-251]

+> [!NOTE]
+> Update the path to match your project's actual MCU+ directory structure.
+> Some projects place MCU+ code under `mcuplus/<board>/` (e.g., `examples/empty`);
+> others place it directly under `<board>/` at the project root
+> (e.g., `academy/intc/intc_mcu`).

Evidence

PR Compliance ID 20 prohibits e.g. in repository text and requires using for example instead.
The cited lines include e.g., in the NOTE block.

docs/open_pru_create_new_project.md[247-251]
docs/open_pru_create_new_project.md[309-311]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/open_pru_create_new_project.md` contains `e.g.,` which is disallowed.
## Issue Context
The repository documentation standard requires `for example` instead of `e.g.`.
## Fix Focus Areas
- docs/open_pru_create_new_project.md[247-251]
- docs/open_pru_create_new_project.md[309-311]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Results up to commit N/A

🐞 Bugs (1) 📘 Rule violations (4) 📎 Requirement gaps (0)

1. Broken docs/... links ☑ 📘 Rule violation ≡ Correctness

Description

docs/open_pru_create_new_mcuplus_project.md links to docs/open_pru_create_new_project.md and
docs/open_pru_organization.md, which will resolve to docs/docs/... and break when rendered. This
violates the requirement for portable, correct doc paths.

Code

docs/open_pru_create_new_mcuplus_project.md[R12-13]

+First, create the new PRU firmware project by completing
+[Creating a New Project in the OpenPRU Repo](docs/open_pru_create_new_project.md).

Evidence

PR Compliance ID 24 requires correct, portable link paths. The added links use a docs/ prefix from
within a docs/ file, creating incorrect relative paths.

docs/open_pru_create_new_mcuplus_project.md[12-13]
docs/open_pru_create_new_mcuplus_project.md[55-56]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/open_pru_create_new_mcuplus_project.md` uses `docs/...` relative links even though it is already under `docs/`, resulting in broken `docs/docs/...` paths.
## Issue Context
These links should be relative to the current file (for example, `./open_pru_create_new_project.md`).
## Fix Focus Areas
- docs/open_pru_create_new_mcuplus_project.md[12-13]
- docs/open_pru_create_new_mcuplus_project.md[55-56]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. e.g. and tabs used 📘 Rule violation ⚙ Maintainability

Description

The updated docs/open_pru_organization.md uses disallowed shorthand (e.g.) and introduces tab
characters in the code block indentation. This violates the repo-wide terminology/whitespace hygiene
requirements.

Code

docs/open_pru_organization.md[R17-23]

getting started & training labs
+	Projects sit either directly under academy/ or under a topic subdirectory:
+	  academy/<project>              (e.g., getting_started_labs)
+	  academy/<topic>/<project>      (e.g., mac/mac_multiply, uart/uart_echo)
+	academy/makefile lists entries as <topic>/<project> for topic projects
+	and as <project> for top-level projects. There is no intermediate
+	per-topic makefile.

Evidence

PR Compliance ID 19 forbids e.g. in favor of “for example” and disallows non-space whitespace
characters like tabs. The added lines include both e.g., and tab-indented text.

docs/open_pru_organization.md[17-23]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The updated documentation contains `e.g.` and uses tab characters for indentation.
## Issue Context
Repo terminology and whitespace hygiene rules require “for example” instead of `e.g.` and spaces instead of tabs.
## Fix Focus Areas
- docs/open_pru_organization.md[17-23]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. ../docs/open_pru_organization.md bad link 📘 Rule violation ⚙ Maintainability

Description

best_practices.md links to ../docs/open_pru_organization.md, which resolves outside the repo
root from this file location and will break navigation. This violates the requirement that
documentation links be portable and correctly pathed.

Code

best_practices.md[R499-500]

+See [docs/open_pru_organization.md](../docs/open_pru_organization.md) for the
+authoritative project and repository layout.

Evidence

PR Compliance ID 25 requires documentation links to use correct, portable paths. The added link in
best_practices.md uses ../docs/... even though best_practices.md is at the repo root, so the
referenced path does not match ...

[qodo-code-review]

Review Summary by Qodo

Update documentation for v2026.01.00 and add MCU+ project creation guide

📝 Documentation ✨ Enhancement

Walkthroughs

Description

• Remove outdated pru_dependencies scripts no longer maintained
• Update documentation for PRU Academy v2026.01.00 release
• Add new guide for creating MCU+ projects in OpenPRU repo
• Enhance contributing guidelines with AI enablement and detailed checklists
• Reorganize best practices documentation for PRU vs MCU+ host code
• Add Training section to README with links to PRU Academies

Diagram

flowchart LR
  A["v2026.01.00 Updates"] --> B["Remove pru_dependencies scripts"]
  A --> C["Update README & docs"]
  A --> D["New MCU+ guide"]
  A --> E["Enhanced contributing.md"]
  C --> F["Add Training section"]
  C --> G["Reorganize best practices"]
  D --> H["open_pru_create_new_mcuplus_project.md"]
  E --> I["AI documentation requirements"]
  E --> J["Detailed contribution checklists"]

Loading

File Changes

1. docs/pru_dependencies.bat 📝 Documentation +0/-255

Remove outdated Windows dependency installation script

docs/pru_dependencies.bat

---

2. docs/pru_dependencies.sh 📝 Documentation +0/-397

Remove outdated Linux dependency installation script

docs/pru_dependencies.sh

---

3. docs/pru_dependencies_readme.md 📝 Documentation +0/-129

Remove documentation for deprecated dependency scripts

docs/pru_dependencies_readme.md

---

View more (8)

4. README.md 📝 Documentation +52/-31

Add Training section and reorganize documentation structure

README.md

---

5. best_practices.md 📝 Documentation +42/-17

Separate PRU and MCU+ host C code best practices sections

best_practices.md

---

6. docs/contributing.md 📝 Documentation +157/-46

Restructure with detailed contribution workflows and AI enablement

docs/contributing.md

---

7. docs/open_pru_create_new_mcuplus_project.md 📝 Documentation +276/-0

Create comprehensive guide for adding MCU+ code to projects

docs/open_pru_create_new_mcuplus_project.md

---

8. docs/open_pru_create_new_project.md 📝 Documentation +386/-44

Expand with detailed steps, makefiles overview, and CCS configuration

docs/open_pru_create_new_project.md

---

9. docs/open_pru_organization.md 📝 Documentation +22/-1

Add project structure details and CCS file documentation

docs/open_pru_organization.md

---

10. imports.mak.default 📝 Documentation +4/-0

Add clarifying comments for GCC compiler path variables

imports.mak.default

---

11. pr_compliance_checklist.yaml 📝 Documentation +78/-1

Add new compliance checks for AI documentation and contribution requirements

pr_compliance_checklist.yaml

---

[qodo-code-review]

Persistent review updated to latest commit 350c701

[qodo-code-review]

Persistent review updated to latest commit ea4d39b

[qodo-code-review]

Persistent review updated to latest commit a2b1d71

[qodo-code-review]

Persistent review updated to latest commit a2b1d71

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (5) 📘 Rule violations (8) 📎 Requirement gaps (0)

1. e.g. used in open_pru_organization.md 📘 Rule violation ⚙ Maintainability ⭐ New

Description

New documentation text uses e.g. instead of the required phrasing for example. This violates the
repo documentation wording standard and reduces consistency across docs.

Code

docs/open_pru_organization.md[R18-20]

+	Projects sit either directly under academy/ or under a topic subdirectory:
+	  academy/<project>              (e.g., getting_started_labs)
+	  academy/<topic>/<project>      (e.g., mac/mac_multiply, uart/uart_echo)

Evidence

PR Compliance ID 9 requires documentation to use “for example” instead of “e.g.”. The added
repository layout examples in docs/open_pru_organization.md include e.g. in the new lines.

docs/open_pru_organization.md[18-20]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Documentation wording standard forbids `e.g.`; use `for example` instead.

## Issue Context
PR Compliance requires consistent phrasing across docs.

## Fix Focus Areas
- docs/open_pru_organization.md[18-20]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. e.g. used in open_pru_create_new_mcuplus_project.md 📘 Rule violation ⚙ Maintainability ⭐ New

Description

New text in docs/open_pru_create_new_mcuplus_project.md uses e.g. instead of the required `for
example`. This violates the documentation wording standard.

Code

docs/open_pru_create_new_mcuplus_project.md[R124-126]

+> Some projects place MCU+ code under `mcuplus/<board>/` (e.g., `examples/empty`);
+> others place it directly under `<board>/` at the project root
+> (e.g., `academy/intc/intc_mcu`).

Evidence

PR Compliance ID 9 requires documentation to use “for example” instead of “e.g.”. The added note in
the new file uses e.g. twice.

docs/open_pru_create_new_mcuplus_project.md[124-126]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`e.g.` appears in documentation, but the standard requires `for example`.

## Issue Context
This is part of the repo-wide documentation phrasing conventions.

## Fix Focus Areas
- docs/open_pru_create_new_mcuplus_project.md[124-126]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Tabs added in code block 📘 Rule violation ⚙ Maintainability

Description

New lines in docs/open_pru_organization.md use tab characters for indentation inside a code block,
which violates the repo formatting guidance that disallows tabs in source files. Tabs can render
inconsistently across editors and break formatting rules.

Code

docs/open_pru_organization.md[R18-23]

+	Projects sit either directly under academy/ or under a topic subdirectory:
+	  academy/<project>              (e.g., getting_started_labs)
+	  academy/<topic>/<project>      (e.g., mac/mac_multiply, uart/uart_echo)
+	academy/makefile lists entries as <topic>/<project> for topic projects
+	and as <project> for top-level projects. There is no intermediate
+	per-topic makefile.

Evidence

PR Compliance ID 15 forbids disallowed whitespace such as tabs. The added repository tree lines in
docs/open_pru_organization.md are indented with tabs (visible before the text in the fenced
block).

docs/open_pru_organization.md[18-23]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/open_pru_organization.md` adds tab-indented lines inside a fenced code block. Compliance requires avoiding tabs.
## Issue Context
Tabs render inconsistently and violate the repo formatting/whitespace requirements.
## Fix Focus Areas
- docs/open_pru_organization.md[18-23]
## Suggested approach
- Replace leading tab characters with spaces (e.g., 4-space indentation) while keeping the visual tree structure aligned.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (7)

4. Trailing space after Projects** 📘 Rule violation ⚙ Maintainability

Description

A trailing space was introduced at the end of the Using SDK with CCS Projects line, which can
cause inconsistent Markdown rendering and violates documentation hygiene. Trailing whitespace also
creates noisy diffs and can break strict linting.

Code

README.md[125]

+  MCU+ SDK documentation: **Developer Guides > Using SDK with CCS Projects** 

Evidence

PR Compliance ID 24 requires documentation to avoid trailing spaces for render stability.
README.md line 125 ends with trailing whitespace after **Using SDK with CCS Projects**, which is
visible in the modified line.

README.md[125-125]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A trailing space was added at the end of a Markdown line, which can cause inconsistent rendering and violates documentation hygiene requirements.
## Issue Context
This was introduced in the README under the CCS build documentation.
## Fix Focus Areas
- README.md[125-125]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Tab rule unenforceable 🐞 Bug ☼ Reliability

Description

The new compliance check "Tabs in Assembly and C Source Files" requires that .asm/.inc/.c/.h files
contain no tab characters, but the repository already contains tabs in these file types. If enforced
as written, this will create perpetual compliance failures unless the rule is scoped to changed
lines/files or the repo is reformatted.

Code

pr_compliance_checklist.yaml[R206-213]

+  - title: "Tabs in Assembly and C Source Files"
+    compliance_label: true
+    objective: "Ensure assembly and C source files use spaces for indentation, not tab characters (best_practices.md §General Remarks)"
+    success_criteria: |
+      - "All .asm, .inc, .c, and .h source files use spaces only — no tab characters"
+      - "Exempt file types: linker.cmd, makefile, makefile_projectspec, makefile_ccs_bootimage_gen, and other build infrastructure files — tab characters are acceptable in those files"
+    failure_criteria: |
+      - "Any .asm, .inc, .c, or .h file containing tab characters"

Evidence

The compliance checklist adds a strict "no tabs" requirement for all .asm/.inc/.c/.h files, but
existing C source already uses tab indentation/alignment, meaning the repo does not satisfy the
requirement today.

pr_compliance_checklist.yaml[206-213]
examples/empty_c/firmware/main.c[8-11]
source/rpmsg/pru_rpmsg.c[34-41]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A new compliance rule bans tab characters in all `.asm`, `.inc`, `.c`, and `.h` files, but the existing repository already contains tabs in these file types. If the compliance system evaluates the whole repo or whole files, this requirement becomes impossible to satisfy without a repo-wide reformat.
## Issue Context
The rule text currently reads as a global property ("All .asm, .inc, .c, and .h source files...") and does not state that it applies only to files/lines modified in the PR.
## Fix Focus Areas
- pr_compliance_checklist.yaml[206-213]
## Desired fix
Choose one path and update the checklist text accordingly:
1) **Scope the rule to the PR diff** (recommended): change success/failure criteria to explicitly apply only to *new/modified lines* or *files changed in the PR*.
2) **Repo-wide cleanup**: perform a repo-wide conversion of tabs to spaces in all affected source files *before* enabling the global requirement.
3) **Defer/soften enforcement**: make it informational until cleanup is completed.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

6. Broken docs/... links ☑ 📘 Rule violation ≡ Correctness

Description

docs/open_pru_create_new_mcuplus_project.md links to docs/open_pru_create_new_project.md and
docs/open_pru_organization.md, which will resolve to docs/docs/... and break when rendered. This
violates the requirement for portable, correct doc paths.

Code

docs/open_pru_create_new_mcuplus_project.md[R12-13]

+First, create the new PRU firmware project by completing
+[Creating a New Project in the OpenPRU Repo](docs/open_pru_create_new_project.md).

Evidence

PR Compliance ID 24 requires correct, portable link paths. The added links use a docs/ prefix from
within a docs/ file, creating incorrect relative paths.

docs/open_pru_create_new_mcuplus_project.md[12-13]
docs/open_pru_create_new_mcuplus_project.md[55-56]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/open_pru_create_new_mcuplus_project.md` uses `docs/...` relative links even though it is already under `docs/`, resulting in broken `docs/docs/...` paths.
## Issue Context
These links should be relative to the current file (for example, `./open_pru_create_new_project.md`).
## Fix Focus Areas
- docs/open_pru_create_new_mcuplus_project.md[12-13]
- docs/open_pru_create_new_mcuplus_project.md[55-56]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

7. e.g. and tabs used 📘 Rule violation ⚙ Maintainability

Description

The updated docs/open_pru_organization.md uses disallowed shorthand (e.g.) and introduces tab
characters in the code block indentation. This violates the repo-wide terminology/whitespace hygiene
requirements.

Code

docs/open_pru_organization.md[R17-23]

getting started & training labs
+	Projects sit either directly under academy/ or under a topic subdirectory:
+	  academy/<project>              (e.g., getting_started_labs)
+	  academy/<topic>/<project>      (e.g., mac/mac_multiply, uart/uart_echo)
+	academy/makefile lists entries as <topic>/<project> for topic projects
+	and as <project> for top-level projects. There is no intermediate
+	per-topic makefile.

Evidence

PR Compliance ID 19 forbids e.g. in favor of “for example” and disallows non-space whitespace
characters like tabs. The added lines include both e.g., and tab-indented text.

docs/open_pru_organization.md[17-23]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The updated documentation contains `e.g.` and uses tab characters for indentation.
## Issue Context
Repo terminology and whitespace hygiene rules require “for example” instead of `e.g.` and spaces instead of tabs.
## Fix Focus Areas
- docs/open_pru_organization.md[17-23]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

8. ../docs/open_pru_organization.md bad link 📘 Rule violation ⚙ Maintainability

Description

best_practices.md links to ../docs/open_pru_organization.md, which resolves outside the repo
root from this file location and will break navigation. This violates the requirement that
documentation links be portable and correctly pathed.

Code

best_practices.md[R499-500]

+See [docs/open_pru_organization.md](../docs/open_pru_organization.md) for the
+authoritative project and repository layout.

Evidence

PR Compliance ID 25 requires documentation links to use correct, portable paths. The added link in
best_practices.md uses ../docs/... even though best_practices.md is at the repo root, so the
referenced path does not match the actual location.

best_practices.md[499-500]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`best_practices.md` contains a broken/incorrect relative link to `docs/open_pru_organization.md`.
## Issue Context
`best_practices.md` is in the repository root, so linking to `../docs/...` points outside the repo root.
## Fix Focus Areas
- best_practices.md[499-500]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

9. docs/-prefixed links in docs ☑ 📘 Rule violation ⚙ Maintainability

Description

docs/open_pru_create_new_project.md uses docs/...-prefixed relative links even though the file
itself is already under docs/, producing broken docs/docs/... paths. This violates the
requirement that documentation links be portable and correctly pathed.

Code

docs/open_pru_create_new_project.md[R24-28]

+### Set up the repo
+
+Before creating a new OpenPRU project, set up the OpenPRU repo by following the
+steps at [Getting Started with OpenPRU](docs/getting_started.md).
+

Evidence

PR Compliance ID 25 requires documentation links to match correct paths. In
docs/open_pru_create_new_project.md, the new link target includes an extra docs/ prefix, which
will not resolve correctly from within the docs/ directory.

docs/open_pru_create_new_project.md[24-28]
docs/open_pru_create_new_project.md[169-172]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Relative links inside `docs/open_pru_create_new_project.md` incorrectly include a leading `docs/`, causing broken `docs/docs/...` paths.
## Issue Context
Because the file is already located under `docs/`, links to other docs should typically be `./<file>.md` (or just `<file>.md`).
## Fix Focus Areas
- docs/open_pru_create_new_project.md[24-28]
- docs/open_pru_create_new_project.md[169-172]
- docs/open_pru_create_new_project.md[446-449]
- docs/open_pru_create_new_project.md[471-474]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

10. Missing docs_ai runbooks 🐞 Bug ☼ Reliability

Description

The PR adds contribution guidance and compliance checks that require docs_ai/ runbooks (e.g.,
docs_ai/task_create_project.md), but the repository contains no docs_ai/ directory, making the
requirement impossible to satisfy. This can confuse contributors and can also break any automated
enforcement that assumes those files exist.

Code

docs/contributing.md[R43-56]

+### Update AI-agent documentation
+
+If your PR changes any of the following, check whether `docs_ai/` needs
+updating before submitting:
+
+* Project directory structure or file naming conventions
+* Makefile patterns (project `makefile`, core makefile, parent `makefile`)
+* CCS build infrastructure (`example.projectspec` patterns)
+* Adding support for a new device or board
+* Adding or removing a shared library in `source/`
+
+If the existing runbooks in `docs_ai/` still accurately describe the patterns
+after your change, no update is needed. If they no longer match, update the
+relevant runbook(s) as part of the same PR.

Evidence

docs/contributing.md newly instructs contributors to update docs_ai/, and
pr_compliance_checklist.yaml introduces compliance criteria that reference specific docs_ai/...
files; however, no such runbooks are present in the repository contents of this PR.

docs/contributing.md[43-56]
pr_compliance_checklist.yaml[194-204]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The documentation and compliance checklist reference a `docs_ai/` directory and specific runbooks that are not present in the repo, making the new requirements non-actionable.
## Issue Context
Either the PR must introduce the referenced `docs_ai/` directory + the runbooks it names, or the contributing guidelines/compliance checks must be updated to reference documentation that actually exists.
## Fix Focus Areas
- docs/contributing.md[43-56]
- pr_compliance_checklist.yaml[194-204]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

11. Contributing TOC formatting broken 🐞 Bug ⚙ Maintainability

Description

The new TOC entries for the "Reference" sections in docs/contributing.md are not formatted as list
items and lack Markdown line breaks, so they will render as a single wrapped paragraph instead of a
readable TOC. This makes navigation significantly harder and inconsistent with the rest of the TOC
formatting.

Code

docs/contributing.md[R15-19]

+[Reference: project documentation](#reference-project-documentation):
+[Project-level readme](#project-level-readme),
+[Update the section-level readme](#update-the-section-level-readme)
+[Reference: build verification](#reference-build-verification):
+[Testing the build](#testing-the-build)

Evidence

The TOC lines for the reference subsections are plain lines without list markers or trailing
double-spaces, unlike the earlier TOC entries that use proper line breaks; in standard Markdown,
those lines will be merged into one paragraph.

docs/contributing.md[9-20]
docs/contributing.md[15-19]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The TOC in `docs/contributing.md` renders incorrectly because several entries aren’t formatted as a list and don’t include Markdown line breaks.
### Issue Context
The TOC currently mixes `two-space line breaks` and plain lines with colons/commas, which Markdown will fold into a single paragraph.
### Fix Focus Areas
- docs/contributing.md[9-20]
### Suggested change
Convert the TOC to a proper bulleted list with nested bullets for the reference subsections, e.g.:
- [Reference: project documentation](#reference-project-documentation)
- [Project-level readme](#project-level-readme)
- [Update the section-level readme](#update-the-section-level-readme)
- [Reference: build verification](#reference-build-verification)
- [Testing the build](#testing-the-build)
(Or add explicit line breaks consistently, but a list is clearer.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

12. Drift check too broad 🐞 Bug ⚙ Maintainability

Description

The "Contributing Requirements Drift" success criteria triggers on any edit to docs/contributing.md,
even typo/format-only changes, forcing unrelated edits to pr_compliance_checklist.yaml. This does
not match the stated objective of syncing only when contribution requirements change and will cause
unnecessary churn.

Code

pr_compliance_checklist.yaml[R185-192]

+  - title: "Contributing Requirements Drift"
+    compliance_label: true
+    objective: "Keep pr_compliance_checklist.yaml in sync when contribution requirements change in docs/contributing.md"
+    success_criteria: |
+      - "If docs/contributing.md was not modified, this check is not applicable"
+      - "If docs/contributing.md was modified, pr_compliance_checklist.yaml was also modified in the same PR"
+    failure_criteria: |
+      - "PR modifies docs/contributing.md without a corresponding change to pr_compliance_checklist.yaml"

Evidence

The objective says to sync the checklist when requirements change, but the success criteria requires
checklist edits whenever docs/contributing.md is modified at all.

pr_compliance_checklist.yaml[185-192]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The drift compliance rule currently requires updating `pr_compliance_checklist.yaml` whenever `docs/contributing.md` is modified, regardless of whether any contribution requirements changed. This will add friction to routine doc fixes.
## Issue Context
Objective is narrower than the trigger condition in success criteria.
## Fix Focus Areas
- pr_compliance_checklist.yaml[185-192]
## Desired fix
Adjust the success/failure criteria to better match the objective, e.g.:
- Make it a **manual-review** item rather than an automatic condition.
- Reword criteria to apply when **requirements/checklists change** (acknowledging automation limits).
- Or remove the check and rely on reviewer guidance in `docs/contributing.md`.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

13. Training URLs exceed line limits 📘 Rule violation ⚙ Maintainability

Description

The newly added Training links are extremely long single-line URLs, which hurts markdown readability
and violates the render-stability line-length guidance. Consider using reference-style links or
otherwise formatting to keep lines within the documented limits.

Code

README.md[R59-62]

+TI provides additional training for programming the PRU subsystem in
+processor-specific academies. The currently published PRU Academies are:
+[PRU Academy for AM243x](https://dev.ti.com/tirex/explore/node?isTheia=false&node=A__AB.mSUi9ihL.a5hIt1grfw__AM24X-ACADEMY__ZPSnq-h__LATEST)  
+[PRU Academy for AM64x](https://dev.ti.com/tirex/explore/node?isTheia=false&node=A__AB.mSUi9ihL.a5hIt1grfw__AM64-ACADEMY__WI1KRXP__LATEST)  

Evidence

PR Compliance ID 27 requires documentation to be render-stable and to keep lines within the
documented limits (about 79 chars) by reflowing where needed. The added markdown link lines contain
very long URLs on a single line.

README.md[59-62]
Best Practice: Learned patterns

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`README.md` adds very long inline URLs in the Training section, creating overly long lines.
## Issue Context
The docs compliance guidance asks to keep markdown lines reasonably short for stable rendering and reviewability.
## Fix Focus Areas
- README.md[59-62]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (1)

14. e.g., used in create-project doc 📘 Rule violation ⚙ Maintainability

Description

The updated document uses the disallowed abbreviation e.g., instead of for example. This
violates the repository text standardization requirement.

Code

docs/open_pru_create_new_project.md[R247-251]

+> [!NOTE]
+> Update the path to match your project's actual MCU+ directory structure.
+> Some projects place MCU+ code under `mcuplus/<board>/` (e.g., `examples/empty`);
+> others place it directly under `<board>/` at the project root
+> (e.g., `academy/intc/intc_mcu`).

Evidence

PR Compliance ID 20 prohibits e.g. in repository text and requires using for example instead.
The cited lines include e.g., in the NOTE block.

docs/open_pru_create_new_project.md[247-251]
docs/open_pru_create_new_project.md[309-311]
Best Practice: Repository guidelines

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/open_pru_create_new_project.md` contains `e.g.,` which is disallowed.
## Issue Context
The repository documentation standard requires `for example` instead of `e.g.`.
## Fix Focus Areas
- docs/open_pru_create_new_project.md[247-251]
- docs/open_pru_create_new_project.md[309-311]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

15. Ambiguous grep command 🐞 Bug ☼ Reliability ⭐ New

Description

The new project-creation docs say to run grep -r empty without an explicit search path, which is
easy to mis-run (or behave differently across environments) despite the intent being “search this
directory tree”.

Code

docs/open_pru_create_new_project.md[R188-194]

+```
+$ cd /path/to/open-pru/examples/<project_name>
+# search for filenames from the template project, in this case `empty`
+$ find -name "*empty*"
+# search for mentions within files
+$ grep -r empty
+```

Evidence

Both new-project guides include the same snippet: after cd .../examples/<project_name>, they
instruct “search for mentions within files” and then show grep -r empty without . or another
explicit root. Using grep -r empty . (or similar) makes the command’s scope unambiguous and
consistent.

docs/open_pru_create_new_project.md[188-194]
docs/open_pru_create_new_mcuplus_project.md[88-94]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The docs use `grep -r empty` without specifying a search root, which can be confusing and less portable.

## Issue Context
The surrounding text indicates the intent is to recursively search the current project directory for references.

## Fix Focus Areas
- docs/open_pru_create_new_project.md[188-194]
- docs/open_pru_create_new_mcuplus_project.md[88-94]

## Suggested fix
Change the command to an explicit path, for example:
- `grep -R "empty" .`
Optionally also update `find -name "*empty*"` to `find . -name "*empty*"` for consistency.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[pratheesh-ti]

Looks good