Skip to content

Navigation Menu

Sign in
Sign up

docs: retire the warning sign from the five shipped operator docs (BACKLOG #1265) - #952

Merged
wshallwshall merged 2 commits into
main from
claude/warning-sign-retire-1265
Sep 8, 2026
Merged

docs: retire the warning sign from the five shipped operator docs (BACKLOG #1265) #952
wshallwshall merged 2 commits into
main from
claude/warning-sign-retire-1265

Conversation

@wshallwshall

@wshallwshall wshallwshall commented Sep 6, 2026
edited
Loading

Copy link
Copy Markdown
Collaborator

Retires the warning sign (U+26A0) from the five shipped operator docs, which BACKLOG #1265 names
as its defensible first slice. The item stays open: the two ledger files and the ADR decision are
untouched and still sequenced last.

What changed

17 sites in SECURITY.md, PHI.md, INSTALL-GUIDE.md, DEPLOYMENT.md and CONNECTIONS.md now
say the word the sentence means. Not a mechanical substitution, so the words differ by meaning:

Word Count Chosen when
WARNING 5 acting on the surrounding text leaves something insecure, silently
CAUTION 5 relying on the claim as written is the error
NOTE 5 it corrects a likely misreading and the failure is loud
a named referent 2 the glyph was the cross-reference target

The 2 cross-references are the ones worth reading. CONNECTIONS.md said "see the [glyph]
above"
and "the whole point of the [glyph] above", the second one 60 lines from its target.
Neither told a reader which mark was meant. They now name the [inbound]-versus-inbound(...)
distinction they point at. That is the exact scope defect CLAUDE.md section 11 describes, so these
two are the argument for the sweep rather than a side effect of it.

CLAUDE.md section 11 now carries a fresh census. The BACKLOG item gets a dated amendment.

The three required proofs

1. Census, ledger counts as the positive control. Counted over git-tracked files decoded as
UTF-8, at 172b1327c.

 before after
docs/SECURITY.md 5 0
docs/PHI.md 2 0
docs/INSTALL-GUIDE.md 1 0
docs/DEPLOYMENT.md 2 0
docs/CONNECTIONS.md 7 0
SLICE TOTAL 17 0
REPO-WIDE 496 / 75 files 479 / 70 files
positive control docs/BACKLOG.md 127, BACKLOG-CLOSED.md 93 (both passes)

The slice reaches zero while the control still reports non-zero on the same pass, so the zeros
are the files and not a dead pattern.

2. The grep escape was avoided rather than survived. No shell pattern was used. The census and
the test both build the codepoint in Python (chr(0x26A0), "\N{WARNING SIGN}"), so no non-ASCII
byte and no \u escape ever crossed a shell. The instrument was still checked against the figure
everyone agrees on before any zero was trusted: it reproduces docs/BACKLOG.md at 127 and
BACKLOG-CLOSED.md at 93.

3. backlog_status_check.py still passes at its full item count. Identical before and after
the amendment: OK - 679 backlog items, each declaring exactly one status, scanning
docs/BACKLOG.md (442) and BACKLOG-CLOSED.md (237), exit 0. The one advisory warning is
pre-existing (#1426, unrelated). parse_items reports #1265 still open, closed=[] - exactly
one status banner.

Two rows of the filed census table are wrong, and both are left standing

Corrected in CLAUDE.md section 11, not edited in the ledger table, because the wrong version is
what a later reader would otherwise re-derive. Both are SDS-3.8, an answer to an adjacent question:

  • The web console is not zero. The table reads it as zero by counting packaging/. The
    console's source is messagefoundry_webconsole/ (36 tracked files), which carries 2 -
    _external.py and routes/oidc.py. The item's prose claim "the web console has NONE" is
    false at this ref.
  • There is no harness/ row at all, so 26 occurrences across 4 files sat outside every
    bucket. The filed buckets sum to 464 against a printed 496; the corrected ones sum to 479.

My file count (75) differs from both the filed 80 and the re-scored 81. I did not chase the
difference: my denominator is stated (git-tracked, UTF-8 decodable) and the buckets sum to the
total, which the filed ones do not.

Decisions the brief left open

  1. Added a regression guard, tests/test_operator_docs_no_warning_sign.py, and registered it
    in two places the brief did not mention. Both were necessary rather than optional:
    tests/tooling_manifest.txt (without the entry test_tooling_partition.py fails, reddening
    three required legs - measured) and ci.yml DOC_GUARDS (the guard's whole subject is
    Markdown, so the code == 'true' gated pytest legs skip the only change class that can break
    it - the docs-only blind spot the step's own comment records twice).
  2. The positive control is planted in the test, not borrowed from docs/BACKLOG.md. Borrowing
    the ledger's 127 would make this guard red for the wrong reason the day the last slice of #1265
    lands.
  3. The guard also refuses an orphan U+FE0F. Every U+26A0 in this corpus trailed one, and a
    stray variation selector is invisible in review.
  4. _SWEPT holds repo-relative paths, not bare names, so a later slice extends it by adding a
    line. What remains is not all under docs/.
  5. Paragraphs were not reflowed. Two replacements left a line slightly long. There is no
    markdown line-length lint, and at least four other live sessions have these files open, so a
    minimal diff is worth more than a tidy wrap.
  6. Did not build a census baseline file. See the open question below.

Checks

Check Result
ruff check / ruff format --check pass
mypy strict, CI scope (messagefoundry messagefoundry_webconsole) pass, 284 files
mypy strict on the new test pass (CI does not type-check tests/)
new test, red-first 10 failed, 1 passed against pre-sweep content
new test, after 11 passed
doc-contract tests over the five edited files 420 passed
registration + ledger tests 96 passed
pre-commit (both commits) all hooks pass, no --no-verify
full pytest -q did not complete - 3156 passed, 45 skipped, 0 failed, 0 errors through 57%, then the host killed it. See below.

Red-first counted by case, not by "something went red". Reverting the five docs to their
pre-sweep content and running the new module gave 10 failed, 1 passed: the 5 glyph cases and
the 5 orphan-selector cases, each naming its file, with the positive control the single pass. The
control passing is what makes the 10 reds mean the files rather than a broken scanner.

The full suite did not finish, and I am not claiming it passed. Two runs against the committed
tree were killed by the host for memory pressure, not by a test - this box is running a dozen or
more concurrent sessions. The first reached 57% with 3156 passed, 45 skipped, 0 F, 0 E
(counted off the progress characters, not inferred from the absence of a summary line); the second
was killed at 4% with the same shape. That is partial evidence, not a pass. I stopped after two
attempts rather than grind.

What makes this a low-risk gap rather than an unknown: the change touches no engine code. It is
five Markdown files, two ledger/record documents, one new test, one manifest line and one workflow
line. Every test that can read those files was run to completion and named above.

Legs a Builder cannot see, which must be read on the runner: windows-service-smoke (NSSM),
and the docs-only lane itself - this PR changes DOC_GUARDS, so the doc-guards step's membership
and the tooling job's manifest gate should both be confirmed green there.

Concurrency

Ten or more live sessions have these files open. tooling_manifest.txt had uncommitted changes
in another worktree when I edited it; I compared the entry sets first - that session adds
test_verdict_divergence_advisory.py 24 lines away from my insertion, so the two additions merge
cleanly. SECURITY.md, PHI.md, CONNECTIONS.md, BACKLOG.md and ci.yml all carry committed
changes on other branches. My edits are single-line and glyph-scoped, but a rebase is likely.

Merge safety

main moved one commit under this branch (ebdfa44a6), touching docs/BACKLOG.md and
docs/CONNECTIONS.md. git merge-tree --write-tree origin/main HEAD exits 0: both auto-merge,
no conflict. A clean merge is not the question that matters though, so the merged tree was
censused directly - all five swept files are still 0, and the control still reads 127. The PR
shows BEHIND, not CONFLICTING.

Two things found in passing, outside this slice

Named rather than numbered, since I have allocated neither.

  1. The banner alphabet is used decoratively outside the two sanctioned files. Measured at this
    ref: docs/CONNECTIONS.md carries 124 U+2705, 18 U+274C and 3 U+23F3 in its connector-parity
    table, and docs/PHI.md carries 2 U+2705. CLAUDE.md section 11 says nothing outside
    BACKLOG.md and BACKLOG-CLOSED.md may adopt that vocabulary. That is a different
    population
    from #1265 and wants its own item. The new test's docstring says so explicitly, so
    nobody reads a green run here as covering it.
  2. Nothing stops the unswept population growing. The item's own re-score measured it drifting
    up, 496 to 499 in six days with nobody sweeping. A prose number in two documents, verified by
    nothing, is the instrument that already failed here twice. The repo's idiom for this is a
    checked-in baseline the guard re-derives and ratchets downward
    (scripts/quality/username_access_key_baseline.txt, scripts/docs/asvs_tally_baseline.txt).
    Deliberately not built here - it is machinery for the whole population, and this brief scoped me
    to one slice.

Generated with Claude Code

https://claude.ai/code/session_01Mk1rsUuxp823qZs4tecMd6

wshallwshall and others added 2 commits September 6, 2026 16:54
...ocs (BACKLOG #1265)
Replace 17 U+26A0 sites across SECURITY.md, PHI.md, INSTALL-GUIDE.md,
DEPLOYMENT.md and CONNECTIONS.md with the word each sentence means:
5 WARNING, 5 CAUTION, 5 NOTE.
Two of the 17 were cross-references pointing at the glyph itself, one of
them 60 lines from its target. Those now name what they point at, which
is the scope defect CLAUDE.md section 11 describes rather than a
find-and-replace.
tests/test_operator_docs_no_warning_sign.py pins the slice at zero and
also refuses an orphan U+FE0F, since every glyph here trailed one and a
stray selector reviews as clean. Its positive control is a planted
string, not the ledger counts: the last slice of #1265 sweeps
docs/BACKLOG.md, and a control there would then red this guard for the
wrong reason.
The guard is registered where it can actually run: tooling_manifest.txt
(without it test_tooling_partition.py reds three required legs) and
ci.yml DOC_GUARDS (its whole subject is Markdown, so the code-gated
pytest legs skip the only change class that can break it).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mk1rsUuxp823qZs4tecMd6 
CLAUDE.md section 11 carried the filed 496 across 80 files at ae76b9f.
Re-censused over git-tracked files at 172b132: 496 across 75 before
this PR's sweep, 479 across 70 after it.
Two rows of the filed table were instrument errors (SDS-3.8), and both
are corrected in section 11 rather than in the ledger table, which is
left standing so a later reader cannot re-derive it:
 - the web console was read as zero by counting packaging/. The
 console's source is messagefoundry_webconsole/, which carries 2.
 - there was no harness/ row at all, so 26 occurrences across 4 files
 sat outside every bucket. The filed buckets sum to 464 against a
 printed 496; the corrected ones sum to their own total.
The distribution is written once, in section 11. The BACKLOG amendment
records what landed and cites it rather than restating ten numbers
(SDS-3.5).
The item stays open. The two ledger files and the ADR decision are
untouched and still sequenced last.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mk1rsUuxp823qZs4tecMd6 
@github-actions github-actions Bot added the ci-red A required check went red. Attribute it before retrying. label Sep 7, 2026

Copy link
Copy Markdown
Collaborator Author

Lander: re-ran the failed jobs on run 34062541550, and recording that here because the
test's own failure message requires it.

What failed: repo harness tests (windows-2025), one test against a green suite.

FAILED tests/test_worktree_gate_control_plane.py::test_a_RELATIVE_repository_token_composes_the_cd_prefix
 - AssertionError: PWSH LAUNCH TIMED OUT after 45s (BACKLOG #1304).
1 failed, 3329 passed, 18 skipped, 8 xfailed, 12 warnings in 1196.24s (0:19:56)

Why this is not a defect in this PR: the failure is a pwsh child process launch that never
returns. No gate logic runs, so no assertion is evaluated. It is the known launch flake filed
as BACKLOG #1304, it lands on a different test name on every PR that hits it, and this PR's
diff does not touch the gate, the hook, or conftest.

The CI gate failure is the aggregator reporting the leg above, not an independent failure.

Honesty note, which is the reason this comment exists: BACKLOG #1304 is unfixed and its cause
is unmeasured. A green on this re-run is a green earned on a re-run of a known flake, not
evidence that anything was repaired. If the same marker reds again, this PR should be reported
as blocked by #1304 rather than re-run in a loop.

Co-Authored-By: Claude Opus 5 noreply@anthropic.com

Copy link
Copy Markdown
Collaborator Author

Lander note: rerunning the failed repo harness tests (windows-2025) job only, not the suite.

The failure is the BACKLOG #1304 pwsh launch timeout, which is a process launch that never
returned rather than an assertion about this branch. No gate logic ran, so it is not evidence
of a regression here.

Recording the rerun rather than doing it silently, because that test's own failure message
asks for exactly that: a manufactured green and an earned one are otherwise indistinguishable.

New evidence from PR 986, which instruments this timeout: on its own run both child streams
were empty and pwsh 7.6.5 resolved correctly, so it is not a missing interpreter, a bad PATH
or a crashed process -- it is a launch that never got scheduled. Consistent with the runner
contention this repository is under tonight.

wshallwshall added this pull request to the merge queue Sep 8, 2026
@github-actions github-actions Bot added the unread Green and mergeable, but not marked read. Read it, then add: reviewed label Sep 8, 2026

github-actions Bot commented Sep 8, 2026

Copy link
Copy Markdown

@wshallwshall

This pull request is green and nobody has marked it read.

Every check that has reported is passing and the reviewed label is absent, so
a reviewer has read this is the only thing between it and a merge. Nothing else reports that, which is
why this comment exists (BACKLOG #1413).

To clear it, IN THIS ORDER:

  1. If the branch is behind main, update it FIRST: gh pr update-branch --repo MEFORORG/MessageFoundry 952.
    That push fires synchronize, and synchronize REMOVES the reviewed label. Labelling
    before updating throws the label away and costs a round trip.
  2. Read the diff.
  3. gh pr edit 952 --repo MEFORORG/MessageFoundry --add-label reviewed

DO NOT TRIAGE THIS FROM mergeStateStatus. It returns one value with precedence, so BEHIND,
DIRTY and UNSTABLE each mask the missing check -- the requirement is invisible until you act on
something else. This check never reads that field; see scripts/ci/check_unread_prs.py.

A seat can find every pull request in this state in one call: gh pr list --label unread.

Adding reviewed withdraws unread: the label event re-evaluates this pull request,
and so does the next completion of a watched workflow. Those are the two edges that clear it, so a
change neither of them reports -- converting to a draft, say -- can leave the label standing until one
of them next happens.

The reviewed label is a PROCESS gate. It records that a step happened. It does not
establish that an independent party looked, and nothing here should be read as saying it does.

Merged via the queue into main with commit 2e3d5d2 Sep 8, 2026
81 of 85 checks passed
wshallwshall deleted the claude/warning-sign-retire-1265 branch September 8, 2026 06:07
@github-actions github-actions Bot removed the unread Green and mergeable, but not marked read. Read it, then add: reviewed label Sep 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

ci-red A required check went red. Attribute it before retrying.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

AltStyle によって変換されたページ (->オリジナル) /