Enforce shared Oxford spelling

[leynos]

Summary

This branch establishes the shared en-GB-oxendict spelling foundation for the
leynos code estate. It adds a curated global dictionary, conditionally
refreshes an untracked local cache only when the authoritative copy is newer,
merges narrow repository overlays, generates deterministic typos
configuration, harvests both Oxford and plain-British forms, and enforces the
result through the repository's CI gate.

The base was curated from exclusion-aware harvests of all 96 non-empty,
accessible repositories in the estate inventory. Generated spelling configs,
local overlays, lockfiles and build output were removed before contextual
classification; 49 observed generic Oxford stems joined the original
reference set. The branch also corrects every spelling finding exposed in this
repository. Product names, identifiers, configuration keys and deliberate
negative test fixtures remain unchanged through narrow local exclusions rather
than global exceptions.

No repository roadmap task, implementation ExecPlan, or open issue was found
for this foundation work. Issue #28 is already satisfied on main and is not
closed by this branch.

Review walkthrough

• Start with the shared dictionary
  and architecture decision
  to review the estate-wide Oxford policy and its trade-offs.
• Review the core helper
  for source-aware local and HTTP refresh, atomic writes, deterministic
  generation, dictionary merging, local harvest exclusions and evidence
  collection.
• Then review the executable CLI
  for the directly runnable generate and harvest commands.
• Continue with the behavioural tests
  for property and regression coverage of freshness, source identity, offline
  recovery, conflicts, harvest exclusions, TOML validity, config drift and the
  real pinned consumer.
• Check the Makefile integration
  and local overlay
  for the serialized CI entrypoint and deliberately narrow repository
  exceptions.
• Finish with the developers' guide
  and users' guide
  for the curation and consumer workflows.

Validation

• make ci: passed; 126 tests, config generation, and the pinned spelling
  gate are green.
• shellcheck -x add-repositories bootstrap-common get-github-tooling rust-setup:
  passed.
• mbake validate Makefile: passed.
• git diff --check: passed.
• Estate harvest: 96 of 96 candidate default branches produced retained JSON
  Lines evidence under the rollout workspace.
• Semantic and word-diff audit: existing changes are limited to tooling,
  tests, prose and comments; no public or serialized application interface
  changed.

Notes

All ten CodeRabbit findings were addressed in c0bc7c5, including the two
correctness defects in source-aware cache validity and local harvest
exclusions. The corresponding threads have responses and are resolved.

The untracked cache files are ignored, while the generated typos.toml remains
tracked and protected by a byte-for-byte drift test. The shared base accepts
only estate-wide vocabulary; repository-specific terms stay in local overlays
so a false positive in one project cannot weaken enforcement elsewhere.

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Add an Oxford-based shared spelling dictionary, deterministic generation and refresh tooling, a CI spelling gate, comprehensive tests, operational documentation, and repository-wide spelling consistency edits.

Changes

Shared spelling rollout

Layer / File(s)	Summary
Dictionary model and generation data/typos-oxendict-base.toml, scripts/typos_rollout.py, typos.local.toml, typos.toml	Add validated dictionary data, Oxford stem expansion, cache refresh, harvesting, deterministic rendering, atomic writes, and generated spelling mappings.
CLI, CI gate, and validation scripts/typos_rollout_cli.py, Makefile, pyproject.toml, tests/test_typos_rollout.py, README.md, docs/developers-guide.md, .gitignore	Expose dictionary generation and harvesting commands, run spelling checks through CI, register slow tests, validate refresh and rendering behaviour, and document the workflow.
Repository wording consistency docs/*, skills/*, agents/subagents.yml, add-repositories, bootstrap-common, get-github-tooling, hooks/*, rust-setup, tests/test_bootstrap_common.py	Update spelling and terminology in comments, documentation, skill guidance, and test descriptions without changing executable behaviour.

Sequence Diagram(s)

sequenceDiagram
  participant Developer
  participant Makefile
  participant Rollout as typos_rollout_cli.py
  participant Typos
  Developer->>Makefile: run make spelling
  Makefile->>Rollout: generate shared configuration
  Rollout->>Typos: write typos.toml
  Makefile->>Typos: check repository spelling
  Typos-->>Developer: report spelling results

Loading

Possibly related issues

• leynos/stilyagi issue 57 — The renderer’s TOML parse validation and committed-config drift test address malformed or duplicate-key configuration regressions.

Poem

Oxford stems wake, neat and bright,
Cache and mappings fall in line.
CI guards each word in flight,
Tests keep generated truth in time.
Spelling sails through every gate.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error, 4 warnings)

Check name	Status	Explanation	Resolution
Unit Architecture	❌ Error	The PR violates unit architecture principles in multiple critical ways: (1) harvest_repository loads only the shared dictionary and never merges typos.local.toml before filtering, emitting fixt...	Merge repository overlay before filtering in harvest_repository; fix _refresh_local cache validity to key against metadata source identity and mtime; rewrite Makefile to serialise spelling after test via recipe, not dependency; a...
User-Facing Documentation	⚠️ Warning	docs/users-guide.md still only covers bootstrap settings; it has no spelling/typos section for the new workflow.	Add a users-guide section for make spelling, the rollout CLI, shared base vs typos.local.toml, and generated/cache files.
Developer Documentation	⚠️ Warning	The developer guide adds make spelling, but the make ci bullet still says CI runs only check-fmt, lint, typecheck, and test, so the build docs are not fully in sync.	Update the make ci bullet to include spelling, and capture any shared-spelling design decision in the relevant ADR or design doc.
Testing (Property / Proof)	⚠️ Warning	The PR adds invariant-heavy refresh, merge, and rendering logic, but the new tests are example-based only; no Hypothesis/proptest/CrossHair/Kani coverage or substantive proof appears.	Add property tests for merge/render/refresh/harvest invariants (e.g. Hypothesis) or provide a rigorous exhaustive proof for any lemma-like assumptions; keep the example tests as regressions.
Concurrency And State	⚠️ Warning	Serialize ci before spelling; ci: check-fmt lint typecheck test spelling still permits make -j races, and cache/metadata writes have no lock or transaction.	Move spelling into the ci recipe after test, or add explicit locking/atomic coordination around the cache and metadata updates.

✅ Passed checks (15 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 98.04% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Testing (Overall)	✅ Passed	Tests cover schema validation, mapping, merge conflicts, refresh paths, harvesting, atomic writes, drift, and a real pinned typos run; they are substantive, not vacuous.
Module-Level Documentation	✅ Passed	PASS: every touched Python module has a module docstring, and each touched shell module starts with a purpose header describing its role and links to entrypoints/tests.
Testing (Unit And Behavioural)	✅ Passed	Tests cover parsing, merge, freshness, atomic writes and harvest edge cases, and one slow test runs the real pinned typos binary against generated config.
Testing (Compile-Time / Ui)	✅ Passed	No Rust/TypeScript compile-time path was added; structured typos/TOML output is covered by deterministic and end-to-end assertions in tests/test_typos_rollout.py.
Domain Architecture	✅ Passed	PASS: The diff stays in tooling/docs/config; no domain-layer code is altered, and the new CLI/helper keeps filesystem and HTTP concerns at the adapter boundary.
Observability	✅ Passed	Keep this as repository tooling: generate prints stable refresh status plus path, and harvest emits JSONL findings; no production service, metrics, tracing, or alerts were introduced.
Security And Privacy	✅ Passed	No secrets, auth gaps, or unsafe sinks found; the new code only parses TOML, refreshes caches via git/HTTP, and prints derived spelling evidence.
Performance And Resource Use	✅ Passed	Keep the new work single-pass and bounded; the harvest, render, and refresh paths use linear scans, finite suffix sets, and no unbounded retries or background jobs.
Architectural Complexity And Maintainability	✅ Passed	PASS: the PR adds one focused helper and a thin CLI around a real seam, with explicit data files and docs; no speculative layers, cycles, or hidden registration appeared.
Rust Compiler Lint Integrity	✅ Passed	No Rust files changed; the diff adds no broad lint suppressions or suspicious clone-heavy Rust edits.
Title check	✅ Passed	The title clearly matches the PR’s main change: enforcing shared Oxford spelling across the estate.
Description check	✅ Passed	The description directly describes the spelling foundation, rollout, and CI enforcement changes.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch typos-roll-out

---

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Sorry @leynos, your pull request is larger than the review limit of 150000 diff characters

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[leynos]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 10

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@agents/subagents.yml`:
- Around line 296-297: Rewrite the sentence in the relevant gate-order
documentation to attribute cache contention prevention to sequential gate
execution, explicitly stating that uv, cargo, and .pytest_cache do not serialize
access themselves.

In `@docs/developers-guide.md`:
- Around line 302-305: Update the adjacent make ci target-list bullet to include
spelling after test, keeping it consistent with the documentation stating that
CI runs the spelling gate.

In `@Makefile`:
- Line 44: Update the Makefile ci target to remove spelling from its
prerequisites and invoke +$(MAKE) spelling in the ci recipe after check-fmt,
lint, typecheck, and test complete, ensuring spelling generation is serialized
after the existing CI checks.

In `@scripts/typos_rollout_cli.py`:
- Line 6: Expand the module docstring in scripts/typos_rollout_cli.py to explain
the CLI’s purpose, utility, and usage, including cache, network, filesystem, and
JSONL behavior. Add NumPy-style docstrings to the public cli, generate, and
harvest functions, documenting their parameters, returns, side effects, and
command behavior.

In `@scripts/typos_rollout.py`:
- Line 1: Document the public API in scripts/typos_rollout.py using NumPy-style
docstrings: expand the module docstring with usage guidance, and add structured
Parameters, Returns, and Raises sections to every public class and function,
including the interfaces around the referenced ranges; ensure parameter types,
return values, raised exceptions, and behavior are accurately described.
- Around line 342-353: harvest_repository currently filters tracked files using
only the shared dictionary, so repository-specific exclusions are ignored.
Before iterating over tracked files, load the repository’s typos.local.toml
overlay and merge it with the shared dictionary, then pass the merged dictionary
to is_harvest_excluded so excluded fixtures such as tests/test_typos_rollout.py
are skipped.
- Around line 258-272: Update _refresh_local to determine cache freshness from
the authoritative metadata recorded by _write_metadata, rather than comparing
filesystem mtimes alone. Read and validate the metadata source and mtime against
the supplied source; treat missing, malformed, or mismatched metadata as stale,
then load and atomically write the local source content and refresh metadata.

In `@skills/code-review/guides/security-issues.md`:
- Line 72: Update the remaining documentation occurrences of
“Sanitise”/“sanitise” to “Sanitize”/“sanitize” in the referenced security guide,
including the examples around the existing filename-sanitization checklist and
all additionally noted occurrences, while preserving the surrounding wording and
formatting.

In `@tests/test_typos_rollout.py`:
- Line 27: Add descriptive messages to every assertion in
tests/test_typos_rollout.py, including the assertions around spec loading at
line 27 and lines 66–69. Split the compound assertion into separate assertions
for spec and spec.loader, each with a clear failure message, and ensure all
remaining bare assertions use the assert expression, "message" form.
- Around line 319-327: The spelling gate test does not verify the required typos
configuration and exclusion flags. In
test_makefile_spelling_gate_uses_pinned_typos, add an assertion that Makefile
contains the exact command segment "--config typos.toml --force-exclude ."
alongside the existing generator and version assertions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: edfbc55a-a12b-4b46-ab1a-9f2e56c570ec

📥 Commits

Reviewing files that changed from the base of the PR and between b850e2f and cb1b1e4.

📒 Files selected for processing (46)

• .gitignore
• Makefile
• README.md
• add-repositories
• agents/subagents.yml
• bootstrap-common
• data/typos-oxendict-base.toml
• docs/adr/002-subagent-manifest-loader.md
• docs/cmd-mox-users-guide.md
• docs/developers-guide.md
• docs/execplans/adopt-vendcurl.md
• docs/srgn.md
• get-github-tooling
• hooks/test_post_turn_quality_stop_hook.py
• pyproject.toml
• rust-setup
• scripts/typos_rollout.py
• scripts/typos_rollout_cli.py
• skills/ansible-testing/SKILL.md
• skills/biomejs/references/lint-solutions.md
• skills/biomejs/references/strict-rules.md
• skills/code-review/SKILL.md
• skills/code-review/guides/performance-concerns.md
• skills/code-review/guides/security-issues.md
• skills/code-review/language-specific.md
• skills/code-review/templates/review-prompt.md
• skills/codescene-health-rules/SKILL.md
• skills/execplans/SKILL.md
• skills/firecrawl/SKILL.md
• skills/grepai/SKILL.md
• skills/hexagonal-architecture/SKILL.md
• skills/hexagonal-architecture/references/language-specific.md
• skills/implementation-postmortem/references/mvc-action-template.md
• skills/logisphere-design-review/SKILL.md
• skills/logisphere-design-review/references/expert-profiles.md
• skills/logisphere-experts/SKILL.md
• skills/logisphere-experts/references/expert-profiles.md
• skills/odw-authoring/SKILL.md
• skills/odw-supervision/SKILL.md
• skills/odw-testing/SKILL.md
• skills/sem/SKILL.md
• skills/zod4-typescript/SKILL.md
• tests/test_bootstrap_common.py
• tests/test_typos_rollout.py
• typos.local.toml
• typos.toml

All ten findings were addressed in c0bc7c5, the threads are resolved, and the replacement GitHub and local gates are green.