Top rule as an upstream-verification procedure, merit-only selection, and a dated anti-pattern log (user-approved global instructions) - #371

Scope

• What this PR changes, in one or two sentences: the portable user instructions (examples/claude-native/CLAUDE.md) now state the top rule as a five-step upstream-verification procedure at about the same length (881 → 896 words), and docs/harness-defaults.md gains its long form, "Upstream verification and compounding learning", with a dated, sourced anti-pattern log; AGENTS.md points to it in one sentence, and two test classes pin all of it.
• Base commit: dde28cc2; head commit: 3b8ae91d35e375daa07825c875793bdb8c58fd9c (4c6f9171 plus the review resolution under Review)
• Lane: lane:shared (AGENTS.md and manifests/evidence.json are shared hot files in docs/lanes.md); needs the trading lane's acknowledgement before merge.
• Owned paths touched: examples/claude-native/CLAUDE.md, docs/harness-defaults.md, AGENTS.md (one new paragraph after the top rule, well away from the pending WP5 edit near line 34), recipes/claude-native-profile.md (release note), tests/test_install_claude_profile.py, tests/test_adoption_docs_consistency.py, manifests/evidence.json (five re-registered hashes). Not touched: the verdict-wave frozen files, adoption/templates/codex.config.template.toml, and Codex user-scope instructions (the Codex text is staged separately for u4).

Authority and user decisions

examples/claude-native/CLAUDE.md is installed as every host's ~/.claude/CLAUDE.md, so this PR changes the user's global instruction text. The user approved the rewrite on 2026-09-26, in the workstation coordinator session:

• "the upstream repos are the source of truth, always find the sota upstream repos, docs etc ,make sure future session enact it ,so your mistakes can be avoided, always compounding leanring"
• "please make sure it is reflect as top rules and claude md ... manifest them into our claude md.github workflow,agentmd,rules and all related .md for all future sessions and pcs set up"

The follow-up commit adds four later decisions from the same day:

• "never files upstream report but fix with upstream deep dive ,don't assume it is upstream errors but is our methods of adaption, install , and wire methods are not sota upstream align"
• "license are not applibalbe for our env,as we are priviate experimental env not company"
• "keep it so the future session can avoid gates unnessary , focuing on the quality and sotaness of the repos itself compare to its candidates in that field"
• "don't use tavily when there are free llm native practice supreceeded it"

Lane consolidation: on 2026-09-26 the user shut down the other lane sessions and assigned this work to the workstation coordinator ("no other peers live, i shut them with the token save repos install into our native workflow and github workflow , harness update and sota foundation of our session as main task"); this quote stands in for the trading lane's ack.

SOTA sources

• anthropics/claude-code CHANGELOG.md (main; top entry 2.1.283, the installed client), read 2026-09-26 with gh api repos/anthropics/claude-code/contents/CHANGELOG.md -H "Accept: application/vnd.github.raw":
  • 2.1.260: "Added a text form of /advisor (/advisor, /advisor <model>, /advisor off) for the desktop app, Remote Control, and other headless (-p/Agent SDK) sessions".
  • 2.1.232: "Fixed the consent message for interactive --advisor fable launches ...".
  • 2.0.64: "Added support for .claude/rules/"; 2.1.84: rules paths: frontmatter accepts a YAML list; 2.1.69: InstructionsLoaded hook and conditional rules in -p.
  • 2.1.271: "Added omitClaudeMd to agent frontmatter ... letting custom and plugin subagents run without user, project and local CLAUDE.md files".
• Claude Code docs, read 2026-09-26: memory (user instructions in ~/.claude/CLAUDE.md are "Personal preferences for all projects"; rules without paths "are loaded at launch with the same priority as .claude/CLAUDE.md"; user-level ~/.claude/rules/; "if two rules contradict each other, Claude may pick one arbitrarily"); CLI reference (--advisor <model> "Takes precedence over the advisorModel setting"); subagents (omitClaudeMd).
• openai/codex: AGENTS.md guide (linked from docs/agents_md.md; global AGENTS.override.md, else AGENTS.md; project files root to cwd). Source at tag rust-v0.157.1 (commit ac0e23e5232692b95268583c8278c50b8c436d2b): codex-rs/core/src/agents_md.rs (reads each file as raw text; the file contains no @ character) and codex-rs/exec/src/lib.rs read_prompt_from_stdin (lines 2232-2248).
• rtk-ai/rtk v0.50.0 src/hooks/init.rs: RTK_MD_REF = "@RTK.md" and codex_rtk_md_ref (the @<CODEX_HOME>/RTK.md line), for the @-reference log row.
• mksglu/context-mode v1.0.169 (tag commit 442f1eb6c7cdad3f0cb2411d00756f9e5cf2b587) src/server.ts lines 1165-1200 (the Pin vendor skills for CC lane messaging, evals and logs #852 project-boundary guard for ctx_execute_file and its permissions.allow Read(...) escape hatch), and issues #852 (closed 2026-06-22) and #1075 (open), for the Context Mode row.
• procps-ng 4.0.4 pgrep(1): "The running pgrep, pkill, or pidwait process will never report itself as a match."
• GitHub Flavored Markdown Spec 0.29-gfm (https://github.github.com/gfm/), section 4.10 Tables, read 2026-09-26: "The header row must match the delimiter row in the number of cells. If not, a table will not be recognized", for the log checker's delimiter rule.
• This repository's existing rules: the AGENTS.md top rule (Top rule: research first, never self-write without a SOTA source; required sota-sources check #294); .github/pull_request_template.md ### SOTA sources and the required sota-sources job in .github/workflows/validate.yml (context listed in .github/main-ruleset.json); docs/decisions/2026-09-26-harness-rules-cleanup.md (Harness rules cleanup: one statement per rule, token practice as the base layer (research-verified) #327: one statement per rule, and its token-counting method); tools/token-report/token_manifest.py count_files (gpt-tokenizer 3.4.0, o200k_base) for the counts below.

Evidence-class table

Coverage of the template text that was replaced or tightened (one statement per rule, as in #327):

Follow-ups outside this PR (each is recorded, none is fixed here):

• tools/sota-convergence/landscape-sweep/codex_job.py still passes --search, and .claude/settings.json does not set CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION; the log states both "at this base".
• The Codex user-scope text is staged for the Codex-config owner as inlined text with a read-back marker, not installed; until it is, Codex sessions outside this repository do not see the rule.
• rtk's --codex mode writes an @<CODEX_HOME>/RTK.md reference that Codex does not expand. Per the user's rule, no upstream report is filed. The fix is ours: inline the Codex text, staged for the Codex worker-lane PR.
• rtk init --help at 0.50.0 describes --codex as using a PreToolUse hook, while evidence/artifacts/token-e2e-codex-20260926/receipt.json says Codex has no RTK hook; this needs a source check before it becomes a log row.
• The cross-family (GPT-6) review ran on 4c6f9171; its four findings are resolved in 3b8ae91d (see Review), which has had no second cross-family pass.

What this proves: the rule text is in the startup chain (the user-level ~/.claude/CLAUDE.md of a host that merges the example; AGENTS.md for Claude, through @AGENTS.md, and for Codex sessions in this repository), and CI pins it. What it does not prove: behaviour. No model run was made; nothing here shows that sessions or workers follow the check order or that the log prevents a repeat. Hosts that merged an earlier copy of the example do not change until they replace it (the recipe says so), and Codex user-scope sessions do not receive the rule until the staged block is installed and read back.

Local commands run

python is a venv with the CI test dependencies; the unittest summaries were read from stderr with the command's own exit code.

$ python -m unittest tests.test_install_claude_profile.PortableTopRuleTests tests.test_adoption_docs_consistency.UpstreamVerificationSectionTests -v   # before the text changes
FAILED (failures=4)   # the fifth test, the log checker's own mutants, passed from the start
$ python -m unittest tests.test_install_claude_profile tests.test_adoption_docs_consistency tests.test_ecosystem_manifest
Ran 128 tests ... OK (skipped=1), exit 0   # the skip is the existing ProfileTableTests coverage-difference case
$ python scripts/validate.py
{"components": 69, "hashed_files": 6990, "profiles": 4, "receipts": 159, "status": "passed"}
$ python scripts/evidence_manifest.py --check
{"files": 6990, "status": "passed"}
$ python scripts/build_ecosystem.py --check
{"status": "passed", ...}, exit 0
$ python scripts/component_matrix.py --check; python scripts/new_host_grand_list.py --check
{"rows": 32, "status": "checked"}; {"status": "passed", "layers": 32, "winners": 66}
$ python scripts/release_due.py   # before and after, compared
identical reports: none of the changed files is a new-machine file, so no marker is required; the two "changed after `v2026.09.26.2`" notes are informational
$ python -m unittest discover -s tests -q   # on 4c6f9171; the rerun on 3b8ae91d is under Review
Ran 6261 tests in 613.569s
OK (skipped=663), exit 0   # the two earlier runs of this change gave OK (skipped=642); the extra skips are not
                           # itemized (-q). Likely cause: tests that skip while another session holds the gitleaks
                           # per-user lock; a run of those modules right after skipped 6 for that reason
$ python -m unittest tests.test_gitleaks_config tests.test_pre_commit_gate tests.test_gitleaks_guarded_macos -v   # rerun once, lock free
Ran 44 tests in 93.765s: OK (skipped=9), exit 0   # the 9 skips run on macOS only

Decision record

No separate record; the alternatives and overturn condition are here.

• .claude/rules/ (user-level ~/.claude/rules/): supported since 2.0.64 and documented, but not used. Rules without paths load at launch with the same priority as CLAUDE.md, so they cost the same always-loaded context; omitClaudeMd is documented for CLAUDE.md files only, so a rules file could reach the blind verdict lanes; and the profile installer has no rules step. Path-scoped rules load only when matching files are read, which does not fit a rule about every claim.
• Appending the procedure to the old paragraph was rejected for the flat-length constraint; three Core rule lines it covers were folded into it instead (evidence-not-authority, supported install commands, the harness-feature research order).
• Overturn: a measured comparison showing that a rules file or a different placement keeps the same startup cost while reaching the same sessions, or a behaviour trial in which sessions with the procedure still relay unchecked absence claims.

Host evidence

Not applicable: no files under evidence/hosts/.

Checklist

• New/changed GitHub Actions are pinned to a full commit SHA with a version comment (no floating tags). (none changed)
• New/changed workflows declare top-level permissions: contents: read (or a narrower, explicitly justified addition). (none changed)
• No secrets are printed, logged or committed; no new required secret was added without a documented owner.
• No new paid hosting, subscription or billing surface was introduced.
• Peer-owned untracked files and worktrees were preserved (not deleted, moved or overwritten).

Follow-up commit b0a6928 (coordinator)

• Top rule:
  • Step 1 now judges candidates head-to-head on measured quality, security and maintenance; license, stars, installs and incumbency are not criteria.
  • Step 3 adds "Never file upstream issues or comments: when a tool misbehaves, study upstream and fix our install or wiring."
  • The template is 924 words, within the 925 ceiling that PortableTopRuleTests pins.
• docs/harness-defaults.md:
  • The stale Tavily paragraph is replaced with the free native web lanes: Claude WebSearch/WebFetch, Context Mode ctx_fetch_and_index, Codex -c web_search="live", and keyless tools once a measured bake-off adopts them.
  • The foundation section adds merit-only selection and the "fix our side, never file upstream" rule.
  • The context-mode log row now ends in "fix our install or wiring; never file upstream".
  • Three new dated rows: license gating; disabling skills instead of routing them (skillOverrides: "off" blocks an agent's skills: preload, per a headless --agents probe on 2.1.283); and a paid keyed web API used where free native lanes work.
• Checks: validate.py, evidence_manifest.py --check, build_ecosystem.py --check, component_matrix.py --check and new_host_grand_list.py --check all exit 0. The touched modules (test_install_claude_profile, test_adoption_docs_consistency, test_ecosystem_manifest) ran 128 tests OK (1 skipped). Gitleaks: no leaks.
• Not covered: the follow-up text has had no cross-family pass of its own.

Review

Cross-family review of 4c6f9171: GPT-6 through codex exec (read-only, -c web_search="live"), exit 0, no usage-limit hits, about 220 s, 160,020 tokens by Codex's own report, 2 live searches. It reported four defects. Each was checked at source, all four hold, and 3b8ae91d resolves them.

As the PR's own correction rule requires, the log gains a dated row for the lesson ("Summarizing evidence more strongly than its source"), and that rule now says to name a check as enforcement only after seeing it fail on that mistake or a reproduction of it. The template is 896 words, 2 more than at 4c6f9171, because a one-word path became "any anti-pattern log the project declares".

Review coverage: the reviewer's two live searches covered Codex guidance discovery and the GFM table rule. It did not visibly re-verify the other upstream claims under SOTA sources: the Claude Code CHANGELOG /advisor entries, read_prompt_from_stdin at rust-v0.157.1, rtk v0.50.0 src/hooks/init.rs, context-mode #852 and #1075, procps-ng pgrep(1), and the CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION default. Its silence on them is not confirmation, and 3b8ae91d has had no second cross-family pass.

Commands run for the resolution (python is the same venv with the CI test dependencies; each summary read from stderr with the command's own exit code):

$ python -m unittest tests.test_adoption_docs_consistency.UpstreamVerificationSectionTests   # mutant added, old checker
FAILED (failures=1)   # 0 != 1 for the short-delimiter mutant
$ python -m unittest tests.test_install_claude_profile.PortableTopRuleTests   # new check, 4c6f9171 template
FAILED (failures=2)   # "the top rule names this repository's docs/harness-defaults.md, which other projects lack"
$ python -m unittest tests.test_install_claude_profile tests.test_adoption_docs_consistency tests.test_ecosystem_manifest
Ran 128 tests ... OK (skipped=1), exit 0
$ python -m unittest tests.test_credential_status tests.test_blind_checkout tests.test_catalog_freshness_propose \
    tests.test_landscape tests.test_layer_verdicts tests.test_retrieval_quality_v2 tests.test_record_verdicts \
    tests.test_sota_convergence   # the other modules that reference these paths
Ran 577 tests ... OK, exit 0
$ python scripts/validate.py
{"components": 69, "hashed_files": 6990, "profiles": 4, "receipts": 159, "status": "passed"}
$ python scripts/evidence_manifest.py --check; python scripts/host_receipts.py validate
{"files": 6990, "status": "passed"}; {"receipts": 167, "status": "passed"}
$ python scripts/build_ecosystem.py --check; python scripts/component_matrix.py --check; python scripts/new_host_grand_list.py --check
each exit 0: "passed"; {"rows": 32, "status": "checked"}; {"status": "passed", "layers": 32, "winners": 66}
$ python scripts/release_due.py   # before and after the commit
identical reports (informational; strict: false)
$ python -m unittest discover -s tests -q   # on 3b8ae91d
Ran 6261 tests in 620.100s
OK (skipped=642), exit 0   # the same count as the change's two earlier clean runs

Replay and second review round (coordinator, 2026-09-26)

• Replay. The branch was rebuilt onto main 4a32e646 as one commit, 28ef5496, under the hot-file protocol: main's manifests/evidence.json, with the six changed files re-registered. git diff b0a6928a 28ef5496 over those six files is empty. validate.py FAILS=0, verdict gate: no verdict rows changed, 596 tests OK.
• Second GPT-6 round on the follow-up b0a6928a (codex exec, gpt-6-astra, max effort, read-only, live search, rc=0). It found two medium defects, and both hold at source:

• Reviewer's own checks: the template is 924 of 925 words; five structural tests and validate.py pass; the manifest changes carry only the doc hashes.
• Reviewer's "unverified" notes:
  • The probe output is now retained in the addendum.
  • The GPT-6 license re-vote cited by the license row is not published yet. The row now says so: its output is published with the verdict wave.
• After the repair: validate.py FAILS=0. The docs, profile, skills, kernel-keyring and render-config modules ran 245 tests OK. 870bd32e has had no third cross-family pass (the bounded loop allows one review and one repair per round).
• Moved out of this PR: the context trim (the Ultracode section behind an on-demand pointer, the dedupe between the global template and AGENTS.md, the find-command wording) becomes its own PR with the AGENTS.md trading-section move.

🤖 Generated with Claude Code