From ab9b9a60e2de3aba27e938ebd8b75a03af7a35db Mon Sep 17 00:00:00 2001 From: OpenCode Date: Fri, 10 Jul 2026 12:28:06 +0700 Subject: [PATCH] docs: Phase D/F/H ops docs -- agent-safe issue template (D2), stop-condition examples (D6), failed-simulation-as-negative-evidence standard (H7) (#928) --- .../FAILED_SIMULATION_AS_NEGATIVE_EVIDENCE.md | 72 +++++++++++++ docs/operations/AGENT_SAFE_ISSUES.md | 96 +++++++++++++++++ docs/operations/AGENT_STOP_CONDITIONS.md | 101 ++++++++++++++++++ 3 files changed, 269 insertions(+) create mode 100644 docs/FAILED_SIMULATION_AS_NEGATIVE_EVIDENCE.md create mode 100644 docs/operations/AGENT_SAFE_ISSUES.md create mode 100644 docs/operations/AGENT_STOP_CONDITIONS.md diff --git a/docs/FAILED_SIMULATION_AS_NEGATIVE_EVIDENCE.md b/docs/FAILED_SIMULATION_AS_NEGATIVE_EVIDENCE.md new file mode 100644 index 00000000..1593d7a9 --- /dev/null +++ b/docs/FAILED_SIMULATION_AS_NEGATIVE_EVIDENCE.md @@ -0,0 +1,72 @@ +# Failed Simulation Stays Useful as Negative Evidence (H7) + +This document establishes the cultural and procedural standard for treating failed simulation results as first-class negative evidence rather than noise to be discarded. + +## The principle + +A simulation that predicts a candidate will fail is not a broken simulation. It is a result. Discarding failed simulation outputs is equivalent to discarding negative lab results — it distorts the evidence base and makes the pipeline look better than it is. + +Every failed simulation result MUST be recorded, not silently dropped. + +## Why this matters + +### Calibration depends on failure signal + +The calibration loop (BSP → PSC → BOS → CPS → CBA → CRG) requires honest failure rates to detect when the pipeline's predictions diverge from outcomes. If failures are dropped: + +- The observed rejection rate looks lower than it is. +- Calibration updates will overfit to a curated success signal. +- The `FMS-` failure mode similarity report cannot identify repeated failure patterns. + +### Evidence trail integrity + +The proof-ladder and evidence certificates are only meaningful if the negative evidence is as complete as the positive. A certificate that reflects only the candidates that passed screening — without mentioning how many failed — is incomplete and misleading. + +### Anti-selective-reporting + +Selective reporting of simulation results (reporting hits, dropping misses) is the computational equivalent of p-hacking. It inflates apparent discovery rates and misleads downstream decisions. + +## Required behavior + +When a simulation module returns a failed result (low score, below-threshold prediction, error state), the implementer MUST: + +1. **Record a NRR- negative result record** with: + - The candidate ID. + - The simulation module name. + - The reason for rejection (from `VALID_REJECTION_REASONS` in the negative result schema). + - The confidence level. + - `dry_lab_only=True`. + +2. **NOT silently discard** the failed result without recording it. + +3. **NOT retry with different parameters** to get a pass result without logging the initial failure. + +4. **Include the failure count** in any batch-level summary (BOS-, FMS-, NRD- records). + +## What counts as a "useful" failed simulation + +A failed simulation is useful when it: + +- Was run under the same conditions as passing simulations (no special-casing of hard cases). +- Used an explicit rejection criterion (not "it looked bad"). +- Is traceable to a specific candidate ID and pipeline run. +- Has a recorded reason from a controlled vocabulary. + +A failed simulation is NOT useful (and should be flagged, not deleted) when: + +- The failure is due to a software bug, not a biological prediction. +- The input was malformed (not a valid sequence). +- The simulation module itself was in a degraded state (flag in SUC- calibration report). + +## For agents + +An agent processing simulation output MUST NOT: + +- Drop or filter out below-threshold results without writing a NRR-. +- Report only passing results in a batch summary. +- Rerun a simulation on a failing candidate without logging the initial failure. + +An agent MAY: + +- Flag a failed result as a software error (not a prediction) if the module returned an error state. +- Note in the NRR- that the failure was due to module unavailability rather than a biological prediction. diff --git a/docs/operations/AGENT_SAFE_ISSUES.md b/docs/operations/AGENT_SAFE_ISSUES.md new file mode 100644 index 00000000..f13d88e8 --- /dev/null +++ b/docs/operations/AGENT_SAFE_ISSUES.md @@ -0,0 +1,96 @@ +# Agent-Safe Issue Examples (D2) + +This document shows how to write GitHub issues that are safe for agents to pick up and implement without human clarification. + +An agent-safe issue has: +1. A clear, bounded scope (one schema, one test file, one doc). +2. No ambiguity about what "done" means. +3. An explicit statement that the task is dry-lab only and does not touch safety, release, or calibration policy. +4. A test verification step. + +## Template + +```markdown +## Summary + +[One sentence: what schema/test/doc to add and why.] + +## Scope + +- [ ] `src/openamp_foundry//.py` +- [ ] `tests//test_.py` (63 tests) +- [ ] `tests/test_test_count_regression.py` (BASELINE: → ) + +## Acceptance criteria + +- All 63 tests pass: `python -m pytest tests//test_.py -v` +- Schema validates a well-formed record with zero errors. +- Schema rejects at least 5 invalid records with specific error messages. +- `dry_lab_only=True` is enforced. +- `make agent-check` passes. + +## Safety classification + +- [ ] This task does NOT touch safety policy, calibration policy, release status, or proof-ladder thresholds. +- [ ] This task does NOT introduce real (non-toy) candidate data. +- [ ] This task does NOT modify benchmark thresholds. + +## What NOT to do + +- Do not add a CLI command (separate issue). +- Do not modify existing schemas (separate issue). +- Do not change any `BASELINE` value other than the one in `tests/test_test_count_regression.py`. +``` + +## Examples + +### Good: well-scoped schema issue + +```markdown +## Summary + +Add a schema for batch-level rejection summaries (BRS-). Each record summarizes +how many candidates were rejected in a batch and why, linking to NRR- entries. + +## Scope + +- [ ] `src/openamp_foundry/evidence/batch_rejection_summary.py` +- [ ] `tests/evidence/test_batch_rejection_summary.py` (63 tests) +- [ ] `tests/test_test_count_regression.py` (BASELINE: 8410 → 8473) + +## Acceptance criteria + +- BRS- prefix validation +- `total_rejected` and `n_with_nrr` consistency check +- `dry_lab_only=True` enforced +- `make agent-check` passes + +## Safety classification + +- [x] Does not touch safety policy or calibration +- [x] No real candidate data +- [x] No benchmark threshold changes +``` + +### Bad: unsafe or under-specified issue + +```markdown +## Title: Improve the pipeline + +Add some improvements to the scoring pipeline. Maybe add a new model. +Test it and make sure it's better. +``` + +This is unsafe for agents because: +- "Some improvements" is unbounded scope. +- "New model" might touch benchmark thresholds (requires human review). +- "Better" has no measurable criterion. +- No safety classification. + +## Agent behavior on receiving an issue + +An agent that receives an issue should: +1. Check `AGENT_TASKS.json` to classify the task. +2. If the task is in a `forbidden_zone`, stop and request human review. +3. Verify the issue has a safety classification section. +4. If no safety section exists, treat the issue as requiring human review before proceeding. diff --git a/docs/operations/AGENT_STOP_CONDITIONS.md b/docs/operations/AGENT_STOP_CONDITIONS.md new file mode 100644 index 00000000..909fdc81 --- /dev/null +++ b/docs/operations/AGENT_STOP_CONDITIONS.md @@ -0,0 +1,101 @@ +# Agent Stop-Condition Examples (D6) + +This document provides worked examples of when an agent MUST stop and request human review instead of proceeding. See `CLAUDE.md` for the authoritative stop rule. + +## Stop rule (from CLAUDE.md) + +> Stop and request human review if a change touches safety policy, release policy, candidate release, model release, non-toy data, external-facing artifacts, benchmark thresholds, calibration policy, or public scientific claims. + +## Stop-condition taxonomy + +| Category | Example trigger | Why it stops | +|---|---|---| +| Safety policy | Lowering the hemolysis rejection threshold | Changes what gets blocked | +| Release policy | Marking a candidate as "cleared for synthesis" | Irreversible wet-lab consequence | +| Benchmark threshold | Changing `PRECISION_AT_K_THRESHOLD` | Changes what counts as a passing model | +| Calibration policy | Auto-approving a recalibration without audit | Corrupts the learning loop | +| Non-toy data | Introducing real sequences into a schema test | Leaks data before human review | +| Public scientific claims | Strengthening the certainty of an evidence certificate | Claim escalation | +| External artifacts | Modifying a released CERT- or RMF- record | Breaks downstream reproducibility | + +## Worked examples + +### Example 1: Stop on threshold edit + +**Scenario:** An agent is implementing a new precision@k benchmark card. While reading the code, it notices the threshold looks too low and edits `PRECISION_AT_K_THRESHOLD = 0.5` to `0.7`. + +**Why this stops:** Changing a benchmark threshold changes what passes the benchmark. A model that previously had ranking authority would lose it; one that didn't might gain it. This is not a schema-addition task — it is a governance decision. + +**Correct agent behavior:** +``` +STOP CONDITION TRIGGERED: Proposed change to PRECISION_AT_K_THRESHOLD. + +This threshold controls which models have ranking authority. Changing it +affects all current and future benchmark comparisons and requires human review. + +Decision required: Should PRECISION_AT_K_THRESHOLD be changed from 0.5 to 0.7? +Evidence needed: Benchmark results showing current threshold is wrong. + +I have NOT made this change. Leaving a decision-log draft in decision_logs/. +``` + +### Example 2: Stop on proof-ladder upgrade + +**Scenario:** An agent is writing a certificate report. It reads the candidate's scores and notices they are very high. It updates `proof_ladder_level` from `dry_lab_candidate` to `computational_validated`. + +**Why this stops:** Proof-ladder level upgrades are public scientific claims. Moving a candidate up the ladder implies more evidence than may exist. This is a calibration policy and public claim decision. + +**Correct agent behavior:** +``` +STOP CONDITION TRIGGERED: Proposed change to proof_ladder_level. + +Changing a candidate's proof-ladder level changes what the evidence certificate +claims about the candidate. This requires human review. + +I have NOT changed proof_ladder_level. The report uses the existing level. +``` + +### Example 3: Stop on real data introduction + +**Scenario:** An agent is asked to "add more realistic test data." It replaces `TOY-001` with a real sequence from a published AMP database. + +**Why this stops:** Non-toy data in tests requires review before appearing in the codebase. Real sequences may have IP, publication, or privacy constraints. + +**Correct agent behavior:** +``` +STOP CONDITION TRIGGERED: Proposed addition of non-toy candidate data. + +The sequence in the suggested test data does not use a TOY-/MOCK-/EXAMPLE- prefix +and appears to be a real AMP sequence. Adding real sequences requires human review. + +I have NOT added this sequence. All test data uses TOY- prefix. +``` + +## How to write a stop-condition decision log + +When a stop condition fires, leave a decision log draft: + +```markdown +# Decision Log Draft — [brief title] + +**Date:** [date] +**Triggered by:** [what action triggered the stop] + +## What I found + +[Description of the situation] + +## What I did NOT change + +[Explicit list of changes not made] + +## Decision required + +[The specific question a human must answer] + +## Evidence needed + +[What evidence would support a go/no-go decision] +``` + +File this in `decision_logs/` with a descriptive name. Index it in `decision_logs/INDEX.md`.