Skip to content

fix: rewrite ARCHITECTURE.md to remove vendor coupling#56

Merged
chaksaray merged 1 commit into
developfrom
fix/architecture-remove-vendor-coupling
Jul 17, 2026
Merged

fix: rewrite ARCHITECTURE.md to remove vendor coupling#56
chaksaray merged 1 commit into
developfrom
fix/architecture-remove-vendor-coupling

Conversation

@chaksaray

Copy link
Copy Markdown
Contributor

Summary

Task D2 from the neutrality-audit-phase-2 brief. Depends on D1 (#54, merged) since this rewrite assumes `rules/` no longer exists. Applied as one coordinated rewrite, not five independent changes, per the brief's own instruction.

  • Repo layout diagram: dropped the `rules/` block entirely; `tests/fixtures/` description now explains the conformance-fixture model
  • "The record -> rule -> fixture triangle" diagram replaced with "record and conformance fixture relationship" -- dotted lines to an external `IMPL` node instead of a `RULE` node this repo no longer has
  • "How the scanner consumes this repo" -> "How an implementation consumes this repo": dropped the `rules/pattern -> PatternEngine` / `rules/yara -> YARAEngine` / `rules/semgrep -> SemgrepEngine` rows; the PiranhaDB/`api.piranha.bawbel.io` mention replaced with a generic "any other service, including any Bawbel-operated one, is documented in its own repo" per `CONTEXT.md`
  • Five detection layers table: dropped "(bawbel scan)" / "(bawbel scan-server-card)" CLI names from the "Scanner that reaches it" column
  • Recounted both stale figures against the live 59-record corpus: "33 of 48" -> "37 of 59" (content layer), "12 records" -> "15 records" (runtime layer)

One deviation from the brief as drafted: two of its replacement paragraphs cited `TRUST_STRATEGY.md` by name as supporting evidence. That file is deliberately kept out of this repo (gitignored, per `CONTEXT.md`'s own separation rule) -- citing it from a document any second implementer or OWASP reviewer will read would point them at a file they can't see, the same problem this rewrite exists to fix. Repointed both citations to `CONTEXT.md` instead, which is actually in the repo.

Test plan

  • `python3 scripts/validate_records.py` -- all 59 records still valid
  • `python3 scripts/check_fixtures.py` -- all 59 records have fixtures
  • `python3 -m pytest tests/ -x -q` -- 236 passed
  • Repo-wide grep in `ARCHITECTURE.md` for `rules/`, `bawbel scan\b`, `PatternEngine`/`YARAEngine`/`SemgrepEngine`, and stale record counts -- clean except the two `bawbel-scanner` mentions that are legitimate (named as one example implementer, not a dependency)

Task D2 from the neutrality-audit-phase-2 brief, depends on D1
(rules/ removed, #54) and applied as one coordinated rewrite, not
five independent changes:

- Repo layout diagram: dropped the rules/ block entirely (D1 already
  removed the directory); tests/fixtures/ description now explains
  the conformance-fixture model
- The "record -> rule -> fixture triangle" diagram replaced with
  "record and conformance fixture relationship" -- dotted lines to an
  external IMPL node instead of a RULE node this repo no longer has
- "How the scanner consumes this repo" -> "How an implementation
  consumes this repo": dropped the rules/pattern -> PatternEngine /
  rules/yara -> YARAEngine / rules/semgrep -> SemgrepEngine rows
  (those engines belong to bawbel-scanner specifically); the PiranhaDB/
  api.piranha.bawbel.io mention replaced with a generic "any other
  service, including any Bawbel-operated one, is documented in its
  own repo" per CONTEXT.md
- Five detection layers table: dropped "(bawbel scan)" /
  "(bawbel scan-server-card)" CLI names from the "Scanner that reaches
  it" column
- Recounted both stale figures against the live 59-record corpus:
  "33 of 48" -> "37 of 59" (content layer), "12 records" -> "15
  records" (runtime layer)

One deviation from the brief as drafted: two of its replacement
paragraphs cited `TRUST_STRATEGY.md` by name as supporting evidence.
That file is deliberately kept out of this repo (gitignored, per
CONTEXT.md's own separation rule) -- citing it from a document any
second implementer or OWASP reviewer will read would point them at a
file they can't see, the same problem this rewrite exists to fix.
Repointed both citations to CONTEXT.md instead, which is in the repo.

All 59 records still validate; full fixture-conformance suite (236
tests) passes.
@chaksaray
chaksaray merged commit d8a3e02 into develop Jul 17, 2026
6 checks passed
@chaksaray
chaksaray deleted the fix/architecture-remove-vendor-coupling branch July 17, 2026 16:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant