CLAUDE.md (new root instruction file, PR #1830) is outside ROOT_TEXT_FILES — the hygiene byte scan does not read it #1833

Activity

1. os-steve

   added

   ci/cdCI plumbing and the verification pipelineCI plumbing and the verification pipeline

   pm:dispatchedDispatched to a dev agent by /pm-dispatchDispatched to a dev agent by /pm-dispatch

   on Sep 10, 2026
2. os-steve

   self-assigned this

   on Sep 10, 2026
3. os-steve commented on Sep 10, 2026

   

   os-steve

   on Sep 10, 2026 – with Claude

   Collaborator

   More actions

   Claim: session_01DuzfS5chho38Yx1jxx9DEj → branch claude/issue-1833-hygiene-claude-md

   Dispatched by the hotcrm PM seat (#1353). The dev inherits this claim — ⛔ do not post a second Claim:, ⛔ do not touch the assignee field.

   Base off main at 62e23f5 or later (fetch origin/main fresh).
   Model: Opus, per 「没有 fable 派 opus」.
   Deliverable: one PR, ready for review, pnpm verify green. ⛔ Do not enable auto-merge and ⛔ do not merge — the PM arms the queue after reading your report.

   PM verification — the Blocked-by is cleared

   Measured on 62e23f5 (current main):

   • CLAUDE.md exists at the repo root — PR docs(agents): keep only what is necessary — metadata-application principle first, rules not narratives, no inventories; add CLAUDE.md pointer; correct the two *.workflow.ts briefs #1830 landed, so the gate's missing-file guard will not fire on the new entry. The card's Blocked-by: #1830 is discharged.
   • grep -c "CLAUDE.md" scripts/lib/source-hygiene-surface.mjs → 0. ROOT_TEXT_FILES still holds exactly the 15 entries the card lists (scripts/lib/source-hygiene-surface.mjs:179-195).

   So the finding is live and the fix is the one line the card describes. Alphabetical position is between CHANGELOG.md and CONTRIBUTING.md.

   What is NOT verified, and is yours to establish

   ⭐ The card asserts "no test edit is expected" — that is a hypothesis, not a measurement. The three sandbox suites materialise fixtures from rootFixture() and test/source-hygiene-scan-surface.test.ts asserts the gate prints ${ROOT_TEXT_FILES.length} root file(s), which follows the list if every reader derives from the constant. Check that no reader hard-codes 15, and if one does, that is part of this card.

   Proof obligation — this is a gate-surface widening, so prove the gate now READS the file

   Green is not the deliverable here; coverage is. Run the house three-leg shape:

   • CONTROL — plant a control byte in CLAUDE.md, show pnpm hygiene on the unmutated whitelist exits 0 (the byte is invisible today — that is the defect).
   • LEG — with 'CLAUDE.md' added, show pnpm hygiene exits 1 and names CLAUDE.md by path.
   • RESTORE by bytes — under trap … EXIT INT TERM; prove the post-restore blob hash equals HEAD, git diff HEAD --name-only empty, git status --porcelain empty.

   Capture every exit code before any pipe. Also run the three sandbox suites (test/source-hygiene-scan-surface.test.ts, -size-advisory, -header-position) and report the test-file / test counts before and after.

   Scope

   • ⛔ Do not re-shape the gate, do not touch its banner line (The hygiene banner binds the wrong count to the marker and header checks — it says 339 + 3 where those checks read allTs = 329, and two cards this round were told to trust that line as the producer #1339 owns that), do not move ROOT_TEXT_FILES to a different module.
   • ⛔ content/docs/releases/ is never edited in a code PR.
   • If the same class exists for another new root file, report it in out_of_scope_findings rather than widening the diff.

   ---

   Generated by Claude Code
4. os-steve commented on Sep 10, 2026

   

   os-steve

   on Sep 10, 2026 – with Claude

   Collaborator

   More actions

   os-dev-report

   {
     "issue": 1833,
     "status": "done",
     "branch": "claude/issue-1833-hygiene-claude-md",
     "pr": "https://github.com/objectstack-ai/hotcrm/pull/1842",
     "premise_still_valid": true,
     "summary": "Added 'CLAUDE.md' to ROOT_TEXT_FILES in scripts/lib/source-hygiene-surface.mjs, alphabetically between CHANGELOG.md and CONTRIBUTING.md. One line, plus an empty-frontmatter changeset; the gate's banner line, its shape and the constant's location are untouched. Both PM premises re-verified on 62e23f5 in my own worktree before editing: CLAUDE.md exists at the root (PR #1830 landed, Blocked-by discharged) and grep -c 'CLAUDE.md' on the surface module was 0 with the list at 15 entries. PR #1842 is OPEN and READY FOR REVIEW (draft=false), auto-merge NOT armed, nothing merged. Two observations for the PM. (1) The governed-path rule in AGENTS.md ('How a green PR lands') names CLAUDE.md, but it governs paths in the DIFF, not strings in it: git diff --name-only is scripts/lib/source-hygiene-surface.mjs and .changeset/hygiene-byte-scan-reads-claude-md.md, so the PR is correctly ready rather than a maintainer draft. CLAUDE.md was mutated only inside the ablation legs and restored byte-identical. (2) My standing dev contract says 'draft PR'; this dispatch and the claim comment both say ready-for-review. I followed the dispatch, which is also what AGENTS.md sanctions for a non-governed diff, and both agree on the safety half (no auto-merge, no merge). Flagging rather than silently picking a side.",
     "tests": "THE CARD'S HYPOTHESIS WAS TESTED AND HOLDS — no test edit needed, measured not assumed. No reader hard-codes 15: grep -rn '\\b15\\b' over scripts/check-source-hygiene.mjs, scripts/lib/source-hygiene-surface.mjs and all three sandbox suites returns exactly ONE hit, an unrelated prose sentence at check-source-hygiene.mjs:267 ('15 of 31 tasks in a demo org'). Actual suite filenames are test/source-hygiene-scan-surface.test.ts, test/source-hygiene-size-advisory.test.ts, test/source-hygiene-header-position.test.ts (the card's '-size-advisory'/'-header-position' spellings do not exist as filenames). COUNTS — three sandbox suites: 3 files / 53 tests BEFORE, 3 files / 54 tests AFTER (exit 0 both). Full pnpm test: 165 files / 3455 tests (3454 passed + 1 skipped) BEFORE, 165 files / 3456 tests (3455 passed + 1 skipped) AFTER, exit 0 both. The 'before' full-suite row is a READING, not arithmetic: taken with the fix ablated (git checkout 62e23f5 -- the surface file, changeset removed), ablation proven on disk first (ABLATED_surface_mentions_CLAUDE_md=0, blob b97d71c -> b9b89ea), restored byte-identical after. Zero test FILES edited; the +1 is the new it.each case 'reports a control byte in the root file CLAUDE.md (#838)', confirmed present by name in a --reporter=verbose run. THREE-LEG PROOF, every exit code captured before any pipe (cmd > log 2>&1; EXIT=$?). CONTROL: raw 0x01 appended to CLAUDE.md, whitelist untouched (mentions=0), mutation proven on disk (grep -caP '\\x01' = 1; blob 4e61283 -> 4934a7a) -> CONTROL_HYGIENE_EXIT=0, banner '15 root file(s)', gate prints 'no raw control bytes in first-party files', CONTROL_NAMES_CLAUDE_MD=0. The byte is not missed, it is never read. LEG: same byte, whitelist mentions=1, on committed HEAD 659e419 -> LEG_HYGIENE_EXIT=1, banner '16 root file(s)', 'CLAUDE.md:7  control byte 0x01 at column 9', LEG_NAMES_CLAUDE_MD=1. RESTORE by bytes after each leg, under trap '...' EXIT INT TERM with absolute paths from git rev-parse --show-toplevel, verified by STATE not by exit code: POST_RESTORE_BLOB=4e612837f9ef3f3baadac20d07077ad84db9b4ce equals HEAD_BLOB (non-empty check first), git diff HEAD --name-only = 0 lines, git status --porcelain = 0 lines, control-byte grep over CLAUDE.md exits 1 (none). Same proof for the ablation restore (surface + changeset blobs both equal HEAD, 0/0 lines). PNPM VERIFY, stage by stage on final commit 659e419, each redirected before capture: validate 0, typecheck 0, lint 0, lint:i18n-gate 0, hygiene 0, hygiene:tokens 0, build 0, test 0. hygiene:tokens unmoved (nothing authored under a ratcheted layer). CI on PR #1842 was NOT waited on — mergeable_state was 'unstable' (checks running) at report time, per the report-at-PR-time contract.",
     "mcp_calls": "5 — issue_read get #1833, issue_read get_comments #1833, issue_write create #1841, create_pull_request #1842, add_issue_comment (this report). Channel note: a repo-scoped REST read probe returned HTTP 200, so issue reads and the dedup pass ran over REST list endpoints plus local grep (70 open issues, one page, control term 'CLAUDE.md' returned 3 live hits including this card). The REST /search/issues endpoint returned HTTP 403 for this seat's credentials; I did not fall back to a wide MCP scan, I used the list-plus-grep channel the probe had already cleared. Declared as required.",
     "open_questions": [],
     "out_of_scope_findings": [
       "filed as #1841: nothing in this repo reads CLAUDE.md's CONTENT — measured, git grep 'CLAUDE\\.md' at 62e23f5 over test scripts .github docs e2e src exits 1 with ZERO hits, so after this PR the only reader is the byte whitelist, and the file's own stated contract ('Nothing is restated here, so there is exactly one instruction set to maintain') is unguarded. Includes the adjacent half: test/docs-role-hierarchy.test.ts:187 SCANNED and test/docs-src-tree-paths.test.ts:112/:174 TREE_DOCS are hand-maintained root-doc lists naming AGENTS.md without CLAUDE.md — the first is a live-but-vacuous gap, the second is probably correct as-is (CLAUDE.md names no src/ dir) and is recorded so the next reader need not re-derive that it was considered.",
       "NOT filed, reported as a closure instead: the card's own class does NOT exist for any other root file. 17 tracked files at the repo root vs 16 in ROOT_TEXT_FILES after this PR; the single difference is pnpm-lock.yaml, excluded by a written decision argued out beside the list and pinned from the other side by ROOT_EXCLUDED_FILES in test/source-hygiene-scan-surface.test.ts. Every tracked first-party root file is now scanned.",
       "NOT filed, environment observation for the PM: refs/remotes/origin/claude/issue-1833-hygiene-claude-md was PRUNED out from under this worktree by a sibling agent's fetch (refs/remotes/* is shared across worktrees via the common .git dir). Harmless here and it did not affect the push — git ls-remote is authoritative and confirms refs/heads/claude/issue-1833-hygiene-claude-md = 659e4196bb6f81104627487556bdc8459e533bb2 — but any dev reading branch state from a local remote-tracking ref in this container can be silently misled."
     ]
   }

   Worktree cleanup done — node_modules removed and git worktree remove exited 0; the three sibling worktrees (#1829, #1835, wt-1581) were left untouched. Evidence logs for every run above are retained under the session scratchpad at issue-1833/.

   ---

   Generated by Claude Code
5. os-steve

   closed this as completedin #1842on Sep 10, 2026