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

Open
#130 6 comments 0 reactions 1 assignee View on GitHub

@JohnStrunk is already working on this.

Since Sep 18, 2026.

component:drafting-table documentation triaged
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 artifacts list of project.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

  1. Rewrite the "Registered artifact paths" section (~line 229) so it accounts for both the artifacts list AND the stores block: 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 (in artifacts) from structured store records (in stores, per ADR-0003), while still being clear that a path registered in neither is not staged.
  2. 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 artifacts entries and three stores entries (five managed paths total)" rather than a single bare number.

Validation

  • grep -n "four default registry entries" docs/architecture/git-integration.md returns 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/artifacts split 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 the docs/ hierarchy.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.