jared/cc-os

Watch

Fork 0

Cut Map -> Brief: move fact names to a top-level FactNames #1169

New issue

Closed

opened 2026-10-19 20:13:17 +00:00 by jared · 2 comments

jared commented

2026-10-19 20:13:17 +00:00

Owner

Problem

The Map concept calls into the Brief concept. Map::Document defaults its facts: argument to Brief::Facts::FACTS (map/document.rb:13). That list holds the fact names a map YAML file may use. The edge Map -> Brief lies on 38 concept cycles. Map::Document is the only user of Brief::Facts::FACTS outside Brief::Facts. A neutral top-level list of names, a peer of AgentNames, removes the edge.

Reproduce

n/a: structure-wave cut, nothing to reproduce

Approach

Required work:

Create plugins/os-sdlc/lib/os_sdlc/fact_names.rb with OsSdlc::FactNames::ALL: the frozen list of the 11 names now keys of Brief::Facts::FACT_RESOLVERS (ticket_brief, gate_results, test_changes, code_changes, lint_offense_history, objections, retired_tests, red_tests, gate_verdicts, round_tests, approved_maps) — check: present ALL in plugins/os-sdlc/lib/os_sdlc/fact_names.rb
In plugins/os-sdlc/lib/os_sdlc/brief/facts.rb, keep the literal FACT_RESOLVERS hash: Sdlc/Structural/UnusedPrivateMethod reads the resolver symbols in it, and a derived hash hides the 9 private resolvers from the cop. Delete FACTS. Directly after the hash, add one load-time guard: raise UnknownFactError, "FACT_RESOLVERS keys differ from FactNames::ALL" unless FACT_RESOLVERS.keys == FactNames::ALL — check: present FactNames::ALL in plugins/os-sdlc/lib/os_sdlc/brief/facts.rb
In plugins/os-sdlc/lib/os_sdlc/map/document.rb, default facts: to FactNames::ALL — check: absent Brief in plugins/os-sdlc/lib/os_sdlc/map/document.rb

Acceptance criteria

Given the suite, when run after the change, then it passes with no new failures.
Given the lib tree, when bin/crc-cycle-edges runs, then no edge Map -> Brief lists map/document.rb:13.
Given a map YAML file that names a known fact, when Map::Document.load runs, then it loads.
Given a map YAML file that names an unknown fact, when Map::Document.load runs, then validation fails as before.

Owner sketch

The constant FACTS stays deleted from brief/facts.rb.

module OsSdlc::FactNames
  ALL = %w[ticket_brief gate_results ...].freeze
end

No other file in lib, bin or tests uses Brief::Facts::FACTS. Pinning tests: tests/map/document_test.rb, tests/map/check_test.rb, tests/brief/facts_fact_names_test.rb and the other tests/brief/facts_*_test.rb files.

Origin

Trigger: os-sdlc CRC run 3, structure-ruling wave step 1 (bin/crc-cycle-edges on main 049a7820)
Improvised this session: none
Chain: concept cycle Map -> Brief (cycles_through 38) ← map/document.rb:13 ← DESIGN (docs/crc/os-sdlc/wave0/structure-rulings.tsv S5)
Root candidate: none found; searched FactNames, Map, Brief
Where: plugins/os-sdlc/lib/os_sdlc/map/document.rb
Ledger: docs/crc/os-sdlc/ledger.tsv
Rulings: docs/crc/os-sdlc/wave0/structure-rulings.tsv
Session: 2e167079-f404-4139-9cfa-6c0c937ce9f0
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/2e167079-f404-4139-9cfa-6c0c937ce9f0.jsonl

VERDICT: CREATE

## Problem The Map concept calls into the Brief concept. `Map::Document` defaults its `facts:` argument to `Brief::Facts::FACTS` (map/document.rb:13). That list holds the fact names a map YAML file may use. The edge Map -> Brief lies on 38 concept cycles. `Map::Document` is the only user of `Brief::Facts::FACTS` outside `Brief::Facts`. A neutral top-level list of names, a peer of `AgentNames`, removes the edge. ## Reproduce n/a: structure-wave cut, nothing to reproduce ## Approach Required work: 1. Create `plugins/os-sdlc/lib/os_sdlc/fact_names.rb` with `OsSdlc::FactNames::ALL`: the frozen list of the 11 names now keys of `Brief::Facts::FACT_RESOLVERS` (`ticket_brief`, `gate_results`, `test_changes`, `code_changes`, `lint_offense_history`, `objections`, `retired_tests`, `red_tests`, `gate_verdicts`, `round_tests`, `approved_maps`) — check: present `ALL` in `plugins/os-sdlc/lib/os_sdlc/fact_names.rb` 2. In `plugins/os-sdlc/lib/os_sdlc/brief/facts.rb`, keep the literal `FACT_RESOLVERS` hash: `Sdlc/Structural/UnusedPrivateMethod` reads the resolver symbols in it, and a derived hash hides the 9 private resolvers from the cop. Delete `FACTS`. Directly after the hash, add one load-time guard: `raise UnknownFactError, "FACT_RESOLVERS keys differ from FactNames::ALL" unless FACT_RESOLVERS.keys == FactNames::ALL` — check: present `FactNames::ALL` in `plugins/os-sdlc/lib/os_sdlc/brief/facts.rb` 3. In `plugins/os-sdlc/lib/os_sdlc/map/document.rb`, default `facts:` to `FactNames::ALL` — check: absent `Brief` in `plugins/os-sdlc/lib/os_sdlc/map/document.rb` ## Acceptance criteria 1. Given the suite, when run after the change, then it passes with no new failures. 2. Given the lib tree, when `bin/crc-cycle-edges` runs, then no edge Map -> Brief lists `map/document.rb:13`. 3. Given a map YAML file that names a known fact, when `Map::Document.load` runs, then it loads. 4. Given a map YAML file that names an unknown fact, when `Map::Document.load` runs, then validation fails as before. ## Owner sketch The constant `FACTS` stays deleted from `brief/facts.rb`. ```ruby module OsSdlc::FactNames ALL = %w[ticket_brief gate_results ...].freeze end ``` No other file in lib, bin or tests uses `Brief::Facts::FACTS`. Pinning tests: `tests/map/document_test.rb`, `tests/map/check_test.rb`, `tests/brief/facts_fact_names_test.rb` and the other `tests/brief/facts_*_test.rb` files. ## Origin - Trigger: os-sdlc CRC run 3, structure-ruling wave step 1 (bin/crc-cycle-edges on main 049a7820) - Improvised this session: none - Chain: concept cycle Map -> Brief (cycles_through 38) ← map/document.rb:13 ← DESIGN (docs/crc/os-sdlc/wave0/structure-rulings.tsv S5) - Root candidate: none found; searched FactNames, Map, Brief - Where: plugins/os-sdlc/lib/os_sdlc/map/document.rb - Ledger: docs/crc/os-sdlc/ledger.tsv - Rulings: docs/crc/os-sdlc/wave0/structure-rulings.tsv - Session: 2e167079-f404-4139-9cfa-6c0c937ce9f0 - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/2e167079-f404-4139-9cfa-6c0c937ce9f0.jsonl VERDICT: CREATE

jared added the

labels

2026-10-19 20:13:17 +00:00

jared commented

2026-10-19 20:30:16 +00:00

Author

Owner

Work started on branch crc-os-sdlc-run-3 (os-sdlc CRC run 3, persistent worktree).

jared referenced this issue

2026-10-19 20:51:16 +00:00

Key the RuboCop cache on the CRC ledger that the layer cops read #1173

jared commented

2026-10-19 20:51:22 +00:00

Author

Owner

Resolution

Done: S5 cut applied: new top-level OsSdlc::FactNames::ALL; Map::Document defaults its facts to it; Brief::Facts keeps the literal FACT_RESOLVERS hash, FACTS deleted, load-time guard added. Ledger row for FactNames and corrected S5 sentence committed.

Evidence: 3195e3d3, e0e3a066; suite 2248 runs, 0 failures (45.3 s); eager load clean; rubocop 3 files, no offenses; inward delta 242 -> 242, new 0; cycle edges 22 -> 18; ticket design corrected on the tracker and rerouted once (implementation 81)

Follow-ups: #1173 (RuboCop cache does not key on the ledger; VERDICT: CREATE)

## Resolution **Done:** S5 cut applied: new top-level OsSdlc::FactNames::ALL; Map::Document defaults its facts to it; Brief::Facts keeps the literal FACT_RESOLVERS hash, FACTS deleted, load-time guard added. Ledger row for FactNames and corrected S5 sentence committed. **Evidence:** 3195e3d3, e0e3a066; suite 2248 runs, 0 failures (45.3 s); eager load clean; rubocop 3 files, no offenses; inward delta 242 -> 242, new 0; cycle edges 22 -> 18; ticket design corrected on the tracker and rerouted once (implementation 81) **Follow-ups:** #1173 (RuboCop cache does not key on the ledger; VERDICT: CREATE)

jared closed this issue

2026-10-19 20:51:22 +00:00

jared referenced this issue from a commit

2026-10-20 02:14:32 +00:00

feat(os-sdlc): S5 done. FactNames::ALL created; Map::Document defaults facts to it; Brief::Facts keeps the literal FACT_RESOLVERS hash, FACTS deleted, load-time guard added. Gate green. (#1169)

jared referenced this issue from a commit

2026-10-20 02:14:32 +00:00

docs(crc): ledger row for FactNames; S5 sentence matches the applied cut (#1169)