redhat-et / redhat-et/ProtoBot
docs/architecture/git-integration.md: reconcile 'Registered artifact paths' section and stale path-count fixture with the ADR-0003 stores block
@JohnStrunk is already working on this.
Since Sep 18, 2026.
- Dominant language
- Go
- Stars
- 5
- Forks
- 6
- Avg merge
- 23h 24m
- Merged PRs (30d)
- 66
Description
Problem
docs/architecture/git-integration.md's "Registered artifact paths" section (around line 229) currently reads:
Every specification artifact the Drafting Table may commit is registered in the
artifactslist ofproject.yaml. An unregistered path is not a specification artifact, and the Drafting Table never stages it.
This is now inaccurate. A few lines later in the same document (around line 253), the file correctly describes a separate stores block, defined by ADR-0003 (docs/decisions/0003-ears-manager-storage-layout.md), that holds the three structured store paths (requirements, interfaces, change-sets) — distinct from the artifacts list, which now holds only the opaque Vision/Architecture/interface-IDL/interface-prose entries. The earlier paragraph's absolute claim that only artifacts-list entries are committable directly contradicts the later stores block description. A reader who takes the "Registered artifact paths" section literally would incorrectly conclude that requirement/interface/change-set files can never be staged by the Drafting Table.
Separately, a test fixture in the same document (around line 849, in the "Fixture" table's first row) still says project.yaml carries "the four default registry entries" and that projection.yaml carries a shared class "for each of those four paths." With the current layout (2 artifacts entries — vision, architecture — plus 3 stores entries — requirements, interfaces, change-sets), there are five managed paths, not four. A separate reviewer (CodeRabbit) flagged the same staleness but proposed changing "four" to "two"; that number describes only the artifacts-list count, not the total managed-path count, so the two suggestions are not actually in conflict — they're describing different counts.
Both defects were introduced when PR #123 restructured spec-document path registration (moving the three structured store paths into the new stores block) but did not fully update this document's prose and fixture to match.
Fix
- Rewrite the "Registered artifact paths" section (~line 229) so it accounts for both the
artifactslist AND thestoresblock: both are committable/staged by the Drafting Table. Replace the absolute "An unregistered path is not a specification artifact" claim with wording that distinguishes opaque artifacts (inartifacts) from structured store records (instores, per ADR-0003), while still being clear that a path registered in neither is not staged. - Correct the fixture row (~line 849) to reflect the current five managed paths (2 artifacts + 3 stores). To avoid ambiguity between the artifacts-only count and the total managed-path count, state both explicitly, e.g. "two
artifactsentries and threestoresentries (five managed paths total)" rather than a single bare number.
Validation
grep -n "four default registry entries" docs/architecture/git-integration.mdreturns nothing (or only an updated, accurate phrase).- The "Registered artifact paths" section no longer asserts that only
artifacts-list paths can be staged. - The fixture row at ~line 849 is internally consistent with the
stores/artifactssplit described earlier in the document. - Cross-check against
docs/decisions/0003-ears-manager-storage-layout.md(ADR-0003) to confirm the corrected text matches the store/version-key definitions there, per this repo's rule that specification documents must account for sibling documents in thedocs/hierarchy.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.