Merge pull request #275 from anipotts/codex/remove-litotes

docs: state public claims directly

Author: anipotts

.github/workflows/validate.yml

@@ -123,6 +123,11 @@ jobs:
             exit 1
           fi
 
+          if git grep -n -iE '\bnot (only|just|merely|simply|uncommon|insignificant|impossible|bad|wrong|unreasonable|unlikely|automatically|enough)\b|\bno (small|minor|mean|little)\b' -- '*.md' ':(exclude)CHANGELOG.md' ':(exclude)plugins/**/CHANGELOG.md'; then
+            echo "litotes or negative comparison framing found"
+            exit 1
+          fi
+
   markdown:
     runs-on: ubuntu-latest
     timeout-minutes: 10

AGENTS.md

@@ -10,6 +10,7 @@ this repository is an opinionated, source-backed handbook for experienced coding
 - do not use generated activity, commit frequency, or vendor benchmarks as evidence of quality.
 - keep the voice direct, lowercase, and professional. avoid hype, fan language, and unsupported authority claims.
 - do not use mid-dot dividers in public copy or interface labels.
+- never use litotes or negative comparison frames in public copy. state the intended claim directly.
 - repeat context only when it changes understanding or supports a deliberate editorial rhythm. remove labels that restate the title, route, or surrounding section.
 - preserve compatibility paths through 2026-11-05. legacy changes are limited to security, data-loss, and installation blockers.
 

CLAUDE.md

@@ -9,6 +9,9 @@ this repository is an opinionated, source-backed handbook for experienced coding
 - prefer primary sources and record them in `docs/sources.json`.
 - do not use generated activity, commit frequency, or vendor benchmarks as evidence of quality.
 - keep the voice direct, lowercase, and professional. avoid hype, fan language, and unsupported authority claims.
+- do not use mid-dot dividers in public copy or interface labels.
+- never use litotes or negative comparison frames in public copy. state the intended claim directly.
+- repeat context only when it changes understanding or supports a deliberate editorial rhythm. remove labels that restate the title, route, or surrounding section.
 - preserve compatibility paths through 2026-11-05. legacy changes are limited to security, data-loss, and installation blockers.
 
 ## verification

docs/claude-code/README.md

@@ -26,7 +26,7 @@ evidenceRail:
 
 primary source: [official claude code documentation](https://code.claude.com/docs/en)
 
-local note: 2.1.220 is installed, but the current hands-on protocol in [methodology](/method/) has not been rerun for this reset. recommendations below that depend on current product behavior are therefore source-verified rather than presented as fresh comparative testing.
+local note: 2.1.220 is installed. the current hands-on protocol in [methodology](/method/) remains pending for this reset, so recommendations that depend on current product behavior use source-verified evidence.
 
 ## current shape
 
@@ -85,7 +85,7 @@ third-party plugins run with meaningful local access. review their hooks, comman
 
 claude code desktop combines chats, diffs, previews, files, plans, tasks, terminals, and subagent views. this can reduce the attention cost of moving among a terminal, browser, editor, and pull-request page.
 
-the benefit is supervision, not lower compute use. several local sessions can still duplicate worktrees, dependencies, build processes, file watchers, browser instances, and model requests.
+the desktop benefit is supervision. compute use can still grow as local sessions duplicate worktrees, dependencies, build processes, file watchers, browser instances, and model requests.
 
 ## permissions and safety
 
@@ -97,7 +97,7 @@ permission mode, sandboxing, hooks, managed policy, and operating-system access
 - inspect plugin and mcp provenance before granting access.
 - preserve user approval for destructive or difficult-to-reverse actions.
 
-hooks are useful enforcement, but a hook only covers events and payloads it actually receives. do not describe a hook as a complete security boundary without testing bypasses and failure behavior.
+treat each hook as enforcement for the events and payloads it receives. test bypasses and failure behavior before assigning it responsibility for a security boundary.
 
 ## memory and session continuity
 

docs/codex/README.md

@@ -52,7 +52,7 @@ use the smallest durable surface that matches the rule:
 | mechanical lifecycle enforcement | hook |
 | recurring background work | scheduled task in the desktop or web surface |
 
-keep required team rules in version control. memory is useful recall, not the only copy of a constraint that must always apply.
+keep required team rules in version control. use memory for recall and checked-in files for constraints that must always apply.
 
 ## the working loop
 
@@ -69,7 +69,7 @@ codex responds well to an explicit terminal condition: what must be true, what p
 
 the desktop app can create codex-managed worktrees for parallel chats. this is usually the cleanest local default when two tasks should produce independent diffs.
 
-worktrees isolate tracked files and branches. they do not eliminate shared resources. package caches, local databases, ports, browser profiles, running services, and external accounts can still collide.
+worktrees isolate tracked files and branches. package caches, local databases, ports, browser profiles, running services, and external accounts remain shared and can still collide.
 
 use subagents for read-heavy parallel work such as repository exploration, test triage, source research, or independent review. use separate worktrees when agents need to edit independently or run conflicting application instances.
 
@@ -84,7 +84,7 @@ choose the surface by the next review action:
 - use the ide extension when selection context, debugging, and inline diffs dominate.
 - use cloud work when the task benefits from isolation or should continue without the local machine.
 
-changing surfaces can preserve the same project context, but it does not guarantee identical tools or permissions. verify the effective environment after a handoff.
+changing surfaces can preserve project context while tools and permissions vary. verify the effective environment after a handoff.
 
 ## permissions and automation
 
@@ -104,7 +104,7 @@ local codex memories can summarize useful context from eligible prior chats. the
 
 use memory for preferences, recurring context, and useful recall. use `AGENTS.md`, checked-in docs, config, or a skill for requirements another engineer must be able to inspect and reproduce.
 
-review generated memory before sharing codex state. secret redaction reduces risk but does not make the entire state directory appropriate for publication.
+review generated memory before sharing codex state. publish purpose-selected excerpts after redaction because the state directory can contain private context beyond secrets.
 
 ## where older comparisons went wrong
 

docs/field-lab/README.md

@@ -20,7 +20,7 @@ evidenceRail:
 
 the field lab evaluates coding-agent systems through repeatable engineering work.
 it measures what the operator must understand, supervise, recover, and verify.
-it does not produce a single winner score.
+its output is comparable run evidence rather than a single winner score.
 
 ## protocol
 
@@ -57,20 +57,20 @@ run records conform to the repository [run schema](https://github.com/anipotts/c
 include commits, pull requests, test logs, screenshots, and concise design-review
 notes.
 
-the following never belongs in a public run:
+exclude these from every public run:
 
 - raw chat or agent transcripts.
 - credentials, environment values, or account identifiers.
 - private repository names or private absolute paths.
 - personal data unrelated to the engineering result.
-- inferred token cost when the product did not expose it.
+- inferred token cost when the product leaves it unavailable.
 - a success claim without evidence from the layer it describes.
 
 ## interpretation
 
 elapsed time is useful only with operator interventions and review time beside it.
-tool-call count can describe a run, but it does not establish quality. resource
+tool-call count can describe a run. quality requires review evidence from the resulting work. resource
 measurements must identify what ran locally and what remained provider-hosted.
 
 comparative conclusions require comparable runs. a missing run remains visible as
-`pending`; it is not filled from documentation or remembered product behavior.
+`pending` until comparable hands-on evidence exists.

docs/field-lab/runs/README.md

@@ -3,7 +3,7 @@
 | run | status | evidence |
 |---|---|---|
 | codex v4 publication baseline | in progress | added after implementation verification |
-| claude code v4 publication baseline | pending | no current hands-on claim |
+| claude code v4 publication baseline | pending | current hands-on run pending |
 
 run records are immutable observations. corrections add a note or replacement run
 instead of silently changing the original outcome.

docs/field-lab/runs/codex-publication-baseline-2026-08-07.json

@@ -67,7 +67,7 @@
       "evidence": [
         "https://github.com/anipotts/coding-agent-tips/tree/main/docs/decisions"
       ],
-      "notes": "decisions were persisted in signed commits and repository documents; a separate resumed-session recovery was not run"
+      "notes": "decisions were persisted in signed commits and repository documents; resumed-session recovery remains pending"
     },
     {
       "id": "delegated-analysis",
@@ -83,7 +83,7 @@
       "result": "not-run",
       "elapsedSeconds": null,
       "evidence": [],
-      "notes": "the implementation used the existing dedicated branch and checkout; a second worktree was not provisioned"
+      "notes": "the implementation used the existing dedicated branch and checkout; the second-worktree scenario remains pending"
     },
     {
       "id": "final-review",
@@ -145,10 +145,10 @@
     "machine name and account identifiers"
   ],
   "limitations": [
-    "the public run surface did not expose a model identifier",
-    "start time, scenario durations, memory capacity, and review time were not captured and remain null",
-    "token use and cost were not exposed and are not estimated",
-    "delegated analysis and a separate isolated-worktree scenario were not run",
+    "the model identifier was unavailable on the public run surface",
+    "available measurements exclude start time, scenario durations, memory capacity, and review time",
+    "available evidence excludes token use and cost estimates",
+    "delegated analysis and a separate isolated-worktree scenario remain pending",
     "the paired current claude code run remains pending",
     "production hosting, custom-domain behavior, and github metadata are outside this local baseline"
   ]

docs/legacy-tools.md

@@ -12,7 +12,7 @@ evidenceRail:
     section: why-the-tools-are-retiring
     sourceId: anthropic-features-overview
   - kind: unknown
-    label: no automatic migration parity
+    label: manual migration review
     section: migration
 ---
 
@@ -51,7 +51,7 @@ the useful ideas have moved into first-party products or are better expressed as
 - transcript analytics require careful retention, privacy, and schema ownership.
 - resource estimates derived from undocumented client state are fragile.
 
-the plugin code remains useful as an implementation record. it is no longer the public center of the repository.
+the plugin code remains useful as an implementation record. the active guide carries the repository's current direction.
 
 ## migration
 
@@ -62,7 +62,7 @@ the plugin code remains useful as an implementation record. it is no longer the
 | `time` meters | provider usage surfaces and smaller, reviewable task boundaries |
 | safety hooks | current native hooks, sandboxing, permission rules, and managed policy |
 
-there is no automatic migration that preserves every behavior. export any data you want to keep and review it for sensitive content before moving or sharing it.
+migration requires behavior-by-behavior review. export any data you want to keep and review it for sensitive content before moving or sharing it.
 
 ## end of window
 

docs/market/README.md

@@ -21,7 +21,7 @@ evidenceRail:
     section: contender-map
 ---
 
-this appendix helps experienced builders choose an operating environment. it does not rank model benchmark scores.
+this appendix helps experienced builders choose an operating environment through workflow and operating-model evidence.
 
 ## choose the layer first
 
@@ -86,17 +86,17 @@ default: evaluate opencode before building a custom harness. evaluate kimi code,
 | [kimi code](https://www.kimi.com/code/docs/) | terminal and ide harness optimized for kimi models | source-verified watchlist | separate from the Kimi K3 model family |
 | [qwen code](https://github.com/QwenLM/qwen-code) | open-source terminal and ide-friendly harness | source-verified watchlist | separate from Qwen model releases |
 | [grok build](https://docs.x.ai/build/overview) | open-source terminal harness with dashboard and acp support | source-verified watchlist | xai's coding harness; separate from Grok 4.5 |
-| [Kimi K3](https://github.com/MoonshotAI/Kimi-K3) | hosted and open-weight model family | source-verified watchlist | model layer, not an ide |
+| [Kimi K3](https://github.com/MoonshotAI/Kimi-K3) | hosted and open-weight model family | source-verified watchlist | model layer |
 | [Qwen models](https://github.com/QwenLM) | hosted and open-weight model family | source-verified watchlist | model layer, commonly used through Qwen Code or compatible harnesses |
 | [Grok 4.5](https://docs.x.ai/developers/grok-4-5) | hosted xai model | source-verified watchlist | model layer; available through Grok Build, api, and Cursor |
 
-cline and continue are intentionally outside this edition. absence does not imply a negative recommendation.
+cline and continue are outside this edition and remain unevaluated here.
 
 ## xai naming
 
 xai's first-party coding product is [Grok Build](https://docs.x.ai/build/overview), a terminal agent that can also run headlessly or through the Agent Client Protocol. [Grok 4.5](https://docs.x.ai/developers/grok-4-5) is the model used by that harness and is also offered in Cursor.
 
-current primary sources do not establish a separate xai-built Cursor-style editor. describe the harness and model separately until such a product is documented.
+current primary sources establish xai's model and harness layers. evaluate them separately while evidence for an xai-built Cursor-style editor remains absent.
 
 ## costs that pricing pages miss