microsoft / microsoft/hve-core

Post-merge follow-ups from PR 2934: stem dictionary, OWASP citations, announcement coalescing

Open
#2,952 0 comments 0 reactions 1 assignee Claimed by @WilliamBerryiii View on GitHub
accessibility maintenance stale-docs testing
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

## Issue Description

Tracks the remaining post-merge follow-ups from PR #2934. Supersedes #2947, which carries the detailed verification evidence referenced below.

PR #2934 is cited as the origin of these items only. Its review findings are closed and are not reopened here.

## Done and ready for review

Two repairs are complete on a branch and need review, not more work.

### 1. Word-stem dictionary reduced from 139 entries to 44

`.cspell/word-stems.txt` claimed a stem such as `compl` accepts any token beginning with it. That is false; cspell matches whole words here, so each entry only ever permitted its exact token.

The entries also had more than one origin, which the original write-up got wrong. Attribution across the spell-check glob found three sources:

- truncated generated grader names, for example `...-signal-compl-a5d0ffac`
- hand-authored identifiers, for example `per-stim` in `docs/contributing/evals-ci.md` and `prereq.json` in the accessibility runbook
- hand-authored regex fragments, for example `(?is)(revalidat|validat|check)` in `evals/agent-behavior/stimuli/code-review.yml`

Generated names are now covered by an `ignoreRegExpList` pattern, which also reaches the frozen alias map without excluding any file. 23 entries had no occurrence anywhere and were removed outright. The 44 that remain are genuinely hand-authored.

Verified three ways: 844 files checked both before and after, so no file became unchecked; 0 issues; and a probe containing `sentance` and `validatxyz` still reports both.

### 2. Six OWASP citations updated, two deliberately left alone

OWASP moved from `owasp.org/www-project-` to `owasp.org/projects/`. All 8 legacy URLs were checked individually rather than assuming a mechanical rename, which mattered: two of them 404 under **both** schemes.

Six were replaced after confirming each destination resolves and is the same OWASP project. Full table in #2947.

Two were left unchanged because no replacement was found and none was guessed:

- `https://owasp.org/www-project-top-10-ci-cd-security-risks`
- `https://owasp.org/www-project-ai-security-and-privacy-guide`

These need someone who knows the current OWASP inventory, or a decision to cite a different source.

## Remaining work

### 3. Announcement coalescing has no runtime evidence

Walkthrough step announcements are coalesced behind a 150 ms settle timer so a superseded step does not speak. Both decks implement it; both assert it only in source text. `docs/docusaurus/e2e/slides.spec.ts` asserts slide-change announcements only.

This is the behavior most likely to regress silently, because it is timing-dependent.

**Done when:** a browser assertion advances the walkthrough faster than the settle delay and observes a single settled announcement, and that assertion is proven to fail when the timer is removed. The proof must account for the spec loading a bundled page rather than `deck.js`, so the mutation has to travel through `slides:build` and the Docusaurus staging step, and the tree must be restored afterwards.

## Decisions recorded, no change proposed

### 4. `_intent.py` POSIX gate

49 of 84 tests in `test_intent.py` fail on Windows because `_require_secure_write_support` requires POSIX `dir_fd`, `O_DIRECTORY`, and `O_NOFOLLOW`.

**This is not a coverage gap.** The `Python Tests (.github/skills/accessibility/accessibility)` lane runs on Linux and reported `600 passed`, reconciling exactly with the 516 that run locally plus the 84 intent tests.

Relaxing the precondition would weaken a deliberate security control for local convenience. No change proposed.

### 5. Broken links are detected weekly and go nowhere

A full-repository link check already runs weekly with `changed-files-only: false`, so coverage was never missing. But it sets `soft-fail: true` and concluded `success` on 2026-09-14 while the repository contained two confirmed 404s, and `create-stale-docs-issues` is gated on `msdate-freshness` failure so link results feed nothing.

Proposal and reasoning in #2947. Not applied, because it is shared CI configuration and the false-positive volume of a stricter gate is unknown.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.