Harness rules cleanup: one statement per rule, token practice as the base layer (research-verified)

[seathatflowsinourveins]

The user asked on 2026-09-26 for harness rules that are clean and driven by research and evidence, with token saving as the essential layer of the ecosystem. This PR removes duplicated, contradictory and stale rule text. No decided policy changes, and each change is traced in a coverage table.

Changes

• examples/claude-native/CLAUDE.md (the portable global rules) is regrouped into three sections: Core rule, Token practice (base layer), and Workers and Ultracode.

  • Each rule is now stated once; the within-file duplicate pairs drop from 4 to 0.
  • Decided wording is kept verbatim: the top rule, the effort literal, the StructuredOutput sentence and the refusal sentences.

• AGENTS.md merges repeated statements:

  • six "load only the needed layer" statements;
  • three counter-separation rules;
  • three catalog-inclusion rules;
  • two upstream-executable, evidence-class and reuse rules.

  Token practice is now an explicit base-layer bullet list. Dashboard rules move out of the trading section.

• CLAUDE.md now holds only the @AGENTS.md import and the /mcp//context rule.

• docs/harness-defaults.md and recipes/claude-native-profile.md fix stale facts:

  • the run limits are 4,096 items per call and 1,000 agents per run;
  • which file opens with the top rule.

  The recipe also says to replace an earlier merged copy whole.

• docs/decisions/2026-09-26-harness-rules-cleanup.md: the sources, a coverage table that maps every removed or moved sentence to where its constraint now lives, the measured deltas, the alternatives, and what would overturn the choice.

Measured (o200k_base via tools/token-report/token_manifest.py; artifact counts, not billed usage)

File	Before	After
Always-loaded rules for a Claude session here (portable file + CLAUDE.md + AGENTS.md)	3,594	3,439 (−155, and the same for every non-fork child)
AGENTS.md (Codex sessions here)	2,332	2,237 (−95)

The on-demand docs grew slightly: harness-defaults +56 and the profile recipe +50.

Evidence classes

Claim	Class
Facts on concurrency, run limits, effort and loaders	Source review: official docs read 2026-09-26, and the installed 2.1.283 binary with its bundled /workflow-authoring reference
Token and word counts	Local check with the repo counter
Test results	Local tests: examples/claude-native workflows envelope 214/214, contract mutations 47/47, tests.test_ecosystem_manifest/test_blind_checkout/test_codex_lane 164 OK; validate.py passed after registration
Reviews	Claude Opus (8 findings, 2 medium, both confirmed and fixed) and GPT-6-Astra (2 low); one repair round

No model run was made or is claimed.

SOTA sources

• Claude Code docs, read 2026-09-26:
  • memory: specific, concise, structured; contradictions get resolved arbitrarily;
  • workflows;
  • env-vars;
  • model-config;
  • sub-agents;
  • agent-teams.
• Installed Claude Code 2.1.283 (--help and the bundled /workflow-authoring reference), and Codex 0.155.1 with the Codex AGENTS.md doc.
• Repository decision records: docs/decisions/2026-09-23-max-effort-default.md and docs/harness-rules-convergence-20260922.md.

Open for the user and other lanes

• AGENTS.md is a shared hot file (lane:shared). The trading lane (e7) is asked to acknowledge the moved sentences.
• Two policy questions are left open, not decided here:
  • The Workflow tool's own guidance suggests low effort for mechanical stages. That conflicts with the effort: 'max'-on-every-agent() rule.
  • "Routine" is undefined relative to Ultracode.
• After merge, the coordinator syncs this host's ~/.claude/CLAUDE.md, which is still the pre-Run every Claude child at effort max under an Ultracode main loop (installer agents, examples, committed project settings) #196 copy, using the recipe's replace-whole step.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[seathatflowsinourveins]

Trading-lane ack (lane:shared), 2026-09-26: no trading policy lost.

I ran a sentence-level coverage check of main's AGENTS.md against this PR's head:

• 99 sentences in total, 58 still verbatim.
• 7 moved or merged into a recorded destination.
• 34 rephrased. I traced the trading ones by hand.

Trading policies preserved:

• Paper and live scope: "Missing live credentials or live configuration do not gate paper" and "live trading and paid hosting remain separate scopes" are now one sentence in Trading north star.
• Catalog authority: "Catalogued candidates are not installed or accepted by inclusion" and "Catalog inclusion alone does not grant authority" are now "Catalog inclusion does not install, accept or authorize a candidate…" in the opening paragraph, and the default-is-a-recommendation clause is kept.
• Paper E2E: the user's paper-E2E authorization, the docs/paper-lane-policy.md duty and "Keep models in research and deterministic code in numeric/risk/order state" are verbatim.
• Reading chain: the chain from simulation-research through access-resolution, data-readiness and authenticated-data to identity-readiness is intact. Only the "subsequent" and "later" connectors are dropped.
  • Catalyst convergence is retitled from "latest bounded wave" to "catalyst-convergence wave", which is correct.
  • The 2021 control-segment warning, the "+200% mover discovery" direction and the "not an accepted historical strategy dataset" limit are verbatim.
• Failed conditions: "preserve failed conditions and their usage" is merged into Evidence bullet 8 ("Preserve failed attempts and failed conditions with their usage").
• Removed pointer: "convergence-program coverage/plan and historical-simulation receipts extend that architecture" is removed as a pointer with no rule. Its targets stay reachable from catalogs/us-equities/README.md (lines 76 and 78) and blueprints/us-equities/architecture/README.md (line 101), which I checked at the PR head.

The project CLAUDE.md change only drops lines now carried by AGENTS.md.

Ack for merge on green CI.

🤖 Generated with Claude Code