docs(readme): say what the tool is before showing what it found - #629
Merged
Conversation
…r change it `07-generate-inventories.mjs` counts ADRs, rulesets and schemas. In the local hook it hung off `infraChanged` — docker-compose, helm, `.github/workflows` — so a ruleset or an ADR could be added without ever triggering it. And it ran in no workflow at all: its only other appearance in the repository is its own unit test in ci-cd.yml. The published summary had been stale since 2026-08-16 (141/181 against a measured 142/182) and the front page quoted it onward. - regenerate both halves of the summary, so the numbers match the corpus - run the generator with `--check` in the required `Validate documentation` job, plus its self-test, which also ran nowhere - move the local trigger to `governanceChanged || adrChanged`, the two things that can actually move the count Verified: `--check` exits 0 against the tree; self-test 7/7. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com>
…the surface Closes #566, closes #567. The server registers 52 `evolith-*` tools. The hand-maintained catalog listed 51 -- `evolith-ruleset-list` was never added when the tool landed -- and the product vision master still said 47 tools and 11 resources, a figure corrected in the README months ago and missed here. - add the missing `evolith-ruleset-list` row, in the shape of its neighbours - correct the catalog's two declared totals (51 and "current 47-tool surface") and the Spanish twin's, which asserted 51 as well - product vision EN/ES: 47 tools / 11 resources -> 52 / 12, matching the generated `product-inventory.md` Verified: the server's registered names and the catalog rows are now the same 52-element set (`comm` on both sorted lists returns nothing either way); bilingual suite green, 17/17 entry-surface documents. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com>
…nd in both languages The README quotes counters from one run of the published CLI against a fresh satellite. Until now the run itself lived nowhere, so the numbers had to be taken on faith and the elided rows could not be inspected. Captured today against `@beyondnet/evolith-cli@1.3.2` resolved from the public registry: 133 checked / 26 skipped / 0 errored of 159 selected, 72 issue rows, 37 blocking, nine of those blocking rows being rules the engine could not decide, exit 2. `stderr` was empty. Three things the capture makes checkable rather than asserted: - the two denominators reconcile in the output itself -- the `GOV-RULE-NOT-APPLICABLE` row states 253 inapplicable rules, and 253 + 159 = 412 - the same repository on the default native engine checks 41 rules and skips 118. CI holds the two engines to agreement over fixtures, not to equal coverage over a real repository, and today they do not have it - the three `[Nest] WARN Skipping non-standard ruleset` lines the README still quotes are gone in 1.3.2 -- on both streams. `INFRA-001` and `INFRA-OPA-001` are still in no denominator, so #575 is now silent rather than fixed Both halves written together, as the entry-surface rule requires. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com>
The front page opened with a 490-word forensic account of a run that ends in
`exit 2` with 37 blocking findings, and in 498 lines it never said what category
of tool this is. A reader with a minute left believing it was broken, having
never learned what it does.
Worse, the hero taught `validate --engine opa` and Quick Start taught bare
`validate` — two commands that produce different denominators (133 rules
evaluated against 41) with nothing explaining the flag. That is the exact defect
this project exists to catch, on its own front page.
Restructured, 498 -> 201 lines and 19 -> 10 sections, in both languages:
- category sentence first, then the command, then the real output
- the capture stays but is trimmed to the counters, one `did not run` row, the
`GOV-RULE-NOT-APPLICABLE` row that reconciles both denominators, and `echo $?`;
it now carries its date and resolved version, and links the full capture
- `--engine opa` used consistently, and the divergence between the two engines
disclosed rather than hidden behind the inconsistency
- Quick Start moves to the top fifth and gains Node requirements, a sample
`evolith.yaml`, what the tool actually inspects, and the `--select` mitigation
for the first-run findings
- Network Egress goes from 50 lines to 6, pointing at SECURITY.{md,es.md}, which
already carried the full disclosure bilingually and with two limitations the
README never had
- the hand-written 15-entry Menu, the inline Q&A and the ASCII diagram go; the
documentation table is rebuilt around intent, 21 rows to 9
- Contributing now names the open good-first-issues and Discussions instead of
linking four process documents at the 96% mark
Every figure was measured today rather than carried over. The old "412 rules /
181 files" is replaced by counts CI verifies (142 ADRs, 182 ruleset files, 50
schemas) alongside what the published CLI reports loading (177 packs, 412 rules).
A tree-side rule count is deliberately absent: the published CLI evaluates its
bundled corpus regardless of `coreRef.path`, so that number could not be measured
with the real counting rule, and an unverifiable figure has no business on this
page.
Verified: 201 lines and ten `##` on both sides, every relative link resolves,
both anchors exist, guards 01 and 04 green (17/17 entry-surface documents).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: aarroyo <beyondnet.peru@gmail.com>
Closes #564. Two files called MASTER_INDEX.md, and a reader who found either had no way to know the other existed. The root pair was six links deep and sat on the entry surface; the taxonomy pair was already a redirect, but its two halves pointed at DIFFERENT documents -- English at the control-center hub, Spanish at the Core hub -- so the bilingual pair disagreed about where it was sending you. - the root pair becomes canonical, and is filled out to earn the link the README now gives it: architecture, governance, product, project state and knowledge, twenty entries a side - the taxonomy pair becomes a pure redirect to the root, with both halves naming the same destination, and says in words why it holds no content of its own The redirect stays rather than being deleted: 60-odd ADRs and both reference hubs link to it. Verified: guards 01 and 04 green, five `##` a side at the root and two a side in the redirect, every relative link resolves from its own directory. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com>
… they carried The README rewrite dropped three blocks. Two had a home to go to and one had a defect that only showed once it was moved. - **Core concepts** land in the Core hub as section 8, both languages, with the ten terms the rest of the corpus assumes and links to where each is defined. `Related Navigation` renumbers 8 -> 9; nothing links to those anchors. - **The directory tree** lands in the repository taxonomy, replacing one that had gone stale at the `src/` refactor: it still showed `sdk/`, `rulesets/`, `apps/` and `packages/` at the repository root, four paths that have not existed for months, and omitted `docs/`, `product/` and `.claude-plugin/` entirely. Both halves rewritten from the tracked tree. - **The Q&A** gains the two entries the Spanish half never had. This was not two missing translations: Spanish was missing EN's `T04-P04` (topology composition) and `T07-P03` (Strangler Fig), and had silently renumbered everything after them, so `T04-P04` named different questions in the two languages. The ids now agree as a set, 43 a side. - One Spanish line read `no六个月 después` -- a CJK fragment where "seis meses" belonged, sitting in the file since it was written. The README's Spanish half is corrected from 41 questions to 43 to match. Verified: `T##-P##` id sets identical across both halves (`diff` empty), guards 01 and 04 green, every relative link in the touched files resolves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com>
Measured across the seventeen entry-surface pairs: seventeen link entries differ between halves, and thirteen of them are correct -- a Spanish half pointing at the Spanish anchor of a bilingual document is what it should do. Two were defects. - `gap-tracking` and `gap-reference-catalog` both ended with a "Back to Vision Index" footer whose halves resolved to DIFFERENT files: `../README.md` (Control Center) in English, `../../README.es.md` (the Core hub) in Spanish. Both resolve, so guard 01 was green over the contradiction. Unified on the Control Center, which is the hub these two documents actually live under, and the label now names it -- neither file is a vision index. - `reference/core/interfaces/README.md` had no bilingual navigation line at all while its Spanish half linked back to it, so the Spanish version was reachable in one direction only. Two further divergences are real but out of scope here, and are being left visible rather than papered over: `AGENTS.es.md` has no script-taxonomy section to hang the EN pointer on, and `gap-tracking.es.md` has no 2026-06-27 wave paragraph. Both are abridged translations -- content gaps, not path bugs. A link-parity guard is deliberately NOT added in this change. Of the seventeen divergences it would see today, thirteen are correct translations; a guard that needs a hand-maintained exemption list for its own true negatives is the pattern this repository emptied out of guard 66. It needs a rule that can tell a translated anchor from a wrong destination, and that is its own piece of work. Verified: guards 01, 04 and 08 green (706 gaps, 682/682 catalog sections). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com>
Opening the issue corrected the framing the disclosure carried. Guard 68 (`68-validate-engine-verdict-parity.mjs`) states in its own header that the two engines ARE allowed to disagree about coverage and are held only to agreement about facts -- so the 133-versus-41 gap is an accepted design position, not an undiscovered defect, and calling it one would have contradicted the repository's own stance. What is not accepted, and is what #628 asks for: `evolith validate` with no flag is the lower-coverage command, and nothing in its output says which engine ran or what that engine could decide. The reader sees 118 skips and has no way to tell they belong to the engine rather than to their repository. Both READMEs and both halves of the first-run capture now say that distinction in those terms and link the issue. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
📊 Bilingual Coverage ImpactPR Changes
Repository Coverage
✅ Good: All EN changes have ES counterparts. Generated by GitHub Actions |
beyondnetPeru
added a commit
that referenced
this pull request
Aug 21, 2026
* fix(ci): the inventory tally ran on the one condition that could never change it `07-generate-inventories.mjs` counts ADRs, rulesets and schemas. In the local hook it hung off `infraChanged` — docker-compose, helm, `.github/workflows` — so a ruleset or an ADR could be added without ever triggering it. And it ran in no workflow at all: its only other appearance in the repository is its own unit test in ci-cd.yml. The published summary had been stale since 2026-08-16 (141/181 against a measured 142/182) and the front page quoted it onward. - regenerate both halves of the summary, so the numbers match the corpus - run the generator with `--check` in the required `Validate documentation` job, plus its self-test, which also ran nowhere - move the local trigger to `governanceChanged || adrChanged`, the two things that can actually move the count Verified: `--check` exits 0 against the tree; self-test 7/7. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com> * docs(mcp): the tool catalog and the product vision both undercounted the surface Closes #566, closes #567. The server registers 52 `evolith-*` tools. The hand-maintained catalog listed 51 -- `evolith-ruleset-list` was never added when the tool landed -- and the product vision master still said 47 tools and 11 resources, a figure corrected in the README months ago and missed here. - add the missing `evolith-ruleset-list` row, in the shape of its neighbours - correct the catalog's two declared totals (51 and "current 47-tool surface") and the Spanish twin's, which asserted 51 as well - product vision EN/ES: 47 tools / 11 resources -> 52 / 12, matching the generated `product-inventory.md` Verified: the server's registered names and the catalog rows are now the same 52-element set (`comm` on both sorted lists returns nothing either way); bilingual suite green, 17/17 entry-surface documents. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com> * docs(evidence): publish the front page's first-run capture, in full and in both languages The README quotes counters from one run of the published CLI against a fresh satellite. Until now the run itself lived nowhere, so the numbers had to be taken on faith and the elided rows could not be inspected. Captured today against `@beyondnet/evolith-cli@1.3.2` resolved from the public registry: 133 checked / 26 skipped / 0 errored of 159 selected, 72 issue rows, 37 blocking, nine of those blocking rows being rules the engine could not decide, exit 2. `stderr` was empty. Three things the capture makes checkable rather than asserted: - the two denominators reconcile in the output itself -- the `GOV-RULE-NOT-APPLICABLE` row states 253 inapplicable rules, and 253 + 159 = 412 - the same repository on the default native engine checks 41 rules and skips 118. CI holds the two engines to agreement over fixtures, not to equal coverage over a real repository, and today they do not have it - the three `[Nest] WARN Skipping non-standard ruleset` lines the README still quotes are gone in 1.3.2 -- on both streams. `INFRA-001` and `INFRA-OPA-001` are still in no denominator, so #575 is now silent rather than fixed Both halves written together, as the entry-surface rule requires. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com> * docs(readme): say what the tool is before showing what it found The front page opened with a 490-word forensic account of a run that ends in `exit 2` with 37 blocking findings, and in 498 lines it never said what category of tool this is. A reader with a minute left believing it was broken, having never learned what it does. Worse, the hero taught `validate --engine opa` and Quick Start taught bare `validate` — two commands that produce different denominators (133 rules evaluated against 41) with nothing explaining the flag. That is the exact defect this project exists to catch, on its own front page. Restructured, 498 -> 201 lines and 19 -> 10 sections, in both languages: - category sentence first, then the command, then the real output - the capture stays but is trimmed to the counters, one `did not run` row, the `GOV-RULE-NOT-APPLICABLE` row that reconciles both denominators, and `echo $?`; it now carries its date and resolved version, and links the full capture - `--engine opa` used consistently, and the divergence between the two engines disclosed rather than hidden behind the inconsistency - Quick Start moves to the top fifth and gains Node requirements, a sample `evolith.yaml`, what the tool actually inspects, and the `--select` mitigation for the first-run findings - Network Egress goes from 50 lines to 6, pointing at SECURITY.{md,es.md}, which already carried the full disclosure bilingually and with two limitations the README never had - the hand-written 15-entry Menu, the inline Q&A and the ASCII diagram go; the documentation table is rebuilt around intent, 21 rows to 9 - Contributing now names the open good-first-issues and Discussions instead of linking four process documents at the 96% mark Every figure was measured today rather than carried over. The old "412 rules / 181 files" is replaced by counts CI verifies (142 ADRs, 182 ruleset files, 50 schemas) alongside what the published CLI reports loading (177 packs, 412 rules). A tree-side rule count is deliberately absent: the published CLI evaluates its bundled corpus regardless of `coreRef.path`, so that number could not be measured with the real counting rule, and an unverifiable figure has no business on this page. Verified: 201 lines and ten `##` on both sides, every relative link resolves, both anchors exist, guards 01 and 04 green (17/17 entry-surface documents). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com> * docs(nav): one canonical master index, and the other one stops competing Closes #564. Two files called MASTER_INDEX.md, and a reader who found either had no way to know the other existed. The root pair was six links deep and sat on the entry surface; the taxonomy pair was already a redirect, but its two halves pointed at DIFFERENT documents -- English at the control-center hub, Spanish at the Core hub -- so the bilingual pair disagreed about where it was sending you. - the root pair becomes canonical, and is filled out to earn the link the README now gives it: architecture, governance, product, project state and knowledge, twenty entries a side - the taxonomy pair becomes a pure redirect to the root, with both halves naming the same destination, and says in words why it holds no content of its own The redirect stays rather than being deleted: 60-odd ADRs and both reference hubs link to it. Verified: guards 01 and 04 green, five `##` a side at the root and two a side in the redirect, every relative link resolves from its own directory. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com> * docs(core): rehome the three blocks the front page shed, and fix what they carried The README rewrite dropped three blocks. Two had a home to go to and one had a defect that only showed once it was moved. - **Core concepts** land in the Core hub as section 8, both languages, with the ten terms the rest of the corpus assumes and links to where each is defined. `Related Navigation` renumbers 8 -> 9; nothing links to those anchors. - **The directory tree** lands in the repository taxonomy, replacing one that had gone stale at the `src/` refactor: it still showed `sdk/`, `rulesets/`, `apps/` and `packages/` at the repository root, four paths that have not existed for months, and omitted `docs/`, `product/` and `.claude-plugin/` entirely. Both halves rewritten from the tracked tree. - **The Q&A** gains the two entries the Spanish half never had. This was not two missing translations: Spanish was missing EN's `T04-P04` (topology composition) and `T07-P03` (Strangler Fig), and had silently renumbered everything after them, so `T04-P04` named different questions in the two languages. The ids now agree as a set, 43 a side. - One Spanish line read `no六个月 después` -- a CJK fragment where "seis meses" belonged, sitting in the file since it was written. The README's Spanish half is corrected from 41 questions to 43 to match. Verified: `T##-P##` id sets identical across both halves (`diff` empty), guards 01 and 04 green, every relative link in the touched files resolves. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com> * docs(nav): two bilingual pairs sent their readers to different documents Measured across the seventeen entry-surface pairs: seventeen link entries differ between halves, and thirteen of them are correct -- a Spanish half pointing at the Spanish anchor of a bilingual document is what it should do. Two were defects. - `gap-tracking` and `gap-reference-catalog` both ended with a "Back to Vision Index" footer whose halves resolved to DIFFERENT files: `../README.md` (Control Center) in English, `../../README.es.md` (the Core hub) in Spanish. Both resolve, so guard 01 was green over the contradiction. Unified on the Control Center, which is the hub these two documents actually live under, and the label now names it -- neither file is a vision index. - `reference/core/interfaces/README.md` had no bilingual navigation line at all while its Spanish half linked back to it, so the Spanish version was reachable in one direction only. Two further divergences are real but out of scope here, and are being left visible rather than papered over: `AGENTS.es.md` has no script-taxonomy section to hang the EN pointer on, and `gap-tracking.es.md` has no 2026-06-27 wave paragraph. Both are abridged translations -- content gaps, not path bugs. A link-parity guard is deliberately NOT added in this change. Of the seventeen divergences it would see today, thirteen are correct translations; a guard that needs a hand-maintained exemption list for its own true negatives is the pattern this repository emptied out of guard 66. It needs a rule that can tell a translated anchor from a wrong destination, and that is its own piece of work. Verified: guards 01, 04 and 08 green (706 gaps, 682/682 catalog sections). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com> * docs: cite #628 where the engine coverage gap is disclosed Opening the issue corrected the framing the disclosure carried. Guard 68 (`68-validate-engine-verdict-parity.mjs`) states in its own header that the two engines ARE allowed to disagree about coverage and are held only to agreement about facts -- so the 133-versus-41 gap is an accepted design position, not an undiscovered defect, and calling it one would have contradicted the repository's own stance. What is not accepted, and is what #628 asks for: `evolith validate` with no flag is the lower-coverage command, and nothing in its output says which engine ran or what that engine could decide. The reader sees 118 skips and has no way to tell they belong to the engine rather than to their repository. Both READMEs and both halves of the first-run capture now say that distinction in those terms and link the issue. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: aarroyo <beyondnet.peru@gmail.com> --------- Signed-off-by: aarroyo <beyondnet.peru@gmail.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rebuilds the front page around what a first-time reader needs, and fixes the four things the rewrite exposed on the way.
Why
The README opened with the dump of a run that ends in
exit 2with 37 blocking findings, and spent 490 words explaining that the failure was intentional. In 498 lines it never said what category of tool this is. A reader with a minute left believing it was broken, having never learned what it does.Worse, the hero taught
validate --engine opaand Quick Start taught barevalidate— two commands producing different denominators (133 rules evaluated against 41) with nothing explaining the flag. That is the exact defect this project exists to catch, on its own front page.What changed
498 → 201 lines, 19 → 10 sections, both languages. Category sentence first, then the command, then the real output. The capture stays but is trimmed to the counters, one
did not runrow, theGOV-RULE-NOT-APPLICABLErow that reconciles both denominators, andecho $?— now carrying its date and resolved version, and linking the full capture. Quick Start moves to the top fifth and gains Node requirements, a sampleevolith.yaml, what the tool actually inspects, and the--selectmitigation for first-run findings. Network Egress goes from 50 lines to 6, pointing atSECURITY.{md,es.md}, which already carried the full disclosure bilingually and with two limitations the README never had. The hand-written 15-entry Menu, the inline Q&A and the ASCII diagram go; the documentation table is rebuilt around intent, 21 rows to 9. Contributing names the open good-first-issues and Discussions instead of linking four process documents at the 96% mark.Every figure was measured today rather than carried over. The old "412 rules / 181 files" is replaced by counts CI now verifies (142 ADRs, 182 ruleset files, 50 schemas) alongside what the published CLI reports loading (177 packs, 412 rules). A tree-side rule count is deliberately absent: the published CLI evaluates its bundled corpus regardless of
coreRef.path, so that number could not be measured with the real counting rule, and an unverifiable figure has no business on this page.What the rewrite exposed
07-generate-inventories.mjscounts ADRs, rulesets and schemas, but hung offinfraChanged— compose files, helm,.github/workflows— and ran in no workflow at all. The published summary had been stale since 2026-08-16, and the README quoted it onward. Now regenerated, wired togovernanceChanged || adrChangedlocally, and run with--checkin the requiredValidate documentationjob, with its self-test.MASTER_INDEX.md, whose redirect halves pointed at different documents (closes Two competing MASTER_INDEX.md, and the README nav points at neither #564).T04-P04named different questions in the two languages. Also one line readingno六个月 después.What is deliberately not here
AGENTS.es.mdandgap-tracking.es.md. Both are abridged translations; those are content gaps, not path bugs, and are named in the commit rather than papered over.Verification
01-validate-docs.mjs04-check-bilingual-parity.mjs66-validate-bilingual-sync.mjs --since origin/main07-generate-inventories.mjs --check08-validate-tracking.mjs09-reconcile-maturity.mjs --check##, every relative link resolves, both anchors exist@beyondnet/evolith-cli@1.3.2from the registryGuard 41's five non-zero evidence commands and guard 50's two unreadable dependabot diffs are pre-existing and unrelated; guard 03 fails locally only on an untracked
CLAUDE.mdthat is not in the tree.🤖 Generated with Claude Code