Check present patterns against the conventions that give each pattern its benefit #1555

New issue

Open

opened 2026-11-04 21:55:49 +00:00 by jared · 2 comments

jared commented

2026-11-04 21:55:49 +00:00

Owner

Problem

A present match shows that classes fit the roles of a pattern. It does not show that the roles are built to give the benefits of the pattern. Jared ruled on 2026-11-04 that present does not mean "leave it": a present match needs a check against the conventions of the pattern. No report does this check.

Reproduce

n/a: this is a new analysis. It needs a design first.

Approach

Step 1 is an owner-reviewed list. For each pattern in catalog/, state the benefit that its source claims and the code convention that gives the benefit. Name the fact that measures the convention, or state that no fact measures it. Compare the list with the current rules of each pattern. A convention with no rule is a gap in the role design.

The proof file must also cover two limits of the current rules (ruling 14, docs/decisions/rulings.tsv):

Wrong job: ForbiddenIo sees only I/O. Name a general way to find any job that does not belong to a role, or state that static facts cannot measure it.
Misplaced logic: rules find extra behavior in a class. No rule finds logic that belongs in the class and sits in its callers.

The review fills pattern by pattern, as each POI visit reaches that pattern, not up front (ruling 15, docs/decisions/rulings.tsv). DOM, MVC, PGC and Data Mapper remain the first candidates.

Required work: none beyond the acceptance criteria.

Acceptance criteria

Given the catalog patterns, when the review ends, then a proof file under docs/system-design-format/proof/ lists for each pattern the benefit, the convention, the fact, and the rule, or names the gap.
Given that proof file, when Jared reads it, then each gap has a proposed new rule or a statement that static facts cannot measure it.

Origin

Trigger: Jared's 2026-11-04 reply on the present band of system-model gauge
Improvised this session: none
Chain: present is read as finished ← a pattern is defined by roles and forbidden rules ← no rule tests whether the design gives the benefit of the pattern. DESIGN: docs/system-design-format/pattern-matching.md
Root candidate: none found; searched pattern, convention, benefit, catalog, present, gauge
Where: plugins/os-sdlc/lib/os_sdlc/system_model/catalog/
Session: 16528b06-720e-4ee8-b195-838770c1efe8
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/16528b06-720e-4ee8-b195-838770c1efe8.jsonl

VERDICT: CREATE

## Problem A present match shows that classes fit the roles of a pattern. It does not show that the roles are built to give the benefits of the pattern. Jared ruled on 2026-11-04 that present does not mean "leave it": a present match needs a check against the conventions of the pattern. No report does this check. ## Reproduce n/a: this is a new analysis. It needs a design first. ## Approach Step 1 is an owner-reviewed list. For each pattern in `catalog/`, state the benefit that its source claims and the code convention that gives the benefit. Name the fact that measures the convention, or state that no fact measures it. Compare the list with the current rules of each pattern. A convention with no rule is a gap in the role design. The proof file must also cover two limits of the current rules (ruling 14, `docs/decisions/rulings.tsv`): - Wrong job: `ForbiddenIo` sees only I/O. Name a general way to find any job that does not belong to a role, or state that static facts cannot measure it. - Misplaced logic: rules find extra behavior in a class. No rule finds logic that belongs in the class and sits in its callers. The review fills pattern by pattern, as each POI visit reaches that pattern, not up front (ruling 15, `docs/decisions/rulings.tsv`). DOM, MVC, PGC and Data Mapper remain the first candidates. Required work: none beyond the acceptance criteria. ## Acceptance criteria 1. Given the catalog patterns, when the review ends, then a proof file under `docs/system-design-format/proof/` lists for each pattern the benefit, the convention, the fact, and the rule, or names the gap. 2. Given that proof file, when Jared reads it, then each gap has a proposed new rule or a statement that static facts cannot measure it. ## Origin - Trigger: Jared's 2026-11-04 reply on the present band of `system-model gauge` - Improvised this session: none - Chain: present is read as finished ← a pattern is defined by roles and forbidden rules ← no rule tests whether the design gives the benefit of the pattern. DESIGN: `docs/system-design-format/pattern-matching.md` - Root candidate: none found; searched pattern, convention, benefit, catalog, present, gauge - Where: `plugins/os-sdlc/lib/os_sdlc/system_model/catalog/` - Session: 16528b06-720e-4ee8-b195-838770c1efe8 - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/16528b06-720e-4ee8-b195-838770c1efe8.jsonl VERDICT: CREATE

jared added the

plugin/os-sdlc

filed-by/user

category/investigation

labels

2026-11-04 21:55:49 +00:00

~~jared referenced this issue 2026-11-05 13:10:12 +00:00~~

Widen routes_to and trace wakeup-poll from its script so scan facts clear 21 near misses #1562

jared commented

2026-11-06 16:13:31 +00:00

Author

Owner

Occurrence: catalog tests differ from the patterns they cite
Seen: review of the 24 pattern pages for #1581, plugins/os-sdlc/pattern-pages/
Run: Session 9cb985cb-b739-445b-8657-5a81821536a3
Adds:

FTY tests a simple factory, but its source cites Factory Method.
MED requires a link back to the Mediator and parameter names that match class names. The pattern requires neither.
DOM requires a call to a constant.
MAP and the HEX Port role match almost any class.

Occurrence: catalog tests differ from the patterns they cite Seen: review of the 24 pattern pages for #1581, `plugins/os-sdlc/pattern-pages/` Run: Session 9cb985cb-b739-445b-8657-5a81821536a3 Adds: - FTY tests a simple factory, but its source cites Factory Method. - MED requires a link back to the Mediator and parameter names that match class names. The pattern requires neither. - DOM requires a call to a constant. - MAP and the HEX Port role match almost any class.

jared referenced this issue

2026-11-06 16:13:35 +00:00

Build a pattern catalog site with one teaching page per pattern #1581

jared commented

2026-11-06 18:26:50 +00:00

Author

Owner

Research rounds finished in 11bb7a13. Summary: docs/system-design-format/pattern-research/README.md, with one file per pattern beside it.

Corrections to the earlier comment on catalog tests:

MED: the link back to the Mediator was called an extra. It belongs to the pattern, so only the parameter-name match is an extra. See mediator.md.
MAP: the Mapper role matches 19 classes, not almost any class, and 0 of the 19 are true. The Subsystem role is the wide one. See mapper.md.
The earlier list of five (FTY, MED, DOM, MAP, HEX Port) was too short. Only VIS has a name, citation, page, and test that point at one thing.

Research rounds finished in 11bb7a13. Summary: docs/system-design-format/pattern-research/README.md, with one file per pattern beside it. Corrections to the earlier comment on catalog tests: - MED: the link back to the Mediator was called an extra. It belongs to the pattern, so only the parameter-name match is an extra. See mediator.md. - MAP: the Mapper role matches 19 classes, not almost any class, and 0 of the 19 are true. The Subsystem role is the wide one. See mapper.md. - The earlier list of five (FTY, MED, DOM, MAP, HEX Port) was too short. Only VIS has a name, citation, page, and test that point at one thing.

jared referenced this issue from a commit

2026-11-06 20:25:09 +00:00

docs(os-sdlc): add one research round per pattern and the decision summary (#1555)