Move lint lessons to their own Lesson concept (ADR-0265)

jared commented

2026-10-02 16:56:50 +00:00

Owner

Problem

ADR-0265 makes lint lessons their own concept.
The lesson code still lives under Gate.
OsSdlc::Gate classes own the lesson selection, ordering and rendering today.

Approach

Pure rename.
Relay keeps selection, ordering and rendering together.

Required work:

Move presenter/gate/lesson_relay.rb to presenter/lesson/relay.rb as OsSdlc::Lesson::Relay — check: present Lesson::Relay in plugins/os-sdlc/lib/os_sdlc/presenter/lesson/relay.rb
Move adapter/gate/lesson_library.rb to adapter/lesson/library.rb as OsSdlc::Lesson::Library — check: present Lesson::Library in plugins/os-sdlc/lib/os_sdlc/adapter/lesson/library.rb
Move the two tests to tests/presenter/lesson/relay_test.rb and tests/adapter/lesson/library_test.rb — check: present Lesson::Relay in plugins/os-sdlc/tests/presenter/lesson/relay_test.rb
Update the only caller command/gate/run.rb:100-103 to build Lesson::Library with the plugin lesson directory — check: absent Gate::LessonRelay in plugins/os-sdlc/lib/os_sdlc/command/gate/run.rb
Remove ArtifactDir#lint_lessons — check: absent lint_lessons in plugins/os-sdlc/lib/os_sdlc/model/project/artifact_dir.rb
Remove the lint_lessons use from the gate run — check: absent lint_lessons in plugins/os-sdlc/lib/os_sdlc/command/gate/run.rb
Remove the lint_lessons test — check: absent lint_lessons in plugins/os-sdlc/tests/model/project/artifact_dir_test.rb
Add a lesson step to skills/mine-lints/references/implement-cop.md with the ADR-0265 section list: The signal; What it is a sign of; Why it matters; Your decision; Correction; Example — check: present What it is a sign of in plugins/os-sdlc/skills/mine-lints/references/implement-cop.md

Lesson text uses generic names (for example orders_dataset, Order), never names from this codebase.
Lessons ship with the plugin (ADR-0266, amends ADR-0265): Lesson::Library reads from plugins/os-sdlc/lint-lessons/<kebab-cop-name>.md, found through PluginRoot::PATH.
The gate no longer reads the project's .sdlc/lint-lessons/.
Remove ArtifactDir#lint_lessons (model/project/artifact_dir.rb), its use in command/gate/run.rb, and its test in tests/model/project/artifact_dir_test.rb.
command/gate/run.rb builds the library with the plugin path.

Ruling (user, 2026-10-02): lint lessons are global and not project specific; project-specific lessons are deferred (YAGNI). Recorded in ADR-0266, which amends ADR-0265.

Order: this ticket comes before the three cop tickets (#909, #910, #911); they depend on it.

Acceptance criteria

Given the gate runs on a file with a cop offense that has a lesson file, when the gate replies, then the lesson renders as before.
Given the codebase, when Gate::LessonRelay and Gate::LessonLibrary are searched, then no reference remains.
Given the gate runs in a project with no .sdlc/lint-lessons/ directory and a cop offense that has a plugin lesson file, when the gate replies, then the lesson renders.
Given the implement-cop reference, when a cop author reads it, then it names the lesson step, the plugin lesson path, and the six ADR-0265 sections in order.

Owner sketch

module OsSdlc::Lesson
  class Relay; end
  class Library; end
end

Origin

Trigger: ADR-0265 (commit 16092949) decided that lint lessons are a concept.
Improvised this session: none
Chain: lesson code under Gate ← lessons predate ADR-0265 (DESIGN: docs/adr/0265-*)
Root candidate: none
Where: plugins/os-sdlc/lib/os_sdlc/presenter/gate/lesson_relay.rb, adapter/gate/lesson_library.rb, command/gate/run.rb
Session: 9ee7805f-a4e4-470e-af50-5020e5c524a4
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/9ee7805f-a4e4-470e-af50-5020e5c524a4.jsonl

## Problem ADR-0265 makes lint lessons their own concept. The lesson code still lives under `Gate`. `OsSdlc::Gate` classes own the lesson selection, ordering and rendering today. ## Approach Pure rename. `Relay` keeps selection, ordering and rendering together. Required work: 1. Move `presenter/gate/lesson_relay.rb` to `presenter/lesson/relay.rb` as `OsSdlc::Lesson::Relay` — check: present `Lesson::Relay` in `plugins/os-sdlc/lib/os_sdlc/presenter/lesson/relay.rb` 2. Move `adapter/gate/lesson_library.rb` to `adapter/lesson/library.rb` as `OsSdlc::Lesson::Library` — check: present `Lesson::Library` in `plugins/os-sdlc/lib/os_sdlc/adapter/lesson/library.rb` 3. Move the two tests to `tests/presenter/lesson/relay_test.rb` and `tests/adapter/lesson/library_test.rb` — check: present `Lesson::Relay` in `plugins/os-sdlc/tests/presenter/lesson/relay_test.rb` 4. Update the only caller `command/gate/run.rb:100-103` to build `Lesson::Library` with the plugin lesson directory — check: absent `Gate::LessonRelay` in `plugins/os-sdlc/lib/os_sdlc/command/gate/run.rb` 5. Remove `ArtifactDir#lint_lessons` — check: absent `lint_lessons` in `plugins/os-sdlc/lib/os_sdlc/model/project/artifact_dir.rb` 6. Remove the `lint_lessons` use from the gate run — check: absent `lint_lessons` in `plugins/os-sdlc/lib/os_sdlc/command/gate/run.rb` 7. Remove the `lint_lessons` test — check: absent `lint_lessons` in `plugins/os-sdlc/tests/model/project/artifact_dir_test.rb` 8. Add a lesson step to `skills/mine-lints/references/implement-cop.md` with the ADR-0265 section list: The signal; What it is a sign of; Why it matters; Your decision; Correction; Example — check: present `What it is a sign of` in `plugins/os-sdlc/skills/mine-lints/references/implement-cop.md` Lesson text uses generic names (for example `orders_dataset`, `Order`), never names from this codebase. Lessons ship with the plugin (ADR-0266, amends ADR-0265): `Lesson::Library` reads from `plugins/os-sdlc/lint-lessons/<kebab-cop-name>.md`, found through `PluginRoot::PATH`. The gate no longer reads the project's `.sdlc/lint-lessons/`. Remove `ArtifactDir#lint_lessons` (`model/project/artifact_dir.rb`), its use in `command/gate/run.rb`, and its test in `tests/model/project/artifact_dir_test.rb`. `command/gate/run.rb` builds the library with the plugin path. Ruling (user, 2026-10-02): lint lessons are global and not project specific; project-specific lessons are deferred (YAGNI). Recorded in ADR-0266, which amends ADR-0265. Order: this ticket comes before the three cop tickets (#909, #910, #911); they depend on it. ## Acceptance criteria 1. Given the gate runs on a file with a cop offense that has a lesson file, when the gate replies, then the lesson renders as before. 2. Given the codebase, when `Gate::LessonRelay` and `Gate::LessonLibrary` are searched, then no reference remains. 3. Given the gate runs in a project with no `.sdlc/lint-lessons/` directory and a cop offense that has a plugin lesson file, when the gate replies, then the lesson renders. 4. Given the implement-cop reference, when a cop author reads it, then it names the lesson step, the plugin lesson path, and the six ADR-0265 sections in order. ## Owner sketch ```ruby module OsSdlc::Lesson class Relay; end class Library; end end ``` ## Origin - Trigger: ADR-0265 (commit 16092949) decided that lint lessons are a concept. - Improvised this session: none - Chain: lesson code under Gate ← lessons predate ADR-0265 (DESIGN: docs/adr/0265-*) - Root candidate: none - Where: plugins/os-sdlc/lib/os_sdlc/presenter/gate/lesson_relay.rb, adapter/gate/lesson_library.rb, command/gate/run.rb - Session: 9ee7805f-a4e4-470e-af50-5020e5c524a4 - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/9ee7805f-a4e4-470e-af50-5020e5c524a4.jsonl

jared added the

plugin/os-sdlc

filed-by/user

labels

2026-10-02 16:56:50 +00:00

jared referenced this issue

2026-10-02 16:57:05 +00:00

Add cop Sdlc/Sequel/DatasetResultCompared #909

jared referenced this issue

2026-10-02 16:57:06 +00:00

Add cop Sdlc/Sequel/RubyFilterAfterAll #910

jared referenced this issue

2026-10-02 16:57:07 +00:00

Add cop Sdlc/Sequel/InlineDatasetQuery #911

jared referenced this issue

2026-10-02 17:06:03 +00:00

Write seed lint-lesson files for negotiation-prone cops #519

jared commented

2026-10-02 17:06:24 +00:00

Author

Owner

Work started on branch ticket-908 through the os-sdlc pipeline.

jared commented

2026-10-02 17:13:47 +00:00

Author

Owner

Resolution

Done: Gate::LessonRelay and Gate::LessonLibrary moved to the Lesson concept (OsSdlc::Lesson::Relay, OsSdlc::Lesson::Library). Gate::Run builds the library with the plugin lesson directory. ArtifactDir#lint_lessons removed. implement-cop.md gained the lesson step (ADR-0265, ADR-0266).

Evidence: Branch ticket-908, commits 127395d1 and 52cd78a5; os-sdlc implementation 11: 10 dispatches, suite gate and required-work gate green, contract-auditor pass.

Follow-ups: Lens proposal on heuristic A2 (empty namespace root) from the contract-auditor: captured as a separate ready-for-human issue after its challenge. Lesson files themselves arrive with #909, #910, #911. History row for the os-sdlc leaf added after merge.

## Resolution **Done:** Gate::LessonRelay and Gate::LessonLibrary moved to the Lesson concept (OsSdlc::Lesson::Relay, OsSdlc::Lesson::Library). Gate::Run builds the library with the plugin lesson directory. ArtifactDir#lint_lessons removed. implement-cop.md gained the lesson step (ADR-0265, ADR-0266). **Evidence:** Branch ticket-908, commits 127395d1 and 52cd78a5; os-sdlc implementation 11: 10 dispatches, suite gate and required-work gate green, contract-auditor pass. **Follow-ups:** Lens proposal on heuristic A2 (empty namespace root) from the contract-auditor: captured as a separate ready-for-human issue after its challenge. Lesson files themselves arrive with #909, #910, #911. History row for the os-sdlc leaf added after merge.

jared closed this issue

2026-10-02 17:13:48 +00:00

jared commented

2026-10-02 17:17:15 +00:00

Author

Owner

Lens challenge (implementation 11 contract-auditor LENS line, A2 root-less Lesson namespace at presenter/lesson/relay.rb:4): verdict heuristic holds. ADR-0246 Decision 1 (docs/adr/0246-*.md:25) permits root-less noun namespaces (Evidence has no root file), and ADR-0265 Decision 2 names the root-less Lesson::Relay / Lesson::Library layout. No code change and no lens edit. The proposed A2 NOT clause gives no test that separates Lesson from the lens-cases Case 1 Git defect, so protocol step 6 refuses it. Open point: A2 (1) does not cross-reference the ADR-0246 root-less noun namespace rule. Capture skeptic gate: VERDICT: DROP (need-to-exist), so no Lens proposal ticket was filed.

jared referenced this issue from a commit

2026-10-02 17:43:17 +00:00

feat(os-sdlc): Audited POODR boundaries for #908; Lesson::Relay and Lesson::Library moved intact, Gate::Run injects the plugin lesson library, R1-R8 present, contracts protected. (#908)

jared referenced this issue from a commit

2026-10-02 17:43:17 +00:00

refactor(os-sdlc): #908 remove the Gate::Lesson* files, moved to the Lesson concept

jared referenced this issue from a commit

2026-10-02 17:43:17 +00:00

docs(os-sdlc): #908 History row

jared referenced this issue

2026-10-02 18:06:25 +00:00

Lint lessons as YAML loaded into a Lesson object (ADR-0267, ADR-0268) #913