Add shape detectors over the system model: repeat, vocabulary, pass-through, unclear role

jared commented

2026-10-27 17:48:51 +00:00

Owner

Problem

The system model has cards, stereotypes, class facts, journeys and a six-pattern catalog, but no detector reads the model for the four shapes the format names: shape repeat, vocabulary repeat, pass-through, and unclear role. Nobody can list the top findings over os-me and os-sdlc together, so step 4 of the path to real has no proof.

Reproduce

plugins/os-sdlc/bin/system-model shapes plugins/os-me

Output: the usage line, exit 2. No shapes subcommand exists and plugins/os-sdlc/lib/os_sdlc/system_model/ holds no detector file.

Approach

Add a shapes subcommand to system-model that builds the model with the normal steps plus the Tracer, runs four detectors over Model#cards, Model#facts and Model#journeys, and prints findings sorted by score with the shape name, the cards involved, and the evidence. Each detector is one object under OsSdlc::SystemModel::Shape:

Repeat: two or more cards whose public method names and ClassFacts agree on more than a threshold share.
Vocabulary: a method name that appears on three or more cards with different routes_to targets.
PassThrough: a card whose every public method forwards one message to one collaborator with no state read.
UnclearRole: a card whose stereotype is degenerate or whose facts match no catalog role predicate.

Required work:

Add the four detectors under the system-model library — check: present UnclearRole in plugins/os-sdlc/lib/os_sdlc/system_model/shape/*.rb
Add a ShapeReport that prints findings sorted by score — check: present ShapeReport in plugins/os-sdlc/lib/os_sdlc/system_model/*.rb
Accept shapes in the system-model argv parser and usage text — check: present shapes in plugins/os-sdlc/lib/os_sdlc/boot/inputs.rb
Route shapes through Run with the Tracer step — check: present shapes in plugins/os-sdlc/lib/os_sdlc/system_model/run.rb

Realigned spec

Spec realigned 2026-11-01 (README section 6 step 10, ruled by Jared 2026-11-01):

The pattern list and the thresholds are data. No pattern ID appears in detector code.
Convergence is computed for each scale group (pattern-matching.md section 5, amendment 2026-11-01).
The output prints a coverage figure for each plugin.
Blocked by the step 9 fact spike ticket (#1482).
Proof: run over os-me and os-sdlc together and read the top ten findings by hand.

Acceptance criteria

Given two cards with the same three public method names and equal facts, when the repeat detector runs, then it reports one finding naming both cards.
Given a method name on three cards that route to three different targets, when the vocabulary detector runs, then it reports one finding naming the method and the three cards.
Given a card whose only public method sends one message to one collaborator and reads no state, when the pass-through detector runs, then it reports that card.
Given a card whose facts match no catalog role predicate, when the unclear-role detector runs, then it reports that card.
Given a seventh stub pattern added to the pattern data, when the detectors run, then they run with no code change and no pattern ID appears in detector code.
Given findings over a model with several scale groups, when the detectors run, then convergence is computed for each scale group.
Given a run over os-me and os-sdlc together, when the output prints, then it holds a coverage figure for each plugin.
Given plugins/os-me as the target, when system-model shapes plugins/os-me runs, then it exits zero and prints findings with a shape name, card names and evidence on each line.

Owner sketch

class OsSdlc::SystemModel::Shape::Repeat
  def initialize(model); end
  def findings; end
end
class OsSdlc::SystemModel::ShapeReport
  def initialize(stdout); end
  def print(findings); end
end

Non-goals

Reading the ten findings by hand over os-me and os-sdlc together is the proof step; it runs after this ticket ships and is recorded in docs/system-design-format/proof/.

Origin

Trigger: pattern-detection track handoff 2026-10-27-1540, step 5: capture README section 6 steps 4, 5, 7
Improvised this session: none
Chain: no shape findings ← no detectors over the model ← DESIGN (docs/system-design-format/README.md section 6 step 4 not built)
Root candidate: none found; searched shape, repeat, pass-through, unclear role, detector, system-model
Where: docs/system-design-format/README.md section 6 step 4; plugins/os-sdlc/lib/os_sdlc/system_model/run.rb
Session: 47f54f99-e35c-4567-a3e6-581fecf54dc3
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os--claude-worktrees-ticket-1392/47f54f99-e35c-4567-a3e6-581fecf54dc3.jsonl

VERDICT: CREATE

## Problem The system model has cards, stereotypes, class facts, journeys and a six-pattern catalog, but no detector reads the model for the four shapes the format names: shape repeat, vocabulary repeat, pass-through, and unclear role. Nobody can list the top findings over os-me and os-sdlc together, so step 4 of the path to real has no proof. ## Reproduce ``` plugins/os-sdlc/bin/system-model shapes plugins/os-me ``` Output: the usage line, exit 2. No `shapes` subcommand exists and `plugins/os-sdlc/lib/os_sdlc/system_model/` holds no detector file. ## Approach Add a `shapes` subcommand to `system-model` that builds the model with the normal steps plus the Tracer, runs four detectors over `Model#cards`, `Model#facts` and `Model#journeys`, and prints findings sorted by score with the shape name, the cards involved, and the evidence. Each detector is one object under `OsSdlc::SystemModel::Shape`: * `Repeat`: two or more cards whose public method names and `ClassFacts` agree on more than a threshold share. * `Vocabulary`: a method name that appears on three or more cards with different `routes_to` targets. * `PassThrough`: a card whose every public method forwards one message to one collaborator with no state read. * `UnclearRole`: a card whose stereotype is `degenerate` or whose facts match no catalog role predicate. Required work: 1. Add the four detectors under the system-model library — check: present `UnclearRole` in `plugins/os-sdlc/lib/os_sdlc/system_model/shape/*.rb` 2. Add a `ShapeReport` that prints findings sorted by score — check: present `ShapeReport` in `plugins/os-sdlc/lib/os_sdlc/system_model/*.rb` 3. Accept `shapes` in the system-model argv parser and usage text — check: present `shapes` in `plugins/os-sdlc/lib/os_sdlc/boot/inputs.rb` 4. Route `shapes` through `Run` with the Tracer step — check: present `shapes` in `plugins/os-sdlc/lib/os_sdlc/system_model/run.rb` ## Realigned spec Spec realigned 2026-11-01 (README section 6 step 10, ruled by Jared 2026-11-01): * The pattern list and the thresholds are data. No pattern ID appears in detector code. * Convergence is computed for each scale group (pattern-matching.md section 5, amendment 2026-11-01). * The output prints a coverage figure for each plugin. * Blocked by the step 9 fact spike ticket (#1482). * Proof: run over os-me and os-sdlc together and read the top ten findings by hand. ## Acceptance criteria 1. Given two cards with the same three public method names and equal facts, when the repeat detector runs, then it reports one finding naming both cards. 2. Given a method name on three cards that route to three different targets, when the vocabulary detector runs, then it reports one finding naming the method and the three cards. 3. Given a card whose only public method sends one message to one collaborator and reads no state, when the pass-through detector runs, then it reports that card. 4. Given a card whose facts match no catalog role predicate, when the unclear-role detector runs, then it reports that card. 5. Given a seventh stub pattern added to the pattern data, when the detectors run, then they run with no code change and no pattern ID appears in detector code. 6. Given findings over a model with several scale groups, when the detectors run, then convergence is computed for each scale group. 7. Given a run over os-me and os-sdlc together, when the output prints, then it holds a coverage figure for each plugin. 8. Given `plugins/os-me` as the target, when `system-model shapes plugins/os-me` runs, then it exits zero and prints findings with a shape name, card names and evidence on each line. ## Owner sketch ```ruby class OsSdlc::SystemModel::Shape::Repeat def initialize(model); end def findings; end end class OsSdlc::SystemModel::ShapeReport def initialize(stdout); end def print(findings); end end ``` ## Non-goals Reading the ten findings by hand over os-me and os-sdlc together is the proof step; it runs after this ticket ships and is recorded in `docs/system-design-format/proof/`. ## Origin - Trigger: pattern-detection track handoff 2026-10-27-1540, step 5: capture README section 6 steps 4, 5, 7 - Improvised this session: none - Chain: no shape findings ← no detectors over the model ← DESIGN (docs/system-design-format/README.md section 6 step 4 not built) - Root candidate: none found; searched shape, repeat, pass-through, unclear role, detector, system-model - Where: docs/system-design-format/README.md section 6 step 4; plugins/os-sdlc/lib/os_sdlc/system_model/run.rb - Session: 47f54f99-e35c-4567-a3e6-581fecf54dc3 - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os--claude-worktrees-ticket-1392/47f54f99-e35c-4567-a3e6-581fecf54dc3.jsonl VERDICT: CREATE

jared added the

plugin/os-sdlc

filed-by/user

category/code-change

labels

2026-10-27 17:48:51 +00:00

jared commented

2026-11-01 15:47:19 +00:00

Author

Owner

Waiting on #1482 (step 9 fact spike). Spec realigned to README section 6 step 10: pattern list and thresholds are data, no pattern ID in detector code, convergence per scale group, coverage figure per plugin. Body edited 2026-11-01.

jared referenced this issue

2026-11-01 16:00:21 +00:00

os-backlog CLI has no label-add or label-remove command #867

jared commented

2026-11-01 16:00:31 +00:00

Author

Owner

os-backlog cannot add labels yet (#867, the label verb ticket). This ticket stays blocked by #1482 per its earlier comments.

jared commented

2026-11-01 16:52:25 +00:00

Author

Owner

Work started 2026-11-01 in worktree agent-a4cb3d82d3b8a229b (branch worktree-agent-a4cb3d82d3b8a229b). Blocker #1482 is merged (main 914918c5).

Work started 2026-11-01 in worktree agent-a4cb3d82d3b8a229b (branch worktree-agent-a4cb3d82d3b8a229b). Blocker #1482 is merged (main 914918c5).

jared referenced this issue from a commit

2026-11-01 17:14:31 +00:00

feat(system-model): shape detectors (#1429)

jared referenced this issue from a commit

2026-11-01 17:14:31 +00:00

docs(system-model): shape detector definitions and step 10 status for #1429

jared referenced this issue

2026-11-01 17:18:22 +00:00

Add pattern rules for process, environment, and network io kinds #1489

jared referenced this issue

2026-11-01 17:18:23 +00:00

Detect network io through injected client instances #1490

jared referenced this issue

2026-11-01 17:18:23 +00:00

Rule whether ENV and process conditions count as decides #1491

jared referenced this issue

2026-11-01 17:18:24 +00:00

Extract facts F3 subclasses and F4 abstract methods #1492

jared referenced this issue

2026-11-01 17:18:25 +00:00

Extract facts from bin scripts as well as lib #1493

jared referenced this issue

2026-11-01 17:18:25 +00:00

Stop factory .new calls in self. methods tripping HEX R2 #1494

jared referenced this issue

2026-11-01 17:18:26 +00:00

Credit a nested Data.define block to its own class #1495

jared referenced this issue

2026-11-01 17:18:27 +00:00

Keep rule ids in Opportunity flagged_by #1496

jared referenced this issue

2026-11-01 17:18:27 +00:00

Split large untraced namespace components #1497

jared referenced this issue

2026-11-01 17:18:28 +00:00

Rank vocabulary-repeat terms by domain specificity #1498

jared referenced this issue

2026-11-01 17:18:29 +00:00

Merge vocabulary-repeat findings with the same owner set #1499

jared referenced this issue

2026-11-01 17:18:29 +00:00

Give Data and Struct values ClassFacts #1500

jared referenced this issue

2026-11-01 17:18:30 +00:00

Do not count pass-through classes whose work happens in initialize #1501

jared commented

2026-11-01 17:18:39 +00:00

Author

Owner

Resolution

Done: Shape detectors shipped

Evidence: 98a029ca + 6064041a, merge 85599697; docs/system-design-format/proof/shape-detectors-run-1.md

Follow-ups: #1498 #1499 #1500 #1501

## Resolution **Done:** Shape detectors shipped **Evidence:** 98a029ca + 6064041a, merge 85599697; docs/system-design-format/proof/shape-detectors-run-1.md **Follow-ups:** #1498 #1499 #1500 #1501

jared closed this issue

2026-11-01 17:18:39 +00:00

jared referenced this issue

2026-11-01 17:25:38 +00:00

Measure VIS R2 with the new forwards fact #1503

Rows
Columns

Add shape detectors over the system model: repeat, vocabulary, pass-through, unclear role #1429

Problem

Reproduce

Approach

Realigned spec

Acceptance criteria

Owner sketch

Non-goals

Origin

Resolution