Docs: Incorrect specification line numbers in acms.uko module #9067

Open
opened 2026-04-14 07:02:39 +00:00 by HAL9000 · 2 comments
Owner

Metadata

  • Commit message: docs(acms/uko): fix incorrect specification line number references
  • Branch name: docs/acms-uko-fix-spec-line-number-references

Background and Context

The acms.uko module contains several files with comments and docstrings that reference line numbers in docs/specification.md. These line number references are incorrect — the content at the referenced lines does not match the feature being documented.

This was discovered during a bug hunt sweep of the acms.uko module. The specification is a large, evolving document (~46,000+ lines), and line numbers shift as content is added or reorganized. The references were likely accurate at the time of writing but have since drifted out of sync.

Files with incorrect references:

  • src/cleveragents/acms/uko/detail_level_maps.py
  • src/cleveragents/acms/uko/layer3_java.py
  • src/cleveragents/acms/uko/layer3_py.py
  • src/cleveragents/acms/uko/layer3_rs.py
  • src/cleveragents/acms/uko/layer3_ts.py
  • src/cleveragents/acms/uko/vocabularies.py

To Reproduce:

  1. Open any of the files listed above.
  2. Note the line numbers referenced in the docstrings and comments (e.g., Based on docs/specification.md ~lines 24923-25027).
  3. Open docs/specification.md and navigate to the referenced lines.
  4. Observe that the content at the referenced lines does not match the feature being documented.

Expected Behavior

When this issue is complete, all line number references in the acms.uko module source files point to the correct sections of docs/specification.md. Developers navigating from source code to the specification can find the relevant section immediately without manual searching.

Acceptance Criteria

  • All line number references in detail_level_maps.py are verified and corrected to point to the correct specification sections.
  • All line number references in layer3_java.py are verified and corrected.
  • All line number references in layer3_py.py are verified and corrected.
  • All line number references in layer3_rs.py are verified and corrected.
  • All line number references in layer3_ts.py are verified and corrected.
  • All line number references in vocabularies.py are verified and corrected.
  • Each corrected reference is validated by navigating to the referenced line in docs/specification.md and confirming the content matches the documented feature.
  • No functional code changes are made — this is a documentation-only fix.

Subtasks

  • Audit detail_level_maps.py — identify all spec line references and verify each against docs/specification.md; update incorrect references.
  • Audit layer3_java.py — identify all spec line references and verify each; update incorrect references.
  • Audit layer3_py.py — identify all spec line references and verify each; update incorrect references.
  • Audit layer3_rs.py — identify all spec line references and verify each; update incorrect references.
  • Audit layer3_ts.py — identify all spec line references and verify each; update incorrect references.
  • Audit vocabularies.py — identify all spec line references and verify each; update incorrect references.
  • Open a PR with only documentation/comment changes; no logic changes.
  • PR description lists each file changed and the before/after line numbers for each corrected reference.

Definition of Done

This issue should be closed when:

  • All six files have been audited and all incorrect specification line number references have been corrected.
  • A PR has been merged to master containing only comment/docstring changes.
  • No regressions are introduced (all nox stages pass).

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit message:** `docs(acms/uko): fix incorrect specification line number references` - **Branch name:** `docs/acms-uko-fix-spec-line-number-references` ## Background and Context The `acms.uko` module contains several files with comments and docstrings that reference line numbers in `docs/specification.md`. These line number references are incorrect — the content at the referenced lines does not match the feature being documented. This was discovered during a bug hunt sweep of the `acms.uko` module. The specification is a large, evolving document (~46,000+ lines), and line numbers shift as content is added or reorganized. The references were likely accurate at the time of writing but have since drifted out of sync. **Files with incorrect references:** - `src/cleveragents/acms/uko/detail_level_maps.py` - `src/cleveragents/acms/uko/layer3_java.py` - `src/cleveragents/acms/uko/layer3_py.py` - `src/cleveragents/acms/uko/layer3_rs.py` - `src/cleveragents/acms/uko/layer3_ts.py` - `src/cleveragents/acms/uko/vocabularies.py` **To Reproduce:** 1. Open any of the files listed above. 2. Note the line numbers referenced in the docstrings and comments (e.g., `Based on docs/specification.md ~lines 24923-25027`). 3. Open `docs/specification.md` and navigate to the referenced lines. 4. Observe that the content at the referenced lines does not match the feature being documented. ## Expected Behavior When this issue is complete, all line number references in the `acms.uko` module source files point to the correct sections of `docs/specification.md`. Developers navigating from source code to the specification can find the relevant section immediately without manual searching. ## Acceptance Criteria - [ ] All line number references in `detail_level_maps.py` are verified and corrected to point to the correct specification sections. - [ ] All line number references in `layer3_java.py` are verified and corrected. - [ ] All line number references in `layer3_py.py` are verified and corrected. - [ ] All line number references in `layer3_rs.py` are verified and corrected. - [ ] All line number references in `layer3_ts.py` are verified and corrected. - [ ] All line number references in `vocabularies.py` are verified and corrected. - [ ] Each corrected reference is validated by navigating to the referenced line in `docs/specification.md` and confirming the content matches the documented feature. - [ ] No functional code changes are made — this is a documentation-only fix. ## Subtasks - [ ] Audit `detail_level_maps.py` — identify all spec line references and verify each against `docs/specification.md`; update incorrect references. - [ ] Audit `layer3_java.py` — identify all spec line references and verify each; update incorrect references. - [ ] Audit `layer3_py.py` — identify all spec line references and verify each; update incorrect references. - [ ] Audit `layer3_rs.py` — identify all spec line references and verify each; update incorrect references. - [ ] Audit `layer3_ts.py` — identify all spec line references and verify each; update incorrect references. - [ ] Audit `vocabularies.py` — identify all spec line references and verify each; update incorrect references. - [ ] Open a PR with only documentation/comment changes; no logic changes. - [ ] PR description lists each file changed and the before/after line numbers for each corrected reference. ## Definition of Done This issue should be closed when: - All six files have been audited and all incorrect specification line number references have been corrected. - A PR has been merged to `master` containing only comment/docstring changes. - No regressions are introduced (all `nox` stages pass). --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.3.0 milestone 2026-04-14 07:22:25 +00:00
Author
Owner

🔍 Triage Decision — [AUTO-OWNR-2]

Status: VERIFIED

MoSCoW: Could have
Priority: Low
Milestone: v3.3.0

Reasoning: Incorrect specification line numbers in the acms.uko module docs are a minor accuracy issue that could confuse developers referencing the spec. Low priority but worth fixing when convenient.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

## 🔍 Triage Decision — [AUTO-OWNR-2] **Status:** ✅ VERIFIED **MoSCoW:** Could have **Priority:** Low **Milestone:** v3.3.0 **Reasoning:** Incorrect specification line numbers in the `acms.uko` module docs are a minor accuracy issue that could confuse developers referencing the spec. Low priority but worth fixing when convenient. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Author
Owner

Triage: Verified [AUTO-OWNR-1]

Valid documentation bug: Incorrect specification line numbers in acms.uko module. Line numbers shift with edits and become misleading — per CONTRIBUTING.md, code should be referenced by logical location, not line numbers.

Assigning to v3.3.0 as this is a documentation quality issue. Priority Low — documentation accuracy issue.

MoSCoW: Could Have — fixing incorrect line number references is good practice but not blocking.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Triage: Verified** [AUTO-OWNR-1] Valid documentation bug: Incorrect specification line numbers in `acms.uko` module. Line numbers shift with edits and become misleading — per CONTRIBUTING.md, code should be referenced by logical location, not line numbers. Assigning to **v3.3.0** as this is a documentation quality issue. Priority **Low** — documentation accuracy issue. MoSCoW: **Could Have** — fixing incorrect line number references is good practice but not blocking. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#9067
No description provided.