From 6eb89afcec103277ac78a8680f15dd5c3fab2ced Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Wed, 12 Aug 2026 15:15:08 -0400 Subject: [PATCH] Dedupe CLAUDE.md testing rules into AGENTS.md pointer; untrack agent memory scratch Co-Authored-By: Claude Fable 5 --- .gitignore | 4 +++ CLAUDE.md | 75 ++---------------------------------------------- memory-update.md | 3 -- 3 files changed, 7 insertions(+), 75 deletions(-) delete mode 100644 memory-update.md diff --git a/.gitignore b/.gitignore index 25e13636..ad5d8b0e 100644 --- a/.gitignore +++ b/.gitignore @@ -23,3 +23,7 @@ TEST_LOG.mdtest_logs/nip-hits.txt # Local site archive for manual nsite upload (npm run archive) bitvid-site.zip .env* + +# Agent runtime state (local only) +memory-update.md +memory-update.json diff --git a/CLAUDE.md b/CLAUDE.md index 85967aca..65821079 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,8 @@ This document provides context and guidance for AI assistants working with the bitvid codebase. It explains the project structure, development workflows, conventions, and key architectural decisions. +**Canonical guidance:** `AGENTS.md` is the canonical agent guidance for this repo; `CLAUDE.md` holds Claude-oriented codebase orientation that layers on top of it. + --- ## Project Overview @@ -326,78 +328,7 @@ Resilience invariants — **do not regress**: ## Testing & Validation: Scenario-First, Cheat-Resistant (Dark Factory Rules) -You are operating inside a “Dark Factory” workflow where **validation replaces human code review**. Passing tests is only meaningful if tests are truthful. - -### Prime directive - -**Never alter a test merely to make it pass.** -If you change tests to match buggy behavior, you are destroying the only feedback signal and producing code with no real-world value. - -StrongDM describes the exact failure mode we are preventing: agents discovering shortcuts (“return true”) and narrow tests being reward-hacked, leading to a shift from “tests” to scenario-based validation. - -### How to think about tests here - -Tests are not procedural checklists. They are **behavioral specifications**: -- Write tests as **scenarios** (Given/When/Then or equivalent). -- Assert **externally observable outcomes** at boundaries. -- Avoid “testing the implementation” (internal call sequences, private methods, mirrored logic). -- Prefer deterministic/harmonic execution: fixed seeds, controlled clocks, hermetic IO, virtualized dependencies. - -### Prohibited behaviors (reward-hacking patterns) - -Do NOT: -- weaken assertions, broaden tolerances, or reduce coverage to get green -- update snapshots/goldens without proving the change is intended behavior -- add retries/sleeps/timeouts to hide flakes -- mock so heavily that tests can pass with a broken system -- “hard-code to the test” (single fixtures, single input paths, brittle constants) - -### Allowed test changes: Spec Correction Protocol - -You may change test expectations only if the test is wrong relative to intended behavior. - -Required steps: -1) Identify the scenario/spec that defines correct behavior. -2) Explain why the previous expectation was incorrect. -3) Replace it with an equally strict (or stricter) behavioral assertion. -4) Provide a **Test Integrity Note** (machine-readable) documenting the change. - -If you cannot justify a change with scenario/spec truth: **do not change the test**. Instead, output a “Needs Spec Clarification” note and propose candidate scenarios. - -### Required output when you touch tests - -Include this YAML block in your PR description (or reference it from a `TEST_INTEGRITY.md` entry): - -```yaml -test_integrity_note: - change_type: ["new_tests" | "refactor_tests" | "spec_correction" | "flake_fix"] - scenarios: - - id: SCN- - given: "" - when: "" - then: "" - observable_outcomes: - - "" - determinism_controls: - - "" - anti_cheat_rationale: - prevents: - - "hard-coded return value" - - "over-mocking internal logic" - - "snapshot rubber-stamping" - - "retry/sleep-based flake masking" - relaxation: - did_relax_any_assertion: false - if_true_explain_spec_basis: "" -``` - -### If external services are involved - -Prefer boundary-level service virtualization (“digital twins” / behavioral clones) so scenario tests remain: -- high fidelity (realistic edge cases) -- deterministic and replayable -- not rate-limited / not flaky -(StrongDM’s “Digital Twin Universe” is the reference pattern.) +The testing and validation rules are canonical in `AGENTS.md` — see its "Testing & Validation" section, §16 "Scenario-First Tests & Test Integrity (Dark Factory Standard)". In short: validation replaces human code review here, tests are behavioral scenarios that assert externally observable outcomes at boundaries, and you must **never alter a test merely to make it pass** — expectation changes are allowed only via the Spec Correction Protocol with an accompanying Test Integrity Note. Read AGENTS.md §16 in full before adding or modifying any test. --- diff --git a/memory-update.md b/memory-update.md deleted file mode 100644 index d4a36b87..00000000 --- a/memory-update.md +++ /dev/null @@ -1,3 +0,0 @@ -- The `docs-code-investigator` successfully analyzed and documented `js/historyView.js`. -- JSDoc annotations were appended to the `js/historyView.js` public API to adhere to the strict `no-behavioral-changes` constraint. -- A comprehensive overview markdown file was successfully created at `docs/historyView-overview.md`. \ No newline at end of file